Actor

 
Defined in Kernel.Def
Inherits from SingleLinkable      

Class Description

To be written.

Remember that if the documentation and the software (especially the definition files) disagree, always trust the software.

Programming information

Instantiate: rarely
Subclass: sometimes
Call its methods:rarely

Magic Cap has two built-in actors that

If your package doesn't use any custom actors, all of your code runs on the user actor.

If your package has any lengthy or computationally intensive operations, you should consider moving them onto their own actor. Magic Cap can't process user input if your code is in the middle of an intense calculation on the user actor thread. How long is lengthy? To answer that question, consider what your user's experience is going to be. If the operation takes a few seconds, you should at least call DriveBusyCursor to spin the hat. If your operation takes much longer than that, setting up a separate actor would be more appropriate.

Remember that you can't make calls that might change the screen from any thread other than the user actor. For example, you can't call RedrawNow or Draw from another actor. If you need to make calls like these from your actor, use RunSoon. You might call RunSoon like this:

RunSoon(true, (CompletionFunction) DrawSomeStuff, &parameters->header);

Methods defined by class Actor

Class Actor defines the following methods:

Method	Description
CallWithStack	Call a function with a particular stack
CheckInterruption	Check if this actor should be interrupted
CurrentExceptionReason	cover for setter that includes the boot reason if we failed early enough in
SetCurrentExceptionReason	boot that no actors are yet running
Destroy	Overridden to
FailSoon	Make this actor fail soon with the given exception
Finalize	Overridden to remove the actor from the scheduler and release all semaphores
GrowContextStack	grow context stack of this actor
Init	Overridden to set up the actor and its stack and to add it to the scheduler
Install	Overridden to
Main	The main action of the actor
Resume	Run this actor (this is a BAD comment)
SetInterruptionCheck	Set the function to poll to check if this actor should be interrupted
StackFree	Get the number of bytes of free space on stack
Suspend	Tell this actor it shouldn't run until Resume is called on it
SwitchingStateChanged	The system is going to suspend or run this actor for some period of time (bad comment)
SwitchTo	Switch from this actor to the given actor
Wait	Wait for a semaphore

Methods you might override

You might override these methods in the following circumstances:

Method	When to override
Main

Fields defined by class Actor

Class Actor defines the following fields:

Field	Type	Description
Inherited from SingleLinkable
next	Object	The next actor in the ready queue
Defined by Actor
status	UnsignedShort
priority	SignedShort
waitingFor	Semaphore
state	Pointer
stackSegment	ProcessorStackSegment
stackSegmentSize	Unsigned
exceptionStack	ExceptionStack
exceptionStackPointer	Unsigned
contextStack	ContextStack
contextStackPointer	Unsigned
process	Process	The telescript process or agent
		associated with this actor
context	Context	The current cluster context associated
		with this actor
interruptCheck	Function
forUser	Boolean	True if this actor affects the user
		interface by drawing or accepting
		input';
exception	Object
exceptionReason	Unsigned
globals	Object
suspendLevel	Unsigned

If any of the fields need to be filled out in any particular way, describe them here. You might want to put some object examples here, too.

Attributes defined by class Actor

Class Actor defines the following attributes:

Attribute	Type	Definition
Status	UnsignedShort	status of actor
WaitingFor	Semaphore	semaphore that this actor is waiting for
Process	Process	telescript process corresponding to this Actor
Priority	Signed	default should be 0, and lower is more important. range
		should be [0,1024] for packages.
ForUser	Boolean	can it interact with the user?
ExceptionReason	Unsigned	reason for the current exception
Suspended	Boolean	used by scheduler to decide whether this actor is
		temporarily persona non grata

Constants or Flags used by class Actor

Actor Status Constants

Status	Value	Description
kDying	0	The actor is being destroyed
kRunning	1	The actor is currently executing
kReady	2	The actor is in the queue of actors to be run
kWaiting	3	The actor is waiting to acquire a semaphore

Actor priorities

Priority	Value	Description
kLowPriority	-8
kNormalPriority	0
kHighPriority	8

Method Descriptions

CallWithStack

Call: sometimesOverride: rarely

Call CallWithStack to call the given function with its own stack. Use CallWithStack for functions that use more stack space than your actor has free in its stack.

Here's an example of how you might use CallWithStack:

CallWithStack((CallWithStackFunction)MyBigFunction, 
              &params, 0x1000);

FailSoon

Call: sometimesOverride: rarely

Call FailSoon to make this actor fail with the given exception. You might call FailSoon if you're using more than one actor and you want to make one actor throw a particular exception while your code is running on another.

Make sure the actor you want to throw the exception does not have access to any semaphores. If it does, a deadlock will result, and Magic Cap will appear to stop. You can avoid this problem by using a fail-safe semphore instead of a regular semaphore.

Main

Call: rarelyOverride: often

// subclasses override this to change main action of an actor

things to always do, things to never do

Priority

SetPriority

Call: sometimesOverride: rarely

Call Priority to get an actor's priority level and SetPriority to set it. If SetPriority changes the priority of an actor, it also adjusts its position on the ready queue.

The priority should be in the range from 0 to 1024. Lower priorities are more important. Actors in packages are created with priority 0 by default.

default should be 0, and lower is more important. range should be [0,1024] for packages.

Resume

Call: sometimesOverride: rarely

let loose the running furies

StackFree

Call: sometimesOverride: rarely

Status

Call: sometimesOverride: rarely

status of actor