{Begin SubSec Global Resources}
{Title Global Resources}
{Text


{Begin Note}
File:		<lispmanual>GlobalResource.im
Written:	December 1982
Revised:	Feb 21, 1983, by JonL White
translated to IM format Tue, 13 Sep 83 09:47 PDT by mjs

The GLOBALRESOURCE file contains mechanisms for handling global
resources, ensuring that consumers of such resources don't clobber each other. 
There are two parts to the facility:  a file package type, and a set of five 
macros for paradigmatic usage.
{End Note}


A "global resource" is an association between a name (non-{lisp NIL} litatom) and a form to be evaluated for producing fresh instances of the resource.  Most often, a "resource" is some chunk of data which one may want to use as temporary storage.   For example, a list which will be given as second argument to {fn DCHCON}, or a string used as some kind of character buffer;  but in fact it can be any non-{lisp NIL} object returned by the defining form.

A global resource, in this context, will be stored in a {lisp GLOBALVAR}, and users of that resource obtain it through the VAR. The normal use of such a "resource" is to take the instance from the VAR, set the VAR to {lisp NIL}, do some associated code, and then "give back" the instance by setting it back into VAR; in the case when VAR found to be {lisp NIL}, then a fresh instance is created, which will later be put back into VAR.  

Thus a function will not clobber the instance of the resource in use at a "higher" function-call level.   On the other hand, only the topmost instance will be spared from the ravages of the garbage collector.   The expectation is that creating fresh instances for each toplevel usage is "costly" (either in construction time or subsequent reclamation time);  a further expectation is that there will be few simultaneous usages of a given resource, so it is better to let these instances be reclaimed, rather than hoarding them for some possible future collision.


                Defining GLOBALRESOURCES

Since GLOBALRESOURCES is a filepkgtype, one may use PUTDEF to
define a resource; and the filepkgcom GLOBALRESOURCES should 
be used to declare them.    The file package command takes a list of pairs 
as its argument, each pair consisting of a resource name and its associated
form for making new instances.  For example,
	(GLOBALRESOURCES (\NUMSTR (ALLOCSTRING 38))
				   (\PNAMESTRING (ALLOCSTRING 100)))
is a plausible example.  
Note well: Because it is necessary to initialize the name of a resource to
NIL, the GLOBALRESOURCES command must NOT be embedded in a DONTCOPY.  

[Presumably, this command will be EXPORTed; if you don't know what 
EXPORT is, don't worry about it.]


        Primitives for Using GLOBALRESOURCES

The macros RESOURCECONTEXT, GETRESOURCE, FREERESOURCE, and
RELEASERESOURCE are the lower-level primitives for utilizing resources.
A fifth macro, GLOBALRESOURCE, is restricted to simple lexical scoping,
and is the primary facililty to be used by users.

RESOURCECONTEXT        (RESOURCECONTEXT resource-names . forms) 
    sets up an environment whereby the resources in resource-names may be
    used inside (the lexical scope of) forms.   The resource may be referred 
    to in forms by its name.  The user is responsible for explicitly getting 
    and freeing the various resources by specifying GETRESOURCE and 
    FREERESOURCE inside forms.  The value of RESOURCECONTEXT is the value
    of the last form.    Will cause an error at macro expansion time if any 
    of the resource names have not been declared.

GETRESOURCE              (GETRESOURCE resource-name) 
    makes an instance of resource-name available inside the current resource
    context.  A new instance will be created if the resource is currently in 
    use.  The resource itself is the value of GETRESOURCE, and the resource
    may be referred to by resource-name in subsequent statements inside the
    current resource context (until another GETRESOURCE or FREERESOURCE of that
    name is invoked).  Will cause an error at macro expansion time if not within
    the lexical scope of a matching RESOURCECONTEXT.

FREERESOURCE             (FREERESOURCE resource-name) 
    makes the resource available for other uses.  Will cause an error at 
    macro expansion time if not within the lexical scope of a matching
    RESOURCECONTEXT.

RELEASERESOURCE       (RELEASERESOURCE rname rvalvar . forms)
    provides a mechanism for releasing a resource during the evaluation of 
    forms but reacquiring the resource after forms have been executed.  
    This need not appear in the lexical scope of a RESOURCECONTEXT, but
    rvalvar must be the name of a variable whose current value is the result 
    of a GETRESOURCE.   The value of rvalvar is "released"--made available for
    other consumers inside forms, and that variable is then set to another
    instance (usually the same) of the resource for subsequent use (and 
    freeing).    RELEASERESOURCE causes an error at macro expansion time if
    rname is not a valid resource name.  Note:  the user must guarantee that 
    the value of rvalvar is in fact a legitimate instance of rname.

These 4 macros allow resource management to be intertwined with other
complicated control structures, such as in the \SUBREAD function.  When 
the scope of resource usage conforms to simple control scopes, the macro
GLOBALRESOURCE may be used.

GLOBALRESOURCE     (GLOBALRESOURCE resource-names . forms) 
    sets up a RESOURCECONTEXT, then does the appropriate GETRESOURCEs,
    evaluates forms, and does the appropriate FREERESOURCEs.  Its value 
    is the value of the last form.

CAUTION:  It is up to the user of these facilities to make sure that a 
resource isn't being used implicitly after it has been freed (e.g. by passing 
it back as a value)


          Implementational Note:

The association between names and forms is maintained as list on the global
varialbe  GLOBAL.RESOURCES, each element of which is a 2-list of the form 
      (name instanceform)
just as would be put on the file package command.



}{End SubSec Global Resources}