GLOBALRESOURCE

This file contains mechanisms for handling global resources, ensuring
that consumers of such resources don't trash each other.

There are two parts to the facility:  a file package command and a set of
five functions (actually, only the macros exist).

A global resource is named, and associated with that name is a form which will
create new instances of that resource.  The association between names and forms
is maintained on the list GLOBAL.RESOURCES, each element of which is of the
form (name instanceform).  Thus, the entry for \PNAMESTRING on this list
would be (\PNAMESTRING (ALLOCSTRING \PNAMELIMIT)).

The file package command GLOBALRESOURCES should be used to declare global
resources.  It takes a list of pairs as above as its arguments.  Thus
	(GLOBALRESOURCES (\NUMSTR (ALLOCSTRING 38))
				   (\PNAMESTRING (ALLOCSTRING 100)))
is a plausible example of this command.  The command not only will make the
entries on GLOBAL.RESOURCES, but also initialize the value cells of the
resource names to NIL (a necessary thing to do).  NB:  Because of this
initialization, the GLOBALRESOURCES command must NOT be embedded in a DONTCOPY.
Presumably, this command will be EXPORTed.

The functions/macros RESOURCECONTEXT, GETRESOURCE, FREERESOURCE, and
RELEASERESOURCE are the primitives for utilizing resources.

 (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.

  (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).

  (FREERESOURCE resource-name) makes the resource available for other uses.

GETRESOURCE and FREERESOURCE will cause compile-time errors if they are
not within the lexical scope of a matching RESOURCECONTEXT, and
RESOURCECONTEXT will cause a compile-time error if any of the resource
names has not been declared.

  (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 a 
compile-time error 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 functions 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 function
GLOBALRESOURCE may be used.
  (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)

-----
Comments and suggestions to Ron Kaplan