B.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. [annotate]

Note:

In general I think that this resource stuff is already a good abstraction, however I miss a thing: Resources really should be first class objects. So that say a port can have a [private] resource on stuff like 1x1 pixel pixmaps of a certain color, or similar things. Of course you can always include a port argument but that isn't ideal. Also missing is some way to specify the maximum number of objects hold in the resource.

But then, I what really want is a cache, I suppose.

[edit]-- Gilbert Baumann 2004-12-12 17:12Z
 

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. [annotate]

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. [annotate]

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. [annotate]

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. [annotate]

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. [annotate]

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. [annotate]

[annotate]

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. [annotate]

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. [annotate]

[annotate]

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. [annotate]

[annotate]

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. [annotate]

[annotate]

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. [annotate]

[annotate]

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. [annotate]

[annotate]