"

 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.

"

Object subclass:#ProcessorScheduler

	instanceVariableNames:'quiescentProcessLists scheduler zombie activeProcess

		currentPriority readFdArray readSemaphoreArray readCheckArray

		writeFdArray writeSemaphoreArray timeoutArray timeoutActionArray

		timeoutProcessArray timeoutSemaphoreArray idleActions anyTimeouts

		dispatching interruptedProcess useIOInterrupts gotIOInterrupt

	classVariableNames:'KnownProcesses KnownProcessIds PureEventDriven

		UserSchedulingPriority UserInterruptPriority TimingPriority

		HighestPriority SchedulingPriority MaxNumberOfProcesses'

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

    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 schedulers policy and implementation

    at the smalltalk level.

    (To answer a frequently asked question:

     dont add preemptive round-robin here; this can be implemented without

     any need to change the scheduler. See goodies/timeslicing.st for how

     this is done in a very elegant way).

    Notice: Smalltalk/X can (still) be compiled & configured without

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

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

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

    implement (threads require some assembler support functions). 

    To allow pureEvent mode, kludges are 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).

    This pure-event mode may not be supported in the future 

    (actually, it is no longer maintained in places where was present, so dont

     run the system without Processes).

    class variables:

	KnownProcesses          <Collection>    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)

    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:

"

! !

!ProcessorScheduler class methodsFor:'initialization'!

initialize

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

     setup some priority values."

    UserSchedulingPriority := 8.

    UserInterruptPriority := 24.

    TimingPriority := 16.

    SchedulingPriority := 31.

    HighestPriority := 30.

    Processor isNil ifTrue:[

        "create the one and only processor"

        Processor := self basicNew initialize.

    ].

    "

     allow configurations without processes

    "

    PureEventDriven := self threadsAvailable not.

    PureEventDriven ifTrue:[

        'PROCESSOR: no process support - running event driven' errorPrintNL

    ].

    "Modified: 7.3.1996 / 19:22:49 / cg"

! !

!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:'instance release'!

informDispose

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

    sz := KnownProcessIds size.

    1 to:sz do:[:index |

	(KnownProcesses at:index) isNil ifTrue:[

	    id := KnownProcessIds at:index.

	    id notNil ifTrue:[

		'PROCESSOR: terminating thread ' errorPrint.

		id errorPrint.

		' (no longer refd)' errorPrintNL.

		self threadDestroy:id.

		KnownProcessIds at:index put:nil.

	    ]

	]

    ]

! !

!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 dont 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 ( __MKSMALLINT(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.

    "

    ^ ObjectMemory allocationFailureSignal 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());

%}

! !

!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]

!

maxNumberOfProcesses

    "return the limit on the number of processes;

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

    ^ MaxNumberOfProcesses

!

maxNumberOfProcesses:aNumber

    "set the limit on the number of processes.

     This helps if you have a program which (by error) creates countless

     subprocesses. Without this limit, you may have a hard time to find

     this error (and repairing it). If nil (the default), the number of

     processes is unlimited."

    MaxNumberOfProcesses := aNumber

!

processDriven

    "turn on process driven mode"

    PureEventDriven := false

!

pureEventDriven

    "turn on pure-event driven mode - no processes, single dispatch loop"

    PureEventDriven := true

! !

!ProcessorScheduler methodsFor:'I/O event actions'!

disableFd:aFileDescriptor

    "disable block events on aFileDescriptor.

     This is a leftover support for pure-event systems and may vanish."

    |idx "{Class: SmallInteger }" 

     wasBlocked|

    wasBlocked := OperatingSystem blockInterrupts.

    idx := readFdArray identityIndexOf:aFileDescriptor startingAt:1.

    idx ~~ 0 ifTrue:[

	readFdArray at:idx put:nil.

	readCheckArray at:idx put:nil.

	readSemaphoreArray at:idx put:nil

    ].

    wasBlocked ifFalse:[OperatingSystem unblockInterrupts].

!

