% -*- 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.
