initialization of class metaobjects

[Gregor J. Kiczales <gregor@parc.xerox.com>]

Following is the section from the `functi' pages that deals with the
initialization of class metaobjects.  This covers the use of
MAKE-INSTANCE and REINITIALIZE-INSTANCE with class metaobjects.  The
file arisia.xerox.com:/ftp/pcl/mop/init.ps contains postscript source
for this material.

When you read this, please review not only the specific material about
class metaobjects, but also the framework used to present it.  That is
what has taken most of the work in preparing this section.  If this
framework works, cranking out initialization of generic functions,
methods, slot definitions and method combinations is easy.

----------------


\begincom{Initialization of Class Metaobjects}\ftype{}

A class metaobject can be created by calling {\bf make-instance}.  The
initialization arguments establish the definition of the class.  A class
metaobject can be reinitialized by calling {\bf reinitialize-instance}.
Some classes of class metaobject do not support reinitialization; in
these cases, {\bf reinitialize-instance} signals an error.

Initialization of a class metaobject must be done by calling {\bf
make-instance} and allowing it to call {\bf initialize-instance}.
Reinitialization of a class metaobject must be done by calling {\bf
reinitialize-instance}.  Portable programs must not call {\bf
intialize-instance} directly to initialize a class metaboject.  Portable
programs must not call {\bf shared-intialize} directly to initialize or
reinitialize a class metaboject.

A description of the interpretation of each initialization argument is
presented first, this is followed by a description of the special
behavior of each of the specified classes of class metaobject.

In these descriptions, the phrase ``this argument defaults to {\it
value}'' means that when the initialization argument is not supplied,
initialization or reinitialization proceeds as if {\it value} had been
supplied.  Whether this is done through the use of default
initialization arguments is not specified.  Whether any specified class
of class metaobjects has default initialization arguments is not
specified.  Implementations are free to do so.  Portable programs are
free to define default initialization arguments on portable subclasses
of the class {\bf class}.

\beginlist

\item{\bull} The {\bf :direct-superclasses} argument is a list of class
metaobjects.  Classes which do not support multiple inheritance signal
an error if the list contains more than one element.

An error is signalled if this value is not a proper list; or if it is
the empty list; or if {\bf validate-superclass} returns false for any
element of the list.

When the class is being initialized, and this argument is not supplied,
an error is signalled.  If this argument is supplied, the generic
function {\bf add-direct-subclass} is called once for each element of
the list.

When the class is being reinitialized, and this argument is not
supplied, it defaults to the result of calling {\bf
class-direct-superclasses} with the class metaobject as the argument.
If this argument is supplied, the generic function {\bf
remove-direct-subclass} is called once for each class in the result of
calling {\bf class-direct-superclasses} but not in the list; and the
generic function {\bf add-direct-subclass} is called once for each class
which is in the list but not in the result of {\bf
class-direct-superclasses}.

\item{\bull} The {\bf :direct-slots} argument is a list of direct slot
definition metaobjects.

An error is signalled if this value is not a proper list or; if any
element of the list is not an instance of the class {\bf
direct-slot-definition} or one of its subclasses.

If the class is being initialized, this argument defaults to false.

If the class is being reinitialized, this argument defaults to the
result of calling {\bf class-direct-slots} with the class metaobject as
the argument.

\item{\bull} The {\bf :direct-default-initargs} argument is a list of
canonicalized default initargs.

An error is signalled if this value is not a proper list; or if any
element of the list is not a canonicalized default initarg.

If the class is being initialized, this argument defaults to the empty
list.

If the class is being reinitialized, this argument defaults to the
result of calling {\bf class-direct-default-initargs} with the class
metaobject as the argument.

\item{\bull}  The {\bf :documentation} argument is a string or false.

An error is signalled if this value is not a string or false.

If the class is being initialized, this argument defaults to the empty
list. 

If the class is being reinitialized, this argument defaults to the
result of calling {\bf documentation} with the class metaobject as the
argument.

\endlist

\vskip 2pc

After the processing and defaulting of initialization arguments
described above, the value of each initialization argument is associated
with the metaobject.  These values can then be accessed by calling the
corresponding generic function.  The correspondences are as follows:

\boxfig
{\dimen0=.75pc
\tabskip \dimen0 plus .5 fil
\halign to \hsize {#\hfil&\quad#\hfil\cr
\noalign{\vskip -9pt}
\bf Initialization Argument&\bf Generic Function\cr
\noalign{\vskip 2pt\hrule\vskip 2pt}
\bf :direct-superclasses&\bf class-direct-superclasses\cr
\bf :direct-slots&\bf class-direct-slots \cr
\bf :direct-default-initargs&\bf class-default-initargs \cr
\bf :documentation&\bf documentation \cr
\noalign{\vskip -9pt}}}
\endfig

\label Standard Classes:

Standard classes support multiple inheritance and reinitialization.

\label Structure Classes:

Structure classes support single-inheritance.  An error is signalled if
{\bf initialize-instance} is called to initialize a structure class
metaobject and the length of the {\bf :direct-superclasses} argument is
greater than one.

It is not specified whether structure classes support reinitialization.
The results are undefined if {\bf reinitialize-instance} is called to
reinitialize a structure class metaobject.

\label Built-in Classes:

Built-in classes cannot be created by the user, and cannot be
reinitialized.  

An error is signalled if {\bf initialize-instance} or {\bf
reinitialize-instance} are called to initialize or reinitialize a
built-in class metaobject.

\label Methods:

It is not specified what methods provide the initialization and
reinitialization behavior described above.  Instead, the information
needed to allow portable programs to specialize this behavior is
presented in terms of a set of restrictions on the methods a portable
program can define.

These restrictions govern the methods that a portable program can define
on the generic functions {\bf initialize-instance}, {\bf
reinitialize-instance}, and {\bf shared-initialize}.  These restrictions
apply only to methods on these generic functions for which the first
specializer is a subclass of the class {\bf class}.  Other portable
methods on these generic functions are not affected by these
restrictions.  The results are undefined if any of these restrictions
are violated.

\beginlist

\item{\bull} Portable programs must not define methods on {\bf
shared-initialize}.

\item{\bull} Portable programs must not define primary methods on the
generic function {\bf initialize-instance}.

\item{\bull} Portable programs must not define primary methods on the
generic function {\bf reinitialize-instance}.

\item{\bull} Portable programs may define around methods on the generic
function {\bf initialize-instance}, but these must be shadowing, not
overriding methods.

\item{\bull} Portable programs may define around methods on the generic
function {\bf reinitialize-instance}, but these must be shadowing, not
overriding methods.

\item{\bull} A portable before method on the generic function {\bf
initialize-instance} must assume that when it is run, the class
metaobject has not been initialized.

\item{\bull} A portable after method on the generic function {\bf
initialize-instance} must assume that when it is run, the class
metaobject has been completely initialized.

\item{\bull} A portable before method on the generic function {\bf
reinitialize-instance} must assume that when it is run, no
reinitialization of the class metaobject has been done.

\item{\bull} A portable after method on the generic function {\bf
reinitialize-instance} must assume that when it is run, the class
metaobject has been completely reinitialized.

\endlist

\endcom