enableIOAction:aBlock onInput:aFileDescriptor

    "half-obsolete event support: arrange for aBlock to be

     evaluated when input on aFileDescriptor arrives. 

     This is a leftover support for pure-event systems and may vanish."

    |idx "{Class: SmallInteger }"

     wasBlocked|

    wasBlocked := OperatingSystem blockInterrupts.

    (readFdArray identityIndexOf:aFileDescriptor startingAt:1) == 0 ifTrue:[

	idx := readFdArray identityIndexOf:nil startingAt:1.

	idx ~~ 0 ifTrue:[

	    readFdArray at:idx put:aFileDescriptor.

	    readCheckArray at:idx put:aBlock.

	    readSemaphoreArray at:idx put:nil

	] ifFalse:[

	    readFdArray := readFdArray copyWith:aFileDescriptor.

	    readCheckArray := readCheckArray copyWith:aBlock.

	    readSemaphoreArray := readSemaphoreArray copyWith:nil.

	]

    ].

    wasBlocked ifFalse:[OperatingSystem unblockInterrupts].

! !

!ProcessorScheduler methodsFor:'accessing'!

activePriority

    "return the priority of the currently running process.

     GNU-ST & ST-80 compatibility; this is the same as currentPriority"

    ^ currentPriority

!

activeProcess

    "return the currently running process"

    ^ activeProcess

    "Processor activeProcess"

!

currentPriority

    "return the priority of the currently running process"

    ^ currentPriority

    "Processor currentPriority"

!

interruptedProcess

    "returns the process which was interrupted by the active one"

    ^ interruptedProcess

! !

!ProcessorScheduler methodsFor:'background processing'!

addIdleBlock:aBlock

    "add the argument, aBlock to the list of idle-actions.

     Idle blocks are evaluated whenever no other process is runnable,

     and no events are pending.

     Use of idle blocks is not recommended, use a low priority processes 

     instead, which has the same effect. Idle blcoks are still included

     to support background actions in pure-event systems, where no processes 

     are available.

     Support for idle-blocks may vanish."

    |wasBlocked|

    wasBlocked := OperatingSystem blockInterrupts.

    idleActions isNil ifTrue:[

	idleActions := OrderedCollection new

    ].

    idleActions add:aBlock.

    wasBlocked ifFalse:[OperatingSystem unblockInterrupts].

!

removeIdleBlock:aBlock

    "remove the argument, aBlock from the list of idle-blocks.

     Support for idle-blocks may vanish - use low prio processes instead."

    |wasBlocked|

    wasBlocked := OperatingSystem blockInterrupts.

    idleActions notNil ifTrue:[

       idleActions remove:aBlock

    ].

    wasBlocked ifFalse:[OperatingSystem unblockInterrupts].

! !

!ProcessorScheduler methodsFor:'constants'!

highestPriority

    "return the highest priority value (normal) processes can have."

    "must be below schedulingPriority - 

     otherwise scheduler could be blocked ...

    "

    ^ HighestPriority  

!

lowIOPriority

    "not currently used - for ST80 compatibility only"

    ^ 2 "claus: is this ok ?"

!

lowestPriority

    "return the lowest priority value"

    ^ 1   "do not change this - its not variable"

!

schedulingPriority

    "return the priority at which the scheduler runs."

    "must be above highestPriority - 

     otherwise scheduler could be blocked ...

    "

    ^ SchedulingPriority

!

systemBackgroundPriority

    "return the priority, at which background system processing

     should take place.

     Not currently used - for ST80 compatibility only"

    ^ 4

!

timingPriority

    "return the priority, at which all timing takes place (messageTally,

     delay etc.)"

    ^ TimingPriority

!

userBackgroundPriority

    "return the priority, at which background user (non-interactive) processing

     should take place.

     Not currently used - for ST80 compatibility only"

    ^ 6

!

userInterruptPriority

    "return the priority, at which the event scheduler runs - i.e.

     all processes running at a lower priority are interruptable by Cntl-C

     or the timer. Processes running at higher prio will not be interrupted."

    ^ UserInterruptPriority

!

userSchedulingPriority

    "return the priority, at which all normal user (interactive) processing

     takes place"