"

 COPYRIGHT (c) 1992 by Claus Gittinger

	      All Rights Reserved

 This software is furnished under a license and may be used

 only in accordance with the terms of that license and with the

 inclusion of the above copyright notice.   This software may not

 be provided or otherwise made available to, or used by, any

 other person.  No title to or ownership of the software is

 hereby transferred.

"

Link subclass:#Process

	instanceVariableNames:'id prio state startBlock name restartable interruptActions

		exitActions suspendSemaphore singleStepping

		emergencySignalHandler suspendActions'

	classVariableNames:'TerminateSignal CoughtSignals'

	poolDictionaries:''

	category:'Kernel-Processes'

!

!Process class methodsFor:'documentation'!

copyright

"

 COPYRIGHT (c) 1992 by Claus Gittinger

	      All Rights Reserved

 This software is furnished under a license and may be used

 only in accordance with the terms of that license and with the

 inclusion of the above copyright notice.   This software may not

 be provided or otherwise made available to, or used by, any

 other person.  No title to or ownership of the software is

 hereby transferred.

"

!

documentation

"

    Instances of Process represent lightweight smalltalk processes 

    (i.e. threads). These all run in a shared smalltalk/X address space,

    and can thus access and communicate via any objects.

    Do not confuse these with (heavy-weight) unix processes, which are

    created differently, and do NOT run in the same address space.

    Also notice, that heavy-weight process creation takes much longer.

    (see OperatingSystemclass>>fork).

    Processes are typically created by sending #fork or #forkAt: to a block;

    the block creates a new process, defines itself as its startBlock,

    and (optionally) tells the Processor about the new process.

    Scheduling is done by Processor, which is the sole instance of 

    ProcessorScheduler.

    Processes can be terminated either soft or via a hardTerminate.

    A soft terminate (see Process>>terminate) will raise a TerminationSignal

    in the process, which can be handled by the process. 

    If no other handler was specified, the processes own handler 

    (see Process>>start) will catch the signal and terminate the process. 

    During this signal processing, normal unwind processing takes place,

    this means that with a soft terminate, all valueOnUnwind:/valueNowOrOnUnwind: 

    cleanup blocks are evaluated.

    (so a process which has set up those blocks correctly does not have to

     care especially about cleanup in case of termination).

    Other than that, the TerminateSignal can be cought for special cleanup or

    even to make the process continue execution.

    A hard terminate (Process>>terminateNoSignal) will NOT do all of the above,

    but quickly (and without any cleanup) terminate the process.

    The debugger offers a quickTerminate option on its popupMenu for

    situations, when soft termination fails. (for example, if some error was

    coded into a handler or unwind block).

    Notice: 

        in Smalltalk/X, processes are gone, when an image is restarted;

        this means, that you have to take care of process re-creation yourself.

        Usually, this is done by depending on ObjectMemory, recreating the

        process(es) when the #returnFromSnapshot-change notifiction arrives.

        All views (actually windowGroups) recreate their window process

        on image-restart. You have to do so manually for your own processes.

    A later version will allow specification of automatic restart, but

    thats not yet implemented. However, even when implemented, restartable processes

    will be recreated to restart from the beginning. It will not be possible to

    automatically continue a processes execution where it left off.

    This is a consequence of the portable implementation of ST/X, since in order to

    implement process continuation, the machines stack had to be preserved and 

    recreated.  Although this is possible to do (and actually not too complicated), 

    this has not been implemented, since the machines stack layout is highly machine/compiler 

    dependent, thus leading to much bigger porting effort of ST/X (which conflicts

    with ST/X's design goal of being highly portable).

    Process synchronization:

        Synchronization with cooperating processes is supported as usual,

        via Semaphores (see Semaphore, Delay, SharedQueue etc.)

        With uncooperative processes, only synchronization on suspend

        and termination is possible:

          any other process can wait for a process to suspend or terminate. 

          This waiting is implemented by using suspendSemaphore and exitBlocks

          (where an exitSemaphore is signalled).

          See waitUntilSuspended / waitUntilTerminated.

    [Instance variables:]

        id                     <SmallInteger>   a unique process-id

        prio                   <SmallInteger>   the processes priority

        state                  <Symbol>         the processes state

                                                (for process-monitor)

        startBlock             <Block>          the startup-block (the one that forked)

        name                   <String-or-nil>  the processes name (if any)

                                                (for process-monitor)

        suspendSemaphore       <Semaphore>      triggered when suspend (if nonNil)

        restartable            <Boolean>        is restartable (not yet implemented)

        interruptActions       <Collection>     interrupt actions as defined by interruptWith:,

                                                performed at interrupt time

        exitActions            <Collection of Block>          

                                                additional cleanup actions to perform 

                                                on termination (if nonEmpty)

        emergencySignalHandler <Block>          can be used for per-process

                                                emergency signal handling

    [Class variables:]

        TerminateSignal         <Signal>        signal used to terminate processes

                                                (should not be cought - or at least

                                                 rejected in handlers)

    [see also:]

        ProcessorScheduler

        Block

        Sempahore SemaphoreSet Delay SharedQueue

        WindowGroup

"

!

examples 

"

    start a background process, computing 1000 factorial 100 times;

    the processes priority is set to not disturb any interactive process.

    Since its prio is higher than the 3D animation demos prio, you will notice,

    that those are suspended while the computation runs. But Interactive views

    (like browsers) will continue to react normal.

    [

       'starting' printNL.

       100 timesRepeat:[1000 factorial].

       'done with factorial' printNL.

    ] forkAt:(Processor userBackgroundPriority).

    start a background process, computing 1000 factorial 100 times;

    the processes priority is set to not disturb any process.

    The prio is set to 1 (which is the lowest possible) notice that now,

    the 3D animation demos also continue to run. 

    [

       'starting' printNL.

       100 timesRepeat:[1000 factorial].

       'done with factorial' printNL.

    ] forkAt:1.

    start a background process, reading a pipe without blocking other

    processes;

    [

       |p|

       'starting' printNL.

       p := PipeStream readingFrom:'ls -lR .'.

       [p atEnd] whileFalse:[

	   p readWait.

	   p nextLine printNL.

       ].

       p close.

       'done with pipe' printNL.

    ] forkAt:1.

    see more examples in doc/coding 

    (or search in the browser for senders of fork*)

"

! !

!Process class methodsFor:'initialization'!

initialize

    TerminateSignal isNil ifTrue:[

	TerminateSignal := Signal new mayProceed:true.

	TerminateSignal nameClass:self message:#terminateSignal.

	TerminateSignal notifierString:'unhandled process termination'.

	CoughtSignals := SignalSet with:AbortSignal with:TerminateSignal.

    ]

! !

!Process class methodsFor:'instance creation'!

for:aBlock priority:aPrio

    "create a new (unscheduled) process which will execute aBlock at

     a given priority, once scheduled. The process will start execution once

     it gets a #resume-message."

    ^ self new for:aBlock priority:aPrio

! !

!Process class methodsFor:'Signal constants'!

terminateSignal

    "return the signal used for process termination"

    ^ TerminateSignal

! !

!Process methodsFor:'accessing'!

changePriority:aNumber

    "same as priority:, but returns the old priority.

     (cannot do this in #priority: for ST-80 compatibility)"

    |oldPrio|

    oldPrio := prio.

    Processor changePriority:aNumber for:self.

    ^ oldPrio

    "Modified: 23.12.1995 / 18:38:53 / cg"

!

id

    "return the processes id"

    ^ id

!

name

    "return the processes name"

    ^ name

!

name:aString

    "set the processes name"

    name := aString

!

priority

    "return the receivers priority"

    ^ prio

!

priority:aNumber

    "set my priority"

    Processor changePriority:aNumber for:self.

!

restartable:aBoolean

    "set/clear, the restartable flag.

     Restartable processes will automatically be restarted by the

     ProcessorScheduler upon image restart. 

     Others have to be restarted manually."

    startBlock isNil ifTrue:[

        self error:'cannot be made restartable when already started'.

        ^ self

    ].

    restartable := aBoolean

    "Modified: 23.12.1995 / 18:38:32 / cg"

!

singleStep:aBoolean

    singleStepping := aBoolean

!

startBlock

    "return the processes startup-block"

    ^ startBlock

!

state

    "return a symbol describing the processes state"

    ^ state

!

state:aSymbol

    "set the state - only to be used from scheduler"

    state := aSymbol

!

suspendedContext

    "return the processes suspended context 

     - this is the context from which a process switch into the scheduler

     or another process occured.

     Typically, only the debugger is interested in this one."

%{  /* NOCONTEXT */

    OBJ i;

    if (__isSmallInteger(i = __INST(id))) {

	RETURN (__threadContext(__intVal(i)));

    }

%}.

    ^ nil

! !

!Process methodsFor:'accessing-change notifications'!

emergencySignalHandler

    "return the emergencySignalHandler block.

     See Signal>>documentation for more info."

    ^ emergencySignalHandler

!

emergencySignalHandler:aOneArgBlock

    "set the emergencySignalHandler block.

     See Signal>>documentation for more info."

    emergencySignalHandler := aOneArgBlock

!

exitAction:aBlock

    "add aBlock to the processes exit actions.

     This block will be evaluated right before the process dies.

     An argument of nil clears removes all exitActions."

    aBlock isNil ifTrue:[

	exitActions := nil.

	^ self.

    ].

    exitActions isNil ifTrue:[

	exitActions := OrderedCollection new

    ].

    exitActions add:aBlock

    "Modified: 13.12.1995 / 13:44:03 / stefan"

!

suspendAction:aBlock

    "add aBlock to the processes suspend actions.

     This block will be evaluated when a process gets suspended.

     A nil argument removes all suspendActions."

    aBlock isNil ifTrue:[

	suspendActions := nil.

	^ self.

    ].

    suspendActions isNil ifTrue:[

	suspendActions := OrderedCollection new

    ].

    suspendActions add:aBlock

    "Created: 13.12.1995 / 13:35:54 / stefan"

    "Modified: 13.12.1995 / 13:44:31 / stefan"

! !

!Process methodsFor:'accessing-stack'!

maximumStackSize

    "returns the processes stack limit - i.e. the process will be 

     interrupted with a recursionSignal-raise, if it ever

     needs more stack (in bytes) than this number"

%{  /* NOCONTEXT */

    extern int __threadMaxStackSize();

    OBJ i;

    if (__isSmallInteger(i = __INST(id))) {

	RETURN( __MKSMALLINT(__threadMaxStackSize(__intVal(i))) );

    }

%}.

    ^ nil

!

setMaximumStackSize:limit

    "sets the processes stack limit - i.e. the process will be

     interrupted with a recursionSignal-raise, if it ever

     needs more stack (in bytes) than this number.

     Returns the old value."

%{  /* NOCONTEXT */

    extern int __threadSetMaxStackSize();

    OBJ i;

    if (__isSmallInteger(i = __INST(id)) 

     && __isSmallInteger(limit) ) {

	RETURN ( __MKSMALLINT(__threadSetMaxStackSize(__intVal(i), __intVal(limit))) );

    }

%}.

    ^ nil

!

setStackInitialSize:initial increment:increment safe:safe

    "hook for fine-tuning. Sets the processes initialStackSize- and

     and stackIncrement-parameters. Not for normal use."

%{  /* NOCONTEXT */

    extern int __threadSetJunkSizes();

    OBJ i;

    if (__isSmallInteger(i = __INST(id))

     && __isSmallInteger(initial)

     && __isSmallInteger(increment)

     && __isSmallInteger(safe)) {

	RETURN ( __threadSetJunkSizes(__intVal(i), __intVal(initial), __intVal(increment), __intVal(safe)) ? true : false );

    }

%}.

    ^ false

! !

!Process methodsFor:'interrupts'!

addInterruptAction:aBlock 

    "make the receiver evaluate aBlock when resumed/interrupted.

     The name is somewhat misleading (actually, its historic):

     the block is also evaluated on resume."

    self uninterruptablyDo:[

        interruptActions isNil ifTrue:[

            interruptActions := OrderedCollection with:aBlock.

        ] ifFalse:[

            interruptActions addLast:aBlock.

        ].

    ].

    "Created: 5.3.1996 / 17:10:10 / cg"

    "Modified: 8.3.1996 / 13:03:10 / cg"

!

forceInterruptOnReturnOf:aContext

    "helper entry for debugger. Force a stepInterrupt whenever aContext

     returns either directly or via an unwind."

    aContext markForUnwind.

%{

    OBJ i;

    if (__isSmallInteger(i = __INST(id))) {

	__threadContextStepInterrupt(__intVal(i), 1);

    }

%}

!

interrupt

    "evaluate my interrupt-actions.

     The process will go back to where it got interrupted

     after doing this."

    |action|

    [interruptActions size > 0] whileTrue:[

        self uninterruptablyDo:[

            action := interruptActions removeFirst

        ].

        action value

    ].

    interruptActions := nil

    "Modified: 12.4.1996 / 12:43:31 / cg"

!

interruptWith:aBlock

    "interrupt the receiver and make it evaluate aBlock.

     If the receiver is currently suspended it is resumed."

    self addInterruptAction:aBlock.

    Processor scheduleForInterrupt:self.