Actor

BuryActor CallWithStack CheckInterruption CurrentExceptionReason DestroyActor DestroyStackSegment DestroyUnusedStackSegments EachPotentialObjectInStack

FailSoon Finalize IndexicalForActor Init Main NewStackSegment ReinitializeClass Resume

SetCurrentExceptionReason SetInterruptionCheck StackFree Suspend SwitchTo SwitchingStateChanged WaitForSemaphore

Attributes

Exception ExceptionReason ForUser Priority Status Suspended WaitingFor

Fields

Define Class Actor;
    abstract;
    inherits from Object;                       

    field status: UnsignedShort, getter;
        // may be one of: kDying, kRunning, kReady, kWaiting
    field priority: SignedShort, getter;
        // default is 0, higher number means higher priority
        // default scheduler is strict priority-based with
        // round-robin within same priority level 
    field waitingFor: Semaphore, weak, getter, setter;
        // this is the object (usually) semaphore that
        // the actor is waiting upon

    field state: Pointer;                   
        // saved CPU state for actors that are not running
    
    field stackSegment: Pointer;
    field stackSegmentSize: Unsigned;
        // top CPU stack in chain
    
    field exceptionStack: Pointer;
    field exceptionStackPointer: Unsigned;              
        // offset in bytes, or truly a pointer if this is the current actor
    
    field interruptCheck: Function;                 
        // call function to check for interrupt
    field forUser: Boolean, getter, setter;
        // is this an actor that affects the user interface
        // (i.e. taking input or drawing)
    
    field exception: Object, getter, setter;        
        // should be 0, except for after _FailSoon
    field exceptionReason: Unsigned, getter, setter;    
        // reason we got this exception
    
    field suspendLevel: Unsigned;                   
        // if 0 we are able to run, if higher we will run when resumed

#ifdef MIPS_RUNTIME
#ifndef DEBUG
    field dispatcherTimingBuffer: Unsigned;     
        // points to a buffer of dispatcher timing statistics
        // This field is only used if MIPS_DISPATCHER_TIMING is
        // defined, but we don't use that conditional here because we
        // want the Actor objects to be the same size on release and
        // final builds.
#endif
#endif

    intrinsic StackFree(): Unsigned;                    
        // free space on stack (in bytes)
    intrinsic CallWithStack(function: CallWithStackFunction; parameters: Pointer; requiredStack: Unsigned): Object;

    operation Main(parameters: Pointer), noMethod;          
        // subclasses override this to change main action of an actor

    attribute Status: UnsignedShort;                    
        // status of actor
    operation SwitchTo(toActor: Actor), noFail;         
        // call this to switch
    operation WaitForSemaphore(forObject: Semaphore), noFail;       
        // call this to wait for a semaphore (scheduler does the work)
    attribute WaitingFor: Semaphore;                    
        // semaphore that this actor is waiting for

    attribute Priority: SignedShort;                            
        // default is 0, higher number means higher priority
        // default scheduler is strict priority-based with
        // round-robin within same priority level 
    attribute ForUser: Boolean;                         
        // can it interact with the user?

    class operation CheckInterruption();                        
        // check for interruption; fail if there is some
    class operation SetInterruptionCheck(check: Function);
        // pass a function to poll if this actor
        // should be interrupted.  the function may do
        // so be calling Fail.
    operation FailSoon(exception: Object), intrinsic;   
        // make this actor fail soon w/ given exception
    attribute Exception: Object;                
        // should be 0, except for after _FailSoon
    attribute ExceptionReason: Unsigned;                
        // reason for the current exception
    intrinsic CurrentExceptionReason(): Unsigned;       
        // cover for getter that includes the boot reason
    intrinsic SetCurrentExceptionReason(reason: Unsigned);
        // cover for setter that includes the boot reason if we
        // failed early enough in boot that no actors are yet running
    operation SwitchingStateChanged(disabled: Boolean);
        // the system is going to suspend/run this actor for some period of time

    operation Suspend();
        // tell this actor it should not run until resumed; nestable
        // if called on self, will suspend and RunNext (another Actor must Resume)
    operation Resume();
        // let loose the running furies
    attribute Suspended: Boolean, readOnly;
        // used by scheduler to decide whether this actor is temporarily persona non grata

    operation DestroyActor();
        // call to destroy an actor with proper clean-up
        // it is an error to call Destroy on an actor directly

    overrides ReinitializeClass, Init, Finalize;
        // overridden to maintain internal state of the actor,
        // its stack segments, semaphores, and of the default scheduler
    
    operation EachPotentialObjectInStack(function: EachFunction; parameters: Pointer): Object;
        // call to look through the stack for all potential object references
        // used by the system for garbage collection

    operation IndexicalForActor(indexical: Object): Object;
        // call to find out the value of <indexical> for this actor
        // this level returns <indexical>
        // override rarely to change the value of the indexical
        // **WARNING** This is a yicky necessity to make faxing multiple cards with
        // attribute text work. It is not recommended for normal use.

    operation BuryActor(), intrinsic;
    
    intrinsic NewStackSegment(stackSize: Unsigned; next: Pointer): Pointer;
    intrinsic DestroyStackSegment(stackSegment: Pointer);
    intrinsic DestroyUnusedStackSegments();

end class;