32 The CLIM-SYS Package
The 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 clim-sys package.
32.1 Resources
CLIM provides a facility called resources that provides for reusing
objects. A resource describes how to construct an object, how to initialize and
deinitialize it, and how an object should be selected from the resource of
objects based on a set of parameters.
| defresource | name parameters
&key constructor initializer deinitializer
matcher initial-copies | [Macro] |
Defines a resource named name , which must be a symbol. parameters is a lambda-list giving names and default values (for optional and keyword
parameters) of parameters to an object of this type.
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.
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 name , which is the object to be initialized. The
initializer is called both on newly created objects and objects that are being
reused.
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 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 clear-resource . Deinitializers are
typically used to clear references to other objects.
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 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 equal . The
matcher should return true if there is a match, otherwise it should
return false .
initial-copies is used to specify the number of objects that should be
initially put into the resource. It must be an integer or 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.
| using-resource | (variable name &rest parameters) &body body | [Macro] |
The forms in body are evaluated with variable bound to an object
allocated from the resource named name , using the parameters given by
parameters . The parameters (if any) are evaluated, but name is
not.
After the body has been evaluated, using-resource returns the object in
variable back to the resource. If some form in the body sets
variable to nil , the object will not be returned to the resource.
Otherwise, the body should not changes the value of variable .
| allocate-resource | name &rest parameters | [Function] |
Allocates an object from the resource named name , using the parameters
given by parameters . name must be a symbol that names a resource.
The returned value is the allocated object.
| deallocate-resource | name object | [Function] |
Returns the object object to the resource named name . name must be a symbol that names a resource. object must be an object that was
originally allocated from the same resource.
| clear-resource | name | [Function] |
Clears the resource named name , that is, removes all of the resourced
object from the resource. name must be a symbol that names a resource.
| map-resource | function name | [Function] |
Calls function once on each object in the resource named name .
function is a function of three arguments, the object, a boolean value
that is true if the object is in use or false if it is free, and
name . function has dynamic extent.
32.2 Multi-processing
Most Lisp implementations provide some form of multi-processing. CLIM provides
a set of functions that implement a uniform interface to the multi-processing
functionality.
| *multiprocessing-p* | [Variable] |
The value of *multiprocessing-p* is t if the current Lisp
environment supports multi-processing, otherwise it is nil .
| make-process | function &key name | [Function] |
Creates a process named name . The new process will evaluate the function
function . On systems that do not support multi-processing,
make-process will signal an error.
| destroy-process | process | [Function] |
Terminates the process process . process is an object returned by
make-process .
| current-process | | [Function] |
Returns the currently running process, which will be the same kind of object as
would be returned by make-process .
Returns a sequence of all of the processes.
| processp | object | [Predicate] |
Returns t if object is a process, otherwise returns nil .
| process-name | process | [Function] |
| process-state | process | [Function] |
| process-whostate | process | [Function] |
These functions return, respectively, the name, state, and ``whostate'' of the
process. These format of these quantities will vary depending on the platform.
| process-wait | reason predicate | [Function] |
Causes the current process to wait until predicate returns true .
reason is a ``reason'' for waiting, usually a string. On systems that do
not support multi-processing, process-wait will loop until predicate returns true .
| process-wait-with-timeout | reason timeout predicate | [Function] |
Causes the current process to wait until either predicate returns
true , or the number of seconds specified by timeout has elapsed.
reason is a ``reason'' for waiting, usually a string. On systems that do
not support multi-processing, process-wait-with-timeout will loop until
predicate returns true or the timeout has elapsed.
Allows other processes to run. On systems that do not support multi-processing,
this does nothing.
| process-interrupt | process function | [Function] |
Interrupts the process process and causes it to evaluate the function
function . On systems that do not support multi-processing, this is
equivalent to funcall 'ing function .
| disable-process | process | [Function] |
Disables the process process from becoming runnable until it is enabled
again.
| enable-process | process | [Function] |
Allows the process process to become runnable again after it has been
disabled.
| restart-process | process | [Function] |
Restarts the process process by ``unwinding'' it to its initial state, and
reinvoking its top-level function.
| without-scheduling | &body body | [Macro] |
Evaluates body in a context that is guaranteed to be free from
interruption by other processes. On systems that do not support
multi-processing, without-scheduling is equivalent to progn .
| atomic-incf | reference | [Function] |
| atomic-decf | reference | [Function] |
Increments (or decrements) the fixnum value referred to by reference as a
single, atomic operation.
32.3 Locks
| make-lock | &optional name | [Function] |
Creates a lock whose name is name . On systems that do not support
locking, this will return a new list of one element, nil .
| with-lock-held | (place &optional state) &body body | [Macro] |
Evaluates body with the lock named by place . place is a
reference to a lock created by make-lock .
On systems that do not support locking, with-lock-held is equivalent to
progn .
| make-recursive-lock | &optional name | [Function] |
Creates a recursive lock whose name is name . On systems that do not
support locking, this will return a new list of one element, nil . A
recursive lock differs from an ordinary lock in that a process that already
holds the recursive lock can call with-recursive-lock-held on the same lock
without blocking.
| with-recursive-lock-held | (place &optional state) &body body | [Macro] |
Evaluates body with the recursive lock named by place . place is a reference to a recursive lock created by make-recursive-lock .
On systems that do not support locking, with-recursive-lock-held is
equivalent to progn .
32.4 Multiple Value setf
CLIM provides a facility, sometimes referred to as setf* , that allows
setf to be used on ``places'' that name multiple values. For example,
output-record-position returns the position of an output record as two
values that correspond to the x and y coordinates. In order to change the
position of an output record, the programmer would like to invoke
(setf~output-record-position) . Normally however, setf only takes a
single value with which to modify the specified place. The setf* facility
provides a ``multiple value'' version of setf that allows an expression
that returns multiple values to be used to update the specified place.
| defgeneric* | name lambda-list &body options | [Macro] |
Defines a setf* generic function named name . The last argument in
lambda-list is intended to be class specialized, just as is the case for
normal setf generic functions. options is as for defgeneric .
| defmethod* | name {method-qualifier}* specialized-lambda-list &body body | [Macro] |
Defines a setf* method for the generic function name . The last
argument in specialized-lambda-list is intended to be class specialized,
just as is the case for normal setf methods. {method-qualifier}* amd body are as for defgeneric .
For example, output-record-position and its setf* method for a class
called sample-output-record might be defined as follows:
(defgeneric output-record-position (record)
(declare (values x y)))
(defgeneric* (setf output-record-position) (x y record))
(defmethod output-record-position ((record sample-output-record))
(with-slots (x y)
(values x y)))
(defmethod* (setf output-record-position) (nx ny (record sample-output-record))
(with-slots (x y)
(setf x nx
y ny)))
The position of such an output record could then be changed as follows:
(setf (output-record-position record) (values nx ny))
(setf (output-record-position record1) (output-record-position record2))