"

 COPYRIGHT (c) 1993 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.

"

"{ Package: 'stx:libbasic' }"

"{ NameSpace: Smalltalk }"

Object subclass:#ProcessorScheduler

	instanceVariableNames:'quiescentProcessLists scheduler zombie activeProcess

		activeProcessId currentPriority readFdArray readSemaphoreArray

		readCheckArray writeFdArray writeSemaphoreArray writeCheckArray

		timeoutArray timeoutActionArray timeoutProcessArray

		timeoutSemaphoreArray idleActions anyTimeouts dispatching

		interruptedProcess useIOInterrupts gotIOInterrupt

		osChildExitActions gotChildSignalInterrupt

		exitWhenNoMoreUserProcesses suspendScheduler timeSliceProcess

		supportDynamicPriorities timeSliceNeededSemaphore

		scheduledProcesses preWaitActions timeoutHandlerProcess

		readableResultFdArray writableResultFdArray exceptFdArray

		exceptResultFdArray exceptSemaphoreArray interruptCounter

		timedActionCounter'

	classVariableNames:'KnownProcesses KnownProcessIds PureEventDriven

		UserSchedulingPriority UserInterruptPriority TimingPriority

		HighestPriority SchedulingPriority MaxNumberOfProcesses

		InvalidProcessSignal TimeSlicingPriorityLimit TimeSliceInterval

		EventPollingInterval MaxProcessId'

	poolDictionaries:''

	category:'Kernel-Processes'

!

!ProcessorScheduler class methodsFor:'documentation'!

copyright

"

 COPYRIGHT (c) 1993 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

