% -*- Mode: LaTeX; Package: CLIM-USER -*- \chapter {The CLIM-SYS Package} \label {clim-sys-package} The \cl{clim-sys} package where useful ``system-like'' functionality lives, including such things as resources and multi-processing primitives. It contains concepts that are not part of Common Lisp, but which are not conceptually the province of CLIM itself. All of the symbols documented in this appendix must be accessible as external symbols in the \cl{clim-sys} package. \section {Resources} \Defmacro {defresource} {name parameters \key constructor initializer deinitializer matcher initial-copies} Defines a resource named \arg{name}, which must be a symbol. \arg{parameters} is a lambda-list giving names and default values (for optional and keyword parameters) of parameters to an object of this type. \arg{constructor} is a form that is responsible for creating an object, and is called when someone tries to allocate an object from the resource and no suitable free objects exist. The constructor form can access the parameters as variables. This argument is required. \arg{initializer} is a form that is used to initialize an object gotten from the resource. It can access the parameters as variables, and also has access to a variable called \arg{name}, which is the object to be initialized. The initializer is called both on newly created objects and objects that are being reused. \arg{deinitializer} is a form that is used to deinitialize an object when it is about to be returned to the resource. It can access the parameters as variables, and also has access to a variable called \arg{name}, which is the object to be deinitialized. It is called whenever an object is deallocated back to the resource, but is not called by \cl{clear-resource}. Deinitializers are typically used to clear references to other objects. \arg{matcher} is a form that ensures that an object in the resource ``matches'' the specified parameters, which it can access as variables. In addition, the matcher also has access to a variable called \arg{name}, which is the object in the resource being matched against. If no matcher is supplied, the system remembers the values of the parameters (including optional ones that defaulted) that were used to construct the object, and assumes that it matches those particular values for all time. This comparison is done with \cl{equal}. The matcher should return \term{true} if there is a match, otherwise it should return \term{false}. \arg{initial-copies} is used to specify the number of objects that should be initially put into the resource. It must be an integer or \cl{nil} (the default), meaning that no initial copies should be made. If initial copies are made and there are parameters, all the parameters must be optional; in this case, the initial copies have the default values of the parameters. \Defmacro {using-resource} {(variable resource \rest parameters) \body body} The forms in \arg{body} are evaluated with \arg{variable} bound to an object allocated from the resource named resource, using the given parameters given by \arg{parameters}. The parameters (if any) are evaluated, but \arg{resource} is not. After the body has been evaluated, \cl{using-resource} returns the object in \arg{variable} back to the resource. If some form in the body sets \arg{variable} to \cl{nil}, the object will not be returned to the resource. Otherwise, the body should not changes the value of \arg{variable}. \Defun {clear-resource} {resource} Clears the resource whose name is \arg{resource}, that is, removes all of the resourced object from the resource. \arg{resource} must be a symbol that names a resource. \section {Multi-processing} \Defun {make-process} {function \key name} Creates a process named \arg{name}. The new process will evaluate the function \arg{function}. On systems that do not support multi-processing, \cl{make-process} will signal an error. \Defun {destroy-process} {process} Terminates the process \arg{process}. \arg{process} is an object returned by \cl{make-process}. \Defun {current-process} {} Returns the currently running process, which will be the same kind of object as would be returned by \cl{make-process}. \Defun {all-processes} {} Returns a sequence of all of the processes. \Defun {process-wait} {reason predicate} Causes the current process to wait until \arg{predicate} returns \term{true}. \arg{reason} is a ``reason'' for waiting, usually a string. On systems that do not support multi-processing, \cl{process-wait} will loop until \arg{predicate} returns \term{true}. \Defun {process-wait-with-timeout} {reason timeout predicate} Causes the current process to wait until either \arg{predicate} returns \term{true}, or the number of seconds specified by \arg{timeout} has elapsed. \arg{reason} is a ``reason'' for waiting, usually a string. On systems that do not support multi-processing, \cl{process-wait-with-timeout} will loop until \arg{predicate} returns \term{true} or the timeout has elapsed. \Defun {process-yield} {} Allows other processes to run. On systems that do not support multi-processing, this does nothing. \Defun {process-interrupt} {process function} Interrupts the process \arg{process} and causes it to evaluate the function \arg{function}. On systems that do not support multi-processing, this is equivalent to \cl{funcall}'ing \arg{function}. \Defmacro {without-scheduling} {\body body} Evaluates \arg{body} in a context that is guaranteed to be free from interruption by other processes. On systems that do not support multi-processing, \cl{without-scheduling} is equivalent to \cl{progn}. \section {Locks} \Defmacro {with-lock-held} {(place \optional state) \body body} Evaluates \arg{body} with the lock named by \arg{place}. \arg{place} is a reference to a lock created by \cl{make-lock}. On systems that do not support locking, \cl{with-lock-held} is equivalent to \cl{progn}. \Defun {make-lock} {\optional name} Creates a lock whose name is \arg{name}. On systems that do not support locking, this should return a new list of one element, \cl{nil}. \Defmacro {with-recursive-lock-held} {(place \optional state) \body body} Evaluates \arg{body} with the recursive lock named by \arg{place}. \arg{place} is a reference to a recursive lock created by \cl{make-recursive-lock}. On systems that do not support locking, \cl{with-recursive-lock-held} is equivalent to \cl{progn}. \Defun {make-recursive-lock} {\optional name} Creates a recursive lock whose name is \arg{name}. On systems that do not support locking, this should return a new list of one element, \cl{nil}. A recursive lock differs from an ordinary lock in that a process that already holds the recursive lock can call \cl{with-recursive-lock-held} on the same lock without blocking.