"

 COPYRIGHT (c) 1993 by Claus Gittinger

 COPYRIGHT (c) 2016-2017 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 }"

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 MinProcessId MaxProcessId SysProcessId'

	poolDictionaries:''

	category:'Kernel-Processes'

!

!ProcessorScheduler primitiveDefinitions!

%{

# ifndef _STDIO_H_INCLUDED_

#  include <stdio.h>

#  define _STDIO_H_INCLUDED_

# endif

%}

! !

!ProcessorScheduler class methodsFor:'documentation'!

copyright

"

 COPYRIGHT (c) 1993 by Claus Gittinger

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

"

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

    self initializeVMProcessIdConstants.

    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:[

	Logger error:'Processor: no process support - running event driven'.

    ].

    "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>"

!

initializeVMProcessIdConstants

    "/ 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__

    @global(ProcessorScheduler:MinProcessId) = __MKSMALLINT(MIN_PROCESS_ID);

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

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

    RETURN (self);

#endif /* not SCHTEAM */

%}.

    self primitiveFailed

! !

!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:anAspect 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 }" wasBlocked|

    anAspect == #ElementExpired ifTrue:[

	wasBlocked := OperatingSystem blockInterrupts.

	sz := KnownProcessIds size.

	1 to:sz do:[:index |

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

		"weak element has been collected"

		id := KnownProcessIds at:index.

		id notNil ifTrue:[

		    Logger warning:'Processor: terminating thread %1 (no longer refd)' with:id.

		    self threadDestroy:id.

		    KnownProcessIds at:index put:nil.

		].

		KnownProcesses at:index put:nil.

	    ]

	].

	wasBlocked ifFalse:[ OperatingSystem unblockInterrupts ].

    ]

    "Created: / 07-01-1997 / 16:45:42 / stefan"

    "Modified: / 01-06-2020 / 14:11:34 / 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'.

	    ]

	]

    ].

    "/ e'threadCreate {(ObjectMemory addressOf:aProcess)hexPrintString} id:{id}\n' printOn:Stderr.

%{

    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"

    |wasBlocked ret|

    wasBlocked := OperatingSystem blockInterrupts.

    ret := KnownProcesses select:[:p | p notNil and:[p class ~~ SmallInteger]] as:OrderedCollection.

    wasBlocked ifFalse:[OperatingSystem unblockInterrupts].

    ^ ret