"

 COPYRIGHT (c) 1992 by Claus Gittinger

 COPYRIGHT (c) 2016 Jan Vrany

	      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.

"

"{ Package: 'stx:libbasic' }"

"{ NameSpace: Smalltalk }"

Link subclass:#Process

	instanceVariableNames:'id lookupActivations lookupDisabled prio state startBlock name

		restartable interruptActions exitActions suspendSemaphore

		singleStepping emergencySignalHandler suspendActions creatorId

		processGroupId interruptsDisabled priorityRange

		exceptionHandlerSet processType environment startTimestamp'

	classVariableNames:'TerminateSignal RestartSignal CaughtSignals SysProcessId'

	poolDictionaries:''

	category:'Kernel-Processes'

!

!Process class methodsFor:'documentation'!

copyright

"

 COPYRIGHT (c) 1992 by Claus Gittinger

 COPYRIGHT (c) 2016 Jan Vrany

	      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

"

    WARNING:

        the offsets of the instance variables lookupActivations and lookupDisabled are known in the VM

        do not remove them, and do not insert/remove instance variables before them

    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 required 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 effect 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

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

    Implementation note:

        for historic and compatibility reasons, Process is a subclass of Link,

        which means, that instances are directly usable as nodes in a linkedList.

        However, this also means, that processes can only be elements of a single LinkedList.

        This is somewhat dangerous, as unknowledgable programmers may unwillingly break the

        scheduler, by placing a process onto another linked list.

        Therefore, we plan to change this in the future.

    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 caught 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 := TerminateProcessRequest.

	TerminateSignal notifierString:'unhandled process termination'.

	RestartSignal := RestartProcessRequest.

	RestartSignal notifierString:'unhandled process restart'.

	CaughtSignals := SignalSet

			    with:AbortAllOperationRequest

			    with:TerminateProcessRequest

			    with:RestartProcessRequest.

    ].

    self initializeVMProcessIdConstants.

    "Modified: / 17.11.2001 / 11:07:29 / cg"

!

initializeVMProcessIdConstants

%{

#ifndef __SCHTEAM__

    @global(Process:SysProcessId) = __MKSMALLINT(SYS_PROCESS_ID);

    RETURN (self);

#endif /* not SCHTEAM */

%}.

    self primitiveFailed

! !

!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 */

    extern INT __defaultThreadMaxStackSize();

    RETURN ( __mkSmallInteger( __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 */

    extern INT __threadSetDefaultMaxStackSize();

    if (__isSmallInteger(numberOfBytes)) {

	RETURN ( __mkSmallInteger(__threadSetDefaultMaxStackSize(__intVal(numberOfBytes)) ));

    }

%}

    "

     Process defaultMaximumStackSize:500*1024

    "

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

!

wrapStackSize

    "return the wrap stack size.

     Under windows, blocking API calls are executed on a separate stack with this size.

     If you ever encounter that a call to n external library function requires more stack than

     this, you may change this size in your startup (or programmatically) during early startup.

     Returns nil on non-windows machines."

%{  /* NOCONTEXT */

    INT sz = 0;

#ifdef __win32__

    extern INT __getWrapStackSize();

    sz = __getWrapStackSize();

#endif

    RETURN (__MKINT(sz));

%}

!

wrapStackSize:newSize

    "set the wrap stack size.

     Under windows, blocking API calls are executed on a separate stack with this size.

     If you ever encounter that a call to n external library function requires more stack than

     this, you may change this size in your startup (or programmatically) during early startup.

     An argument of 0 changes the size back to the default.

     Returns the previous size."

%{  /* NOCONTEXT */

    INT __oldSize = 0;

    if (__isSmallInteger(newSize)) {

	INT __newSize = __intVal(newSize);

	if (__newSize >= 0) {

#ifdef __win32__

	    extern INT __setWrapStackSize(INT);

	    __oldSize = __setWrapStackSize(__newSize);

#endif

	}

    }

    RETURN (__MKINT(__oldSize));

%}

! !

!Process class methodsFor:'instance retrieval'!