6.4 The Resource Facility

6.4.2 Reference pages

Syntax:clear-resource resource

The functionclear-resource removes all existing objects from the specified resource.

Any future calls to the functionresource-allocate for the specified resource create new objects.

The functionresource-allocate removes any pointers from the resource to the object before allocating that object, and the function resource-deallocate restores the pointers when the object is deallocated. Thus, the Resource Facility does not maintain any pointers to objects that are currently in use.

The functionclear-resource removes all pointers to an object that the resource maintains.Thus, you can include a call toclear-resource in functions that invoke a garbage collection to allow objects that are not in use to be reclaimed.

See Also: resource-allocate, resource-deallocate

Syntax:make-resource name&key :constructor :initial-copies:initialization-function :cleanup-function :initial-args

The functionmake-resource creates and returns a resource object.

The name argument is the name of the resource; you need this argument for printing purposes only.

You can specify any of the following keyword arguments:

• :constructor

This keyword argument is a function that creates an object when an empty resource is given as the required argument to the functionresource-allocate. The constructor function that you supply must accept the arguments specified in the args argument toresource-allocate. It returns a resource object; it should not returnnil.

• :initial-copies

If you supply this keyword argument, it must be an integer that indicates the number of times the constructor function makes objects available for allocation. The constructor function uses the:initial-args argument list when making objects. If the specified constructor function is a function of no arguments, you do not need to supply the:initial-args keyword option.

If you do not specify the:initial-copies argument, the resource is created empty. The first time that the functionresource-allocate is invoked, the constructor function makes an object to allocate.

• :initialization-function

This keyword argument is a function that is called when an object is allocated from the resource; it is passed the allocated object and the arguments specified in the args argument toresource-allocate. The initialization function is not called on objects that are created by the constructor function.

• :cleanup-function

This keyword argument is a function that is called when the function resource-deallocate returns an object to the resource. The function that you specify must take one argument, the object being deallocated.

You might use this function to indicate that subparts of an object can be reclaimed by garbage collection. For example, if you had an array of strings as an object in a resource and you no longer needed pointers to the array elements, you could use the cleanup function to set all of the elements of the array to be the null string. The elements in the array that are not referenced by other functions can then be reclaimed.

By default, no cleanup function is called on an object.

• :initial-args

This keyword argument is a list of arguments that is passed to the constructor function when you supply the:initial-copies keyword argument. If the constructor function takes no arguments or if you have not specified a value for:initial-copies, you do not need to supply this list.

To make the manipulation of resources easier, you might want to store the resource that is returned by this function in a global variable.

See Also: resource-allocate

Syntax:resource-allocate resource&rest args

The functionresource-allocate allocates an object from the specified resource and sets any pointer to the object in the resource tonil.

An object that is allocated but has not been deallocated is said to be in use.

The resource argument specifies the resource object that is allocated.

If the resource is empty,resource-allocate callsmake-resource and passes the arguments specified by args to the constructor function. The object returned by the constructor function is returned byresource-allocate.

If the resource is not empty,resource-allocate passes the specified args to the initialization function ofmake-resource before allocating the object.

See Also: make-resource, resource-deallocate

Syntax:resource-deallocate resource object

The functionresource-deallocate returns an object to the specified resource.

The resource argument specifies the resource that receives the deallocated object.

The object argument specifies the object to be returned to the resource; it must be an object that was allocated from the specified resource and that has not been deallocated. Note thatresource-deallocate cannot check whether the specified object was allocated from the specified resource.

See Also: resource-allocate, clear-resource

Syntax:using-resource (object-var resource&rest args) {form}*

The macrousing-resource allocates an object from the specified resource, binds a variable to it, and then invokes a Common Lispunwind-protect special form.

An object that is allocated but has not been deallocated is said to be in use.

The object-var argument specifies a variable that is bound to the specified resource argument. After the body of theunwind-protect special form has been executed,using-resource checks the value of this variable. If the value isnil, the object is not returned to the resource; otherwise, the object is deallocated.

You should not modify the object-var argument in any other way than by setting its value tonil.

The args arguments are passed to the functionresource-allocate to allocate the object before the execution of the form arguments.

Generated with Harlequin WebMaker