Manpage for the stub generator

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

Classifying the methods

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.

No argument to an update method may be of type PROCEDURE or have a component of type PROCEDURE.
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.

Generating stubs using m3build

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