"

    This class has only one instance, which is bound to the global

    'Processor' (well, on future multiprocessor systems, things may look

    different ... ;-). It is responsible for scheduling among the Smalltalk

    processes (threads; not to confuse with heavy weight unix processes).

    Scheduling is fully done in Smalltalk (the always runnable scheduler-

    process, running at highest priority does this).

    See the 'scheduling' documentation.

    The main VM primitive to support this is found in threadSwitch, which passes

    control to another process (usually selected by the scheduler).

    Thus it is possible to modify the scheduler's policy and implementation

    at the Smalltalk level (if you are brave enough to do this).

    Notice:

    ST/X includes a timeslicer and reschedules running threads within the highest runnable

    priority. This is done by the timeSlicer thread, which runs at high realtime prio.

    Also notice, that ST/X supports dynamic priority ranges: a low prio (background) process

    can be quaranteed to make progress, by giving it a range from low to a higher (usually user-) prios.

    If it was suspended long enough, its prio will be dynamically increased, until it gets a slice to run

    (and then drops back to its low background prio). So it will get a chance to do some work.

    Final Notice: 

    Smalltalk/X used to support a mode (configured and compiled) without

    process support. This non-process mode was called 'pureEventDriven' mode

    and was useful to quickly port ST/X to systems, where these facilities

    were either not needed (server applications), or were difficult to

    implement (threads require some assembler support functions).

    To allow pureEvent mode, kludges were built into some places in the

    system, where either a process is forked, or a timeout is used instead

    (for examples, see ProcessMonitor or MemoryMonitor).

    Although still present in some places, support for this pure-event mode is no longer supported,

    and will vanish over time from the code.

    [instance variables:]

        quiescentProcessLists           - list of waiting processes

        scheduler                       - the scheduler process itself

        zombie                          - internal temporary (recently died process)

        activeProcess                   - the current process

        activeProcessId                 - the current processes id

        currentPriority                 - the current processes priority

        readFdArray                     - fd-sema-checkBlock triple-association

        readSemaphoreArray                (stupid historic 3-separate arrays for hi-speed-optimization reasons)

        readCheckArray

        writeFdArray                    - fd-sema-checkBlock triple-association

        writeSemaphoreArray               (stupid historic 3-separate arrays for hi-speed-optimization reasons)

        writeCheckArray

        timeoutArray                    - time-action-process-sema quadruple-association

        timeoutActionArray                (stupid historic 3-separate arrays for hi-speed-optimization reasons)

        timeoutProcessArray

        timeoutSemaphoreArray

        idleActions                     - actions to be executed when idle

        preWaitActions                  - actions to be executed BEFORE going into an OS-wait

        anyTimeouts                     - flag if any timeouts are pending

        dispatching                     - flag if dispatch process is running (i.e. NOT initializing)

        interruptedProcess              - the currently interrupted process.

        useIOInterrupts                 - flag if the OS supports I/O interrupts and if they are used (to get me out of an OS wait)

        gotIOInterrupt                  - flag if I came out of a wait due to an I/O interrupt

        osChildExitActions              - OS chid process actions

        gotChildSignalInterrupt         - flag if I came out of a wait due to an OS child interrupt

        exitWhenNoMoreUserProcesses     - flag which controls if ST/X should exit when the last process dies (for standalone apps)

        suspendScheduler                - internal use

        timeSliceProcess                - the timeSlicer process

        supportDynamicPriorities        - flag if dynamic priorities should be supported by the timeSlicer

        scheduledProcesses              - list of scheduled processes for the timeSlicers dynamic prio handling

    [class variables:]

        KnownProcesses          <WeakArray>     all known processes

        KnownProcessIds         <Collection>    and their IDs

        PureEventDriven         <Boolean>       true, if no process support

                                                is available

        UserSchedulingPriority  <Integer>       the priority at which normal

                                                user interfaces run

        UserInterruptPriority                   the priority at which user-

                                                interrupts (Cntl-C) processing

                                                takes place. Processes with

                                                a greater or equal priority are

                                                not interruptable.

        TimingPriority                          the priority used for timing.

                                                Processes with a greater or

                                                equal priority are not interrupted

                                                by timers.

        HighestPriority                         The highest allowed prio for processes

        SchedulingPriority                      The priority of the scheduler (must

                                                me higher than any other).

        MaxNumberOfProcesses                    if non-nil, no more than this

                                                number of processes are allowed

                                                (for debugging)

        TimeSliceInterval                       for preemptive priority scheduling only:

                                                the time interval in millis, at which processes

                                                are timesliced

        TimeSlicingPriorityLimit                for preemptive priority scheduling only:

                                                processes are only timesliced, if running

                                                at or below this priority.

        EventPollingInterval                    for systems which do not support select on

                                                a fileDescriptor: the polling interval in millis.

    most interesting methods:

        Processor>>suspend:                  (see also Process>>suspend)

        Processor>>resume:                   (see also Process>>resume)

        Processor>>terminate:                (see also Process>>terminate)

        Processor>>yield

        Processor>>changePriority:for:       (see also Process>>priority:

        Processor>>signal:afterSeconds:      (see also Delay>>forSeconds:)

        Processor>>signal:afterMilliseconds: (see also Delay>>forMilliseconds:)

        Processor>>signal:onInput:           (see also ExternalStream>>readWait)

        Processor>>signal:onOutput:          (see also ExternalStream>>writeWait)

        Processor>>disableSemaphore:

    [see also:]

        Process

        Delay Semaphore SemaphoreSet SharedQueue

        WindowGroup

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

    [author:]

        Claus Gittinger

"

!

scheduling

"

    By default, the scheduler does 'non preemptive priority scheduling';

    this means, that the highest priority runnable process

    is choosen and allowed to run, until it either gives back the CPU (via #yield),

    or suspends (i.e. waiting for I/O, the time or a semaphore),

    or a higher priority process becomes runnable..

    A higher prio process may become runnable either by a programmatic action

    (i.e. signalling a semaphore), by a timer or by IO availability.

    If another process is runnable at the same priority, it will not

    be given CPU-time, unless one of the above happens.

    The consequence is, that a user process running at (say) priority 8,

    may block other user processes at the same priority, if it does heavy

    processing, or loops.

    (the event handling which is responsible to care for userInterrupts,

     is running at a much higher priority,

     so that interrupting the process should always be possible).

    The scheduler also supports 'timesliced priority scheduling', which is enabled

    via the #startTimeSlicing message (and disabled by #stopTimeSlicing).

    In this mode, the highest priority running process is suspended in regular intervals

    (the TimeSliceInterval) IFF there is another runnable process with the same priority.

    I.e. the top highest priority processes are timeshared.

    In this mode, the other processes will also get a chance to make some progress - however,

    lower priority process will only run, IFF all higher prio processes are waiting for an

    event.

    Timeslicing will not be done for processes running above TimeSlicingPriorityLimit, which

    allows for critical processes to run unaffected to completion.

    WARNING:

	timesliced priority scheduling is an experimental feature. There is no warranty,

	(at the moment), that the system runs reliable in this mode.

	The problem is, that shared collections may now be easily modified by other

	processes, running at the same time.

	The class library has being investigated for such possible trouble spots

	(we have eliminated many weak spots, and added critical regions at many places,

	 but cannot guarantee that all of them have been found so far ...)

	We found that many existing public domain programs are not prepared for

	being interrupted by a same-prio process and therefore may corrupt their

	data. If in doubt, disable this fefature.

    We think, that the timeSlicer is a useful add-on and that the system is fit enough

    for it to be evaluated, therefore, its included.

    However, use it at your own risk.

    To demonstrate the effect of timeSlicing, do the following:

	- disable timeSlicing (in the launchers misc-settings menu)

	- open a workSpace

	- in the workspace, evaluate:

		[true] whileTrue:[1000 factorial]

    now, (since the workSpace runs at the same prio as other window-processes),

    other views do no longer react - all CPU is used up by the workSpace.

    However, CTRL-C in the workspace is still possible to stop the endless loop,

    since that is handled by the (higher prio) event dispatcher process.

    Now, stop the factorial-loop, enable timeSlicing, and try again.

    You will notice, that other windows react - although possibly a bit slower,

    since the CPU is now divided equally among the runnable processes (timeSliced).

"

! !

!ProcessorScheduler class methodsFor:'initialization'!

initialize

    "class setup: create the one-and-only instance of myself and

     setup some priority values."

    TimeSliceInterval := 50.

    EventPollingInterval := 20.

    UserSchedulingPriority := 8.

    UserInterruptPriority := 24.

    TimingPriority := 16.

    TimeSlicingPriorityLimit := 26.

    HighestPriority := 30.

    SchedulingPriority := 31.

    InvalidProcessSignal isNil ifTrue:[

	InvalidProcessSignal := Error newSignalMayProceed:true.

	InvalidProcessSignal nameClass:self message:#invalidProcessSignal.

	InvalidProcessSignal notifierString:'invalid process'.

    ].

    Processor isNil ifTrue:[

	"create the one and only processor"

	Smalltalk at:#Processor put:(self basicNew initialize).

    ].

    "

     allow configurations without processes

     (but such configurations are no longer distributed)

    "

    PureEventDriven := self threadsAvailable not.

    PureEventDriven ifTrue:[

	'Processor [error]: no process support - running event driven' errorPrintCR

    ].

    self initializeVMMaxProcessId

    "Modified: / 23-09-1996 / 14:24:50 / stefan"

    "Modified: / 10-01-1997 / 18:03:03 / cg"

    "Modified: / 19-09-2014 / 12:47:51 / Jan Vrany <jan.vrany@fit.cvut.cz>"

!

initializeVMMaxProcessId

    "/ for java locks, the VM may reserve some bits

    "/ and reduce the maximum processID to be able to

    "/ encode the id in an object's header field.

%{

#ifndef __SCHTEAM__

# ifndef MAX_PROCESS_ID

#  define MAX_PROCESS_ID _MAX_INT

# endif

    @global(ProcessorScheduler:MaxProcessId) = __MKSMALLINT(MAX_PROCESS_ID);

    RETURN (self);

#endif /* not SCHTEAM */

%}.

    MaxProcessId := SmallInteger maxVal.

! !

!ProcessorScheduler class methodsFor:'instance creation'!

new

    "there is (currently) only one processor ..."

    self error:'only one processor is allowed in the system'

! !

!ProcessorScheduler class methodsFor:'Signal constants'!

invalidProcessSignal

    ^ InvalidProcessSignal

    "Created: 23.9.1996 / 13:44:57 / stefan"

! !

!ProcessorScheduler class methodsFor:'instance release'!

update:something with:aParameter from:changedObject

    "some Process has been garbage collected

     - terminate the underlying thread.

     Usually this does not happen; instead, the process terminates itself

     by sending #terminate."

    |id sz "{ Class: SmallInteger }"|

    something == #ElementExpired ifTrue:[

	sz := KnownProcessIds size.

	1 to:sz do:[:index |

	    "/ (KnownProcesses at:index) isNil ifTrue:[

	    (KnownProcesses at:index) class == SmallInteger ifTrue:[

		id := KnownProcessIds at:index.

		id notNil ifTrue:[

		    'Processor [warning]: terminating thread ' errorPrint.

		    id errorPrint.

		    ' (no longer refd)' errorPrintCR.

		    self threadDestroy:id.

		    KnownProcessIds at:index put:nil.

		].

		KnownProcesses at:index put:nil.

	    ]

	]

    ]

    "Created: 7.1.1997 / 16:45:42 / stefan"

    "Modified: 10.1.1997 / 19:10:48 / cg"

! !

!ProcessorScheduler class methodsFor:'primitive process primitives'!

threadCreate:aProcess withId:id

    "physical creation of a process.

     (warning: low level entry, no administration done).

     This may raise an exception, if a VM process could not be created."

    MaxNumberOfProcesses notNil ifTrue:[

        KnownProcessIds size >= MaxNumberOfProcesses ifTrue:[

            (KnownProcessIds count:[:el | el notNil]) >= MaxNumberOfProcesses ifTrue:[

                "

                 the number of processes has reached the (soft) limit.

                 This limit prevents runaway programs from creating too many

                 processes. If you continue in the debugger, the process will be

                 created as usual. If you don't want this, abort or terminate.

                "

                self error:'too many processes'.

            ]

        ]

    ].

%{

    int tid;

    extern int __threadCreate();

    tid = __threadCreate(aProcess,

                         0   /* stackSize: no longer needed */,

                         __isSmallInteger(id) ? __intVal(id)     /* assign id */

                                              : -1              /* let VM assign one */  );

    if (tid) {

        RETURN ( __mkSmallInteger(tid));

    }

%}

.

    "

     arrive here, if creation of process in VM failed.

     This may happen, if the VM does not support more processes,

     or if it ran out of memory, when allocating internal data

     structures.

    "

    ^ AllocationFailure raise.

!

threadDestroy:id

    "physical destroy other process ...

     (warning: low level entry, no administration done)"

%{  /* NOCONTEXT */

    if (__isSmallInteger(id)) {

	__threadDestroy(__intVal(id));

    }

%}

!

threadInterrupt:id

    "make the process evaluate an interrupt. This sets a flag in the VMs

     threadSwitcher, to let the process perform a #interrupt when its set to

     run the next time. The process itself can decide how to react on this

     interrupt (currently, it looks for interruptBlocks to evaluate)."

%{  /* NOCONTEXT */

    if (__isSmallInteger(id)) {

	__threadInterrupt(__intVal(id));

    }

%}

!

threadsAvailable

    "return true, if the runtime system supports threads (i.e. processes);

     false otherwise."

%{  /* NOCONTEXT */

    RETURN (__threadsAvailable());

%}.

    ^ true

! !

!ProcessorScheduler class methodsFor:'queries'!

isPureEventDriven

    "this is temporary - (maybe not :-).

     you can run ST/X either with or without processes.

     Without, there is conceptionally a single process handling all

     outside events and timeouts. This has some negative implications

     (Debugger is ugly), but allows a fully portable ST/X without any

     assembler support - i.e. quick portability.

     The PureEvent flag will automatically be set if the runtime system

     does not support threads - otherwise, it can be set manually

     (from rc-file).

    "

    ^ PureEventDriven

!

knownProcesses

    "return a collection of all (living) processes in the system"

    ^ KnownProcesses select:[:p | p notNil and:[p class ~~ SmallInteger]]

!

knownProcessesDo:aBlock

    "evaluate aBlock for each (living) processes in the system"

    KnownProcesses do:[:p |

	(p notNil and:[p class ~~ SmallInteger]) ifTrue:[aBlock value:p]

    ]

    "Created: / 26-10-2012 / 13:02:33 / cg"

!

maxNumberOfProcesses

    "return the limit on the number of processes;

     the default is nil (i.e. unlimited)."

    ^ MaxNumberOfProcesses

!