"

 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 creatorId processGroupId

		interruptsDisabled priorityRange exceptionHandlerSet processType'

	classVariableNames:'TerminateSignal RestartSignal 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).

    Smalltalk processes do not nescessarily need to be implemented as native

    threads - it may, but the actual implementation depends on the underlying

    OS'S features. However, even if implemented as native thread, the ST/X

    kernel makes certain, that only one thread executes at a time (with certain,

    well-defined exceptions). The reason is that the reqiored locking in the

    runtime system would make things slower in most cases.

    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.

    In ST/X, the scheduling algorithms are fully implemented (and visible) on the

    smalltalk level - beside the threadSwitch primitive, there is virtually no VM

    support (i.e. it can be easily changed).

    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 caught for special cleanup or

    even to make the process continue execution.

    If the process is suspended at termination time, it will be resumed

    in order to perform its cleanup actions (i.e. the cleanup is always 

    done in the context of the terminating process itself).

    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).

    Leaving the processes startBlock has the same effct as a soft-terminate

    (i.e. there is no need to send an explicit terminate).

    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.

    Process states:

        #dead           process has (been) terminated;

                        the process instance has no underlting

                        thread.

        #run            the process is willing to run,

                        but not active (i.e. another higher prio

                        process is currently executing)

        #active         the process is the current process

                        (there is only one)

        #ioWait         waiting on some io-related semaphore

                        (typically in #readWait / #writeWait)

        #eventWait      waiting on some GUI event

        #timeWait       waiting on a timer-related semaphore

        #wait           waiting on some (other) semaphore

        #suspended      stopped from execution; however, an interrupt

                        will return it into the run state.

        #stopped        stopped from execution; an interrupt will

                        NOT return it into the run state (for debugging)

        #debug          debugger sitting on top of the processes

                        stack.

    Win32 only:

        #osWait         waiting on an OS-API call to finish.

                        can be interrupted, terminated and aborted

                        (i.e. the usual context actions are is possible).

        #halted         thread was cought while in a blocking API call

                        or primitive endless loop and has been halted by

                        the scheduler.

                        Can only be resumed or hard-terminated - abort

                        or soft terminate or unwind actions are not possible.

                        (due to win32 limitations)

    [Instance variables:]

        id                     <SmallInteger>   a unique process-id

        creatorId              <SmallInteger>   the id of the process that

                                                created me (useful for debugging

                                                or monitoring).

        processGroupId                          usually the id of the creator,

                                                unless the process detached from

                                                the group and became a groupLeader.

                                                Groups can be easily terminated

                                                as a whole.

                                                Group leaders have a groupId of nil.

                                                A groupId of 0 (zero) marks a system

                                                process; these do not prevent a standAlone

                                                app from exiting.

        prio                   <SmallInteger>   the processes priority

        priorityRange          <Interval>       the processes dynamic priority range

                                                (or nil)

        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; if true, the process

                                                will be restarted when an image is

                                                restarted. Otherwise, it remains dead.

                                                Running processes cannot be continued

                                                at the point where leftOff after an 

                                                image-restart.

        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

        interruptsDisabled     <Boolean>        flag if interrupts (as installed

                                                via #interruptWith:) are currently

                                                disabled. (i.e. on-hold).

                                                Interrupts will be delivered when

                                                reenabled.

        exceptionHandlerSet    <ExceptionhandlerSet>

                                                Handled by any process; allows for

                                                exceptionHandlers and query-answerers to

                                                be added/removed dynamically.

    [Class variables:]

        TerminateSignal         <Signal>        signal used to terminate processes

                                                (should not be caught - or at least

                                                 rejected in handlers).

                                                If caught and proceeded, a process

                                                cannot be terminated via #terminate.

                                                For hardTermination (in case of emergency),

                                                send it a #erminateNoSignal message.

        RestartSignal           <Signal>        signal used to restart a process.

                                                Can be caught in additional handler(s),

                                                to perform all kind of re-initialization.

                                                However, these handlers should reject,

                                                for the restart to be really performed.

    [see also:]

        ProcessorScheduler

        Block

        Sempahore SemaphoreSet Delay SharedQueue

        WindowGroup

        (``Working with processes'': programming/processes.html)

    [author:]

        Claus Gittinger

"

!

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.

                                                                        [exBegin]

    [

       'starting' printNL.

       100 timesRepeat:[1000 factorial].

       'done with factorial' printNL.

    ] forkAt:(Processor userBackgroundPriority).

                                                                        [exEnd]

    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. 

                                                                        [exBegin]

    [

       'starting' printNL.

       100 timesRepeat:[1000 factorial].

       'done with factorial' printNL.

    ] forkAt:1.

                                                                        [exEnd]

    start a background process, reading a pipe without blocking other

    processes;

                                                                        [exBegin]

    [

       |p|

       'starting' printNL.

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

       [p atEnd] whileFalse:[

           p readWait.

           p nextLine printNL.

       ].

       p close.

       'done with pipe' printNL.

    ] forkAt:1.

                                                                        [exEnd]

    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'.

        RestartSignal := Signal new mayProceed:true.

        RestartSignal nameClass:self message:#restartSignal.

        RestartSignal notifierString:'unhandled process restart'.

        CoughtSignals := SignalSet 

                            with:AbortSignal 

                            with:TerminateSignal

                            with:RestartSignal.

    ]

    "Modified: 28.10.1996 / 20:39:05 / cg"

! !

!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 basicNew for:aBlock priority:aPrio

    "Modified: 25.1.1997 / 01:23:12 / cg"

!

new

    "create a new (unscheduled) process which will execute the start

     method, when scheduled. The process will start execution once

     it gets a #resume-message."

    ^ self basicNew for:nil priority:(Processor activePriority).

    "Created: 25.1.1997 / 01:31:05 / cg"

! !

!Process class methodsFor:'Signal constants'!

restartSignal

    "return the signal used for process restart"

    ^ RestartSignal

    "Created: 28.10.1996 / 20:26:50 / cg"

!

terminateSignal

    "return the signal used for process termination"

    ^ TerminateSignal

! !

!Process class methodsFor:'defaults'!

defaultMaximumStackSize

    "return the default max stack size. All new processes get

     this limit initially. 

     It may be changed for individual processes with: 

        aProcess setMaximumStackSize:limit"

%{  /* NOCONTEXT */

    RETURN ( __MKSMALLINT( __defaultThreadMaxStackSize() ));

%}

    "

     Process defaultMaximumStackSize

    "

    "Modified: 8.5.1996 / 10:22:24 / cg"

!

defaultMaximumStackSize:numberOfBytes

    "set the default max stack size, return the previous value. 

     All new processes get this stack limit initially. 

     It may be changed for individual processes with: 

        aProcess setMaximumStackSize:limit

     Notice:

        There is seldom any need to change the default setting,

        except for highly recursive programs."

%{  /* NOCONTEXT */

    if (__isSmallInteger(numberOfBytes)) {

        RETURN ( __MKSMALLINT( __setDefaultThreadSetMaxStackSize(__intVal(numberOfBytes)) ));

    }

%}

    "

     Process defaultMaximumStackSize:500*1024

    "

    "Modified: 8.5.1996 / 10:23:26 / cg"

! !

!Process class methodsFor:'instance retrieval'!

findProcessWithId:id

    "return a process with a particular id.

     This is only a debugging helper, to allow

     easy access of a process by name in the MiniDebugger"

    self allSubInstances do:[:aProcess | aProcess id = id ifTrue:[^ aProcess]].

    ^ nil

    "

     Process findProcessWithId:1

    "

    "Modified: / 26.8.1998 / 15:39:55 / cg"

!

findProcessWithName:name

    "return a process with a particular name.

     This is only a debugging helper, to allow

     easy access of a process by name in the MiniDebugger"

    self allSubInstances do:[:aProcess | aProcess name = name ifTrue:[^ aProcess]].

    ^ nil

    "

     Process findProcessWithName:'scheduler'

    "

    "Modified: / 26.8.1998 / 15:40:54 / cg"

! !

!Process methodsFor:'Compatibility - V''Age'!

queueInterrupt:aBlock

    "VisualAge compatibility: alias for #interruptWith:

     arrange for the receiver process to be interrupted and

     evaluate aBlock in its interrupt handler."

    ^ self interruptWith:aBlock

    "Created: 15.11.1996 / 11:41:06 / cg"

! !

!Process methodsFor:'accessing'!

beGUIProcess

    "mark the receiver as a gui process.

     This is currently not used, but allows end-user applications

     to terminate all subprocesses which are GUI related, and leave

     other background processes in the same process group untouched."

    processType := #gui

!

beGroupLeader

    "make the receiver a processGroupLeader.

     This detaches the process from its creator, so that it will not

     be terminated when it teminates via #terminateGroup.

     (windowgroup processes do this)."

    processGroupId := id

    "Modified: 8.7.1996 / 14:00:35 / cg"

    "Created: 8.7.1996 / 14:08:44 / cg"

!

beSystemProcess

    "make the receiver a system process.

     These processes have a groupId of 0.

     When executed as standAlone application, smalltalk exits when

     no more user processes are running.

     To prevent any daemon processes from preventing this exit,

     you should make the systemProcess"

    processGroupId := 0

    "Created: 17.1.1997 / 21:42:46 / cg"