stablegen(1) stablegen(1)
Name
stablegen -- Generate stubs for stable objects.
Syntax
stablegen
[-i Interfaces] [-o StableObjectIntf] [-im StableObjectImpl] [-rm
RepModule] [options]
Description
The program stablegen generates stubs for Modula-3 stable objects. Sta-
ble objects are Modula-3 objects whose state is backed up on the disk
or other stable medium, so that it will survive program crashes.
It is not intended to be used from the command line. Use m3build and
the quake macros stableobj and Stableobj instead to run the stub gener-
ator (see the m3build section below).
The command
stablegen -i Data -o Data -im Impl -rm Rep
writes into "Impl.m3" an implementation of the generic interface
"Stable(Data)". See this generic interface for the specifications of
the methods and procedures implemented by stablegen. Thus Data should
be the name of an interface and Data.T should name an object type;
stablegen implements a stable version of Data.T and writes the
implementation to "Impl.m3". Impl defaults to the objects interface
name as stated in the -o option with "Stable" prepended. All
interfaces that contain revealations of Data.T must be listed after the
-i parameter. The first interface of the list must contain the most
specific supertype of Data.T. In most cases this will be Data itself.
But if Data does not state any more specific supertyp of Data.T than
ROOT, the interface listet after the -i will be the one containing the
most specific revealation.
To complete your program, you should include in the file "Impl.i3" the
text
INTERFACE Impl = Stable(Data) END Impl.
The implementation of stable objects consists of two modules. The
first is generated by stablegen, the second is an instantiation of the
generic module "StableRep". The name of this second module is stated
after the -rm option. It defaults to the name of the generated
implementation Impl with "Rep" appended. If both module names are
defaulted, "StableDataRep" will be used for the generic's
instantiation. So in the file "Rep.i3" you will need the text
INTERFACE Rep = StableRep(Impl) END Rep.
And the file "Rep.m3" looks like
MODULE Rep = StableRep(Impl) END REP.
The m3build macros will also generate all these files (see below).
The interface "Data.i3" presented to the stub generator must contain a
pragma that lists all methods of Data.T that modify the state of the
object. The pragma has the form
<* STABLE UPDATE METHODS m_1, ..., m_k *>
where the m's are the names of the update methods of Data.T. The stub
generator will override these methods to log their arguments before
calling the corresponding method of the supertype. The stub generator
will not override the other methods of Data.T; the stable object will
simply inherit them from its supertype. The pragma may appear more
than once (the list stated in the second pragma will be appended to
those methods already mentioned). You may use ANY instead of a list of
methods in which case all methods of the object are treated as update
methods.
Options
The stub generator is based on the Modula 3 toolkit, therefore the
other options defined by the toolkit are available. See the manpage
for m3fe for a list of these options. In particular, it is possible to
set the search path used by the stub generator with the -Tx option,
where x is the name of a map file generated by m3build. The name of
the map file associated with package P and build directory B is
P/B/.M3IMPORTS. It is also possible to set a specific search path with
the -D option, though this is usually more trouble than it is worth.
You may use -help instead of any other options to get a list of
available options.
Restrictions
As mentioned before, not all types Data.T are valid for stub
generation. The following restrictions apply. The stub generator will
not produce stubs for types that violate any of the restrictions.
1. No argument to an update method may be of type PROCEDURE or
have a component of type PROCEDURE.
2. The name of the update methods listed in the STABLE UPDATE
METHODS pragma must not conflict with the names of the
stable object methods as declared in Stable.ig.
The marshaling of parameters to update methods is performed as for
network objects, as specified in the documentation for stubgen.
Currently the macros described here only support the defaults for the
filenames of the generated module and the instatiated generic part of
the implementation.
It is possible to manage stub generation using m3build. You must put
the following line in your m3makefile, prior to any occurrences of one
of the macros:
import("stable")
To state that an interface Data contains a stable object use one of the
macros:
stableobj("Data", [])
Stableobj("Data", [])
(Stableobj sets the visability of the stable object's interface to
visible, stableobj to hidden) which generates stubs for Data.T, storing
them in "StableData.m3". It generate the instatiation of Stable.ig in
"StableData.i3" and the instatiation of the generic part of the
implementation (StableRep) in "StableDataRep.i3" and
"StableDataRep.i3". It also arranges for the generated stubs to be
compiled and linked into the program.
The second parameter of the macros is a list of interfaces that Data
depends on. The first in the list must be the interface containing the
most specific exported revealation of Data.T. The following interface
names are only used to trigger stablegen correctly. If one of those
interfaces are changed, stablegen will be run again on the next call of
m3build.
If the second parameter is the empty list, it is assumed that "Data.i3"
is the only interface containing definitions necessary for Data.T.
The rules for importing interfaces during stub generation are the same
as those for compilation under m3build. See the m3build manpage for
further detail.
Copyright
Copyright (C) 1994, Digital Equipment Corporation.
Distributed only by permission.
Last modified on Thu Jan 19 14:28:03 PST 1995 by kalsow
modified on Tue Sep 27 11:52:22 PDT 1994 by weich
stablegen(1)