Appendix C The CLIM-SYS Package

C.1 Resources

CLIM provides a facility called resources that allows you to reuse 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 [Macro]

name parameters&key constructor initializer deinitializer matcher initial-copies
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 creates an object; it 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 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 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, 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. 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 returns t if there is a match, and otherwise nil.

initial-copies specifies the number of objects to 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; the initial copies will then have the default values of the parameters.

using-resource [Macro]
(variable name&rest parameters)&body body
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 body has been evaluated, using-resource returns the object in variable to the resource. If a form in the body sets variable to nil, the object is not returned to the resource. Otherwise, the body should not change the value of variable.

allocate-resource [Function]
name&rest parameters
Allocates an object from the resource name, using the parameters given by para-meters. name must be a symbol naming a resource. It returns the allocated object.

deallocate-resource [Function]
name object
Returns the object object to the resource name. name must be a symbol naming a resource. object must be an object originally allocated from the same resource.

clear-resource [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]
function name
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 t if the object is in use or nil if it is free, and name. function has dynamic extent.

CLIM 2.0 User's Guide - OCT 1998

Generated with Harlequin WebMaker