The following table givs a brief description of the primitives available to produce the S User Level Threads API. Given these, we can produce other classes and functions in the standard/official API by using some of these primitives appropriately. These new classes include Reader Writer Locks and Barriers which are convenient synchronization mechanisms.

Table of S "Primitives" for Threads and Related Material

Classes and Objects Associated With S User Level Threads Thread Classes thread Class an S level class that represents the internal object that performs the necessary actions for a thread. This primarily allows us to establish methods for generic functions based on thread objects in the signature. Objects of this class contain very little information themselves but act more as pointers to private/non-accessible data that must be accessed exclusively via functions. For a more complete description and discussion of S user level threads, see Threads. readerThread class of object that watches for input on a connection and performs a specifiable action when input is present. This is implemented as a separate evaluation thread. waitThread class that performs a task after a fixed interval. This can perform a task repeatedly at fixed intervals. This is implemented as a separate evaluation thread ThreadGroup Class a container for a collection of threads. Operations can be easily applied to all threads in a group, such as cancel, start, etc threadAttributes Class an object representing the attributes used in creating a thread. These are values for parameters that control the run time behavior of the thread in terms of its competition for resources and what happens when it exits. psAttributes Vector the vector describing the attributes retrievable from a thread. This is used as an input mask for the functions ps() xps() Thread Creation and Control thread() creates an evaluator thread. threadAttributes create an object of class threadAttributes with the default values overridden by those passed to this function. ThreadGroup constructor for a threadGroup object. Any number of thread objects can be passed to the constructor as elements to be added to the group. sendTask() places a task on the end of a thread's task queue for evaluation in the future. cancel() cancel the execution one or more threads. suspend() temporarily stop the execution of one or more threads until restarted by another thread. start() start or continue one or more threads. This takes out of suspend mode and into run/evaluation mode. exit() terminate the execution of a thread and return a value to the evaluator manager. join() have this thread wait until one or more threads have finished. self() get the thread object for this calling thread, namely the current thread itself. onExit() set or add an expression block to be evaluated when the thread exits, either normally (exit()) or abnormally (e.g.cancel()). yield() causes the calling thread to temporarily give up execution to allow other threads to compete for CPU resources. parent() get the parent thread of a given thread. children() obtain the vector of threads whose parent is the given thread. setReader() create a ReaderThread and have it perform actions when input is found on the supplied connection. waitThread() create a waitThread object which performs a task after a specified interval. Optionally, the task can be automatically rescheduled or the task can reschedule another task. The object created is of class waitThread which inherits from the thread class. setInterval() set the delay between successive evaluations of a task for a waitThread object. The main purpose of this function is to allow an idle waitThread to be parameterized after creation such as after new("waitThread"). We are allowing access to this, but don't envisage it being used much. Synchronization threadLock() create an object of class threadLock which acts as a database into which variables that are shared between two threads can be stored. getLock() obtain a mutually exclusive lock represented by the threadLock object supplied. If a condition is specified, this function does not return until the condition is true and provides a mechanism similar to condition variables in POSIX threads. This allows synchronization on the values of shared variables rather than on access to shared variables provided by threadLock objects. tryGetLock() attempt to acquire a lock on the threadLock object and return even if unsuccessful. This is a non-blocking form of getLock that is guaranteed to return "immediately". If a condition is supplied, the call waits until the lock is required and the condition is evaluated once within the lock. Whatever the result of the evaluation, the call returns with the lock held. yieldLock() release the lock held for this object. threadLock.assign() method for assign() for threadLock objects. This is a mutually exclusive assignment in that no other thread can be assigning to this object at the same time. lockOwner() query the owner of the lock and the recursive lock count. threadLockEvent() creates an object of class threadLockEvent to be used as the condition argument for getLock(). threadLockEvent class describing an event (remove or assign) on a threadLock object. This can be used as the condition argument for getLock(). Evaluator Manager Functions setThreadAttributes() set threadAttributes for one or more thread objects to a common value after these threads have been created. getThreadAttributes() retrieve the threadAttributes object for each of the specified threads in the arguments (of class threads or threadGroups). These are retrieved from the Evaluator Manager. isAlive() checks to see if each of the thread objects are still "active" and potentially available for performing tasks. isBlocked() tests whether each of the thread objects are blocked waiting for a lock. isCancelled() tests whether each of the thread objects are considered cancelled (not simply in cancel pending mode). isIdle() determines whether the task queues are emptry but active for each of the thread objects. isSuspended() tests each thread determining if it is in suspended mode. isFinished() tests each thread to determine if it is considered terminated. This is the opposite of isAlive(), I think. valueOf() returns the exit value for each of supplied thread objects. threadOf() for each object supplied, the associated thread is returned. This is most useful for threadLock objects so as to be able to determine which thread holds the lock at the time of evaluation of this expression. dbOf() returns the database or frame into which the toplevel assignments will be comitted for each of the supplied threads. searchPathOf() returns the search path as a vector of databases and frames for each of the supplied threads. removeTask() removes a given expression from a threads task queue. The expression must be a perfect match with that in the task queue for the removal to take effect. Process Level Thread Management Functions threads() return a list of the threads currently in existence. taskQueue() returns a copy of the expressions/tasks currently queued for the given thread ps() report on the status of a subset of process's user level threads xps() report on the status of a subset of process's user level threads in an X window. Allows point and click interaction. This is an X version of ps that updates it display periodically.