will require different run-time support machinery.
-\subsection{Infrastructure macros} \label{ch:runtime.object.infra}
+\subsection{Layout utilities} \label{sec:runtime.object.layout}
-The runtime support functionality defined here generally expects that
-instances and classes inherit from the standard @|SodObject| root object.
-While the translator can (at some effort) support alternative roots, they
-will require different run-time support machinery.
+The following macros are useful in finding one's way around an instance
+layout structure, given various levels of information about what kind of
+object one is dealing with, or for computing the tables which are used for
+this kind of navigation.
These macros are mostly intended for use in code generated by the Sod
translator. Others may find them useful for special effects, but they can be
tricky to understand and use correctly and can't really be recommended for
general use.
-\begin{describe}[SOD_XCHAIN]{mac}
- {void *SOD_CHAIN(@<chead>, const @<cls> *@<obj>);}
- Performs a `cross-chain upcast'.
-
- Given a pointer @<obj> to an instance of a class of type @<cls> and the
- nickname @<chead> of the least specific class in one of @<cls>'s superclass
- chains which does not contain @<cls> itself, @|SOD_XCHAIN| returns the
- address of that chain's storage within the instance layout as a raw
- @|void~*| pointer. (Note that @<cls> is not mentioned explicitly.)
-
- This macro is used by the generated @|@<CLASS>{}__CONV_@<CLS>| conversion
- macros, which you are encouraged to use instead where possible.
-\end{describe}
-
\begin{describe}[SOD_OFFSETDIFF]{mac}
{ptrdiff_t SOD_OFFSETDIFF(@<type>, @<member>_1, @<member>_2);}
Returns the signed offset between two members of a structure or union type.
@|SOD_INSTBASE| macro (described below) is more suited to general use.
\end{describe}
-
-\subsection{Utility macros} \label{sec:runtime.object.utility}
-
-The following macros are expected to be useful in Sod method definitions and
-client code.
-
-\begin{describe}[SOD_CLASSOF]{mac}
- {const void *SOD_CLASSOF(const @<cls> *@<obj>);}
- Returns the class object describing an instance's dynamic class.
-
- Given a pointer @<obj> to an instance, @|SOD_CLASSOF| returns a pointer to
- @<obj>'s dynamic class, which (assuming @<obj> is typed correctly in the
- first place) will be a subclass of @<cls>. (If you wanted the class object
- for @<cls> itself, it's called @|@<cls>{}__class|.)
-\end{describe}
-
\begin{describe}[SOD_INSTBASE]{mac}{void *SOD_INSTBASE(const @<cls> *@<obj>)}
Finds the base address of an instance's layout.
knowledge of the instance's dynamic class.
\end{describe}
-\begin{describe}[SOD_CONVERT]{mac}
- {@<cls> *SOD_CONVERT(@<cls>, const void *@<obj>);}
-
- Perform general conversions (up-, down-, and cross-casts) on instance
- pointers.
-
- Given a class name @<cls> and a pointer @<obj> to an instance,
- @|SOD_CONVERT| returns an appropriately converted pointer to @<obj> if
- @<obj> is indeed an instance of (some subclass of) @<cls>; otherwise it
- returns a null pointer.
- This macro is a simple wrapper around the @|sod_convert| function described
- below, which is useful in the common case that the target class is known
- statically.
-\end{describe}
+\subsection{Classes} \label{sec:runtime.object.class}
-\begin{describe}[SOD_DECL]{mac}{SOD_DECL(@<cls>, @<var>);}
- Declares and initializes an instance with automatic storage duration.
+The following macros and functions query the runtime relationships between
+instances and classes.
- Given a class name @<cls> and an identifier @<var>, @|SOD_DECL| declares
- @<var> to be a pointer to an instance of @<cls>. The instance is
- initialized in the sense that its vtable and class pointers have been set
- up, and slots for which initializers are defined are set to the appropriate
- initial values.
+\begin{describe}[SOD_CLASSOF]{mac}
+ {const SodClass *SOD_CLASSOF(const @<cls> *@<obj>);}
+ Returns the class object describing an instance's dynamic class.
- The instance has automatic storage duration: pointers to it will become
- invalid when control exits the scope of the declaration.
+ Given a pointer @<obj> to an instance, @|SOD_CLASSOF| returns a pointer to
+ @<obj>'s dynamic class, which (assuming @<obj> is typed correctly in the
+ first place) will be a subclass of @<cls>. (If you wanted the class object
+ for @<cls> itself, it's called @|@<cls>{}__class|.)
\end{describe}
-
-\subsection{Functions} \label{sec:runtime.object.functions}
-
-The following functions are provided in @|libsod|.
-
\begin{describe}[sod_subclassp]{fun}
{int sod_subclassp(const SodClass *@<sub>, const SodClass *@<super>);}
effort has been made to make it perform well it's still not very fast.
\end{describe}
-\begin{describe}[sod_convert]{fun}
- {void *sod_convert(const SodClass *@<cls>, const void *@<obj>);}
- Performs general conversions (up-, down-, and cross-casts) on instance
+
+\subsection{Conversions} \label{sec:runtime.object.conversions}
+
+The following macros and functions are used to convert instance pointers of
+some (static) type into instance pointers of other static types to the same
+instance.
+
+\begin{describe}[SOD_XCHAIN]{mac}
+ {void *SOD_CHAIN(@<chead>, const @<cls> *@<obj>);}
+ Performs a `cross-chain upcast'.
+
+ Given a pointer @<obj> to an instance of a class of type @<cls> and the
+ nickname @<chead> of the least specific class in one of @<cls>'s superclass
+ chains which does not contain @<cls> itself, @|SOD_XCHAIN| returns the
+ address of that chain's storage within the instance layout as a raw
+ @|void~*| pointer. (Note that @<cls> is not mentioned explicitly.)
+
+ This macro is used by the generated @|@<cls>{}__CONV_@<c>| conversion
+ macros, which you are encouraged to use instead where possible.
+\end{describe}
+
+\begin{describe*}
+ {\dhead[SOD_CONVERT]{mac}
+ {@<cls> *SOD_CONVERT(@<cls>, const void *@<obj>);}
+ \dhead[sod_convert]{fun}
+ {void *sod_convert(const SodClass *@<cls>, const void *@<obj>);}}
+ Perform general conversions (up-, down-, and cross-casts) on instance
pointers.
- Given a class pointer @<cls> and an instance pointer @<obj>, @|sod_convert|
- returns an appropriately converted pointer to @<obj> in the case that
- @<obj> is an instance of (some subclass of) @<cls>; otherwise it returns
- null.
+ Given a class @<cls> and a pointer @<obj> to an instance, return an
+ appropriately converted pointer to @<obj> if @<obj> is indeed an instance
+ of (some subclass of) @<cls>; otherwise return a null pointer.
+
+ The @|SOD_CONVERT| macro expects @<cls> to be a class name; the
+ @|sod_convert| function expects a pointer to a class object instead.
This involves a run-time trawl through the class structures: while some
effort has been made to make it perform well it's still not very fast. For
upcasts (where @<cls> is a superclass of the static type of @<obj>) the
automatically defined conversion macros should be used instead, because
- they're much faster and can't fail. When the target class is known
- statically, it's slightly more convenient to use the @|SOD_CONVERT| macro
- instead.
+ they're much faster and can't fail.
+
+ When the target class is known statically, it's slightly more convenient to
+ use the @|SOD_CONVERT| macro than the @|sod_convert| function, since the
+ class object name is longer and uglier, and the macro returns a pointer of
+ the correct type.
+\end{describe*}
+
+
+\subsection{Instance lifecycle}
+\label{sec:runtime.object.lifecycle}
+
+The following macros and functions manage the standard steps along an
+instance's lifecycle.
+
+\subsubsection{Automatic storage duration}
+The following macro constructs an instance with automatic storage duration.
+
+\begin{describe}[SOD_DECL]{mac}{SOD_DECL(@<cls>, @<var>);}
+ Declares and initializes an instance with automatic storage duration.
+
+ Given a class name @<cls> and an identifier @<var>, @|SOD_DECL| declares
+ @<var> to be a pointer to an instance of @<cls>. The instance is
+ initialized in the sense that its vtable and class pointers have been set
+ up, and slots for which initializers are defined are set to the appropriate
+ initial values.
+
+ The instance has automatic storage duration: pointers to it will become
+ invalid when control exits the scope of the declaration.
\end{describe}
%%%----- That's all, folks --------------------------------------------------
.IB cls ,
.IB chead ,
.BI "const void *" obj );
-.PP
-.B const void *\c
-.B SOD_CLASSOF(\c
-.BI "const " cls " *" obj );
.br
.B void *\c
.B SOD_INSTBASE(\c
.BI "const " cls " *" obj );
-.br
-.IB cls " *" \c
-.B SOD_CONVERT(\c
-.IB cls ,
-.BI "const void *" obj );
-.br
-.B SOD_DECL(\c
-.IB cls ,
-.IB var );
.PP
+.B const void *\c
+.B SOD_CLASSOF(\c
+.BI "const " cls " *" obj );
+.br
.B int
.B sod_subclassp(\c
.BI "const SodClass *" sub ,
.BI "const SodClass *" super );
+.PP
+.IB cls " *" \c
+.B SOD_CONVERT(\c
+.IB cls ,
+.BI "const void *" obj );
.br
.B int
.B sod_convert(\c
.BI "const SodClass *" cls ,
.BI "const void *" obj );
+.PP
+.B SOD_DECL(\c
+.IB cls ,
+.IB var );
+.PP
.
.\"--------------------------------------------------------------------------
.SH DESCRIPTION
While the translator can (at some effort) support alternative roots,
they will require different run-time support machinery.
.
-.SS Infrastructure macros
-These macros are mostly intended for use in code
-generated by the Sod translator.
+.SS Layout utilities
+The following macros are useful in
+finding one's way around an instance layout structure,
+given various levels of information about
+what kind of object one is dealing with,
+or for computing the tables which are used for
+this kind of navigation.
+.PP
+These macros are mostly intended for use in
+code generated by the Sod translator.
Others may find them useful for special effects,
but they can be tricky to understand and use correctly
and can't really be recommended for general use.
.PP
The
-.B SOD_XCHAIN
-macro performs a `cross-chain upcast'.
-Given a pointer
-.I cls
-.BI * obj
-to an instance of a class of type
-.I cls
-and the nickname
-.I chead
-of the least specific class in one of
-.IR cls 's
-superclass chains which does not contain
-.I cls
-itself,
-.B SOD_XCHAIN(\c
-.IB chead ,
-.IB obj )
-returns the address of that chain's storage
-within the instance layout as a raw
-.B void *
-pointer.
-(Note that
-.I cls
-is not mentioned explicitly.)
-This macro is used by the generated
-.IB CLASS __CONV_ CLS
-conversion macros,
-which you are encouraged to use instead where possible.
-.PP
-The
.B SOD_OFFSETDIFF
macro returns the signed offset between
two members of a structure or union type.
The
.B SOD_INSTBASE
macro (described below) is more suited to general use.
+.PP
+The
+.B SOD_INSTBASE
+macro finds the base address of an instance's layout.
+Given a pointer
+.BI "const " cls " *" obj
+to an instance,
+.BI SOD_INSTBASE( obj )
+returns the base address of the storage allocated to
+.IR obj .
+This is useful if you want to free a dynamically allocated instance,
+for example.
+This macro needs to look up an offset in
+.IR obj 's
+vtable to do its work.
+Compare
+.B SOD_ILAYOUT
+above,
+which is faster but requires
+precise knowledge of the instance's dynamic class.
.
-.SS Utility macros
-The following macros are expected to be useful
-in Sod method definitions and client code.
+.SS Classes
+The following macros and functions
+query the runtime relationhips between
+instances and classes.
.PP
The
.B SOD_CLASSOF
.IB cls __class \fR.)
.PP
The
-.B SOD_INSTBASE
-macro finds the base address of an instance's layout.
+.B sod_subclassp
+function answers whether one class
+.I sub
+is actually a subclass of another class
+.IR super .
+.B sod_subclassp(\c
+.IB sub ,
+.IB super )
+returns nonzero if and only if
+.I sub
+is a subclass of
+.IR super .
+This involves a run-time trawl through the class structures:
+while some effort has been made to make it perform well
+it's still not very fast.
+.
+.SS Conversions
+The following macros and functions are used
+to convert instance pointers of some (static) type
+into instance pointers of other static types
+to the same instance.
+.PP
+The
+.B SOD_XCHAIN
+macro performs a `cross-chain upcast'.
Given a pointer
-.BI "const " cls " *" obj
-to an instance,
-.BI SOD_INSTBASE( obj )
-returns the base address of the storage allocated to
-.IR obj .
-This is useful if you want to free a dynamically allocated instance,
-for example.
-This macro needs to look up an offset in
-.IR obj 's
-vtable to do its work.
-Compare
-.B SOD_ILAYOUT
-above,
-which is faster but requires
-precise knowledge of the instance's dynamic class.
+.I cls
+.BI * obj
+to an instance of a class of type
+.I cls
+and the nickname
+.I chead
+of the least specific class in one of
+.IR cls 's
+superclass chains which does not contain
+.I cls
+itself,
+.B SOD_XCHAIN(\c
+.IB chead ,
+.IB obj )
+returns the address of that chain's storage
+within the instance layout as a raw
+.B void *
+pointer.
+(Note that
+.I cls
+is not mentioned explicitly.)
+This macro is used by the generated
+.IB cls __CONV_ c
+conversion macros,
+which you are encouraged to use instead where possible.
.PP
The
.B SOD_CONVERT
-macro performs general conversions
+macro
+and
+.B sod_convert
+function
+perform general conversions
(up-, down-, and cross-casts) on instance pointers.
-Given a class name
+Given a class
.I cls
and a pointer
.BI "const void *" obj
to an instance,
-.B SOD_CONVERT(\c
-.IB cls ,
-.IB obj )
-returns an appropriately converted pointer to
+they return an appropriately converted pointer to
.I obj
if
.I obj
is indeed an instance of (some subclass of)
.IR cls ;
-otherwise it returns a null pointer.
-This macro is a simple wrapper around the
+otherwise they return a null pointer.
+.PP
+The
+.B SOD_CONVERT
+macro expects
+.I cls
+to be a class name;
+the
+.B sod_convert
+function
+expects a pointer to a class object instead.
+.PP
+This involves a run-time trawl through the class structures:
+while some effort has been made to make it perform well
+it's still not very fast.
+For upcasts (where
+.I cls
+is a superclass of the static type of
+.IR obj )
+the automatically defined conversion macros should be used instead,
+because they're much faster and can't fail.
+.PP
+When the target class is known statically,
+it's slightly more convenient to use the
+.B SOD_CONVERT
+macro rather than the
.B sod_convert
-function described below,
-which is useful in the common case that
-the target class is known statically.
+function,
+since the class object name is longer and uglier,
+and the macro returns a pointer of the correct type.
+.
+.SS Instance lifecycle
+The following macros and functions
+manage the standard steps along
+an instance's lifecycle.
.PP
The
.B SOD_DECL
pointers to it will become invalid when control
exits the scope of the declaration.
.
-.SS Functions
-The following functions are provided.
-.PP
-The
-.B sod_subclassp
-function answers whether one class
-.I sub
-is actually a subclass of another class
-.IR super .
-.B sod_subclassp(\c
-.IB sub ,
-.IB super )
-returns nonzero if and only if
-.I sub
-is a subclass of
-.IR super .
-This involves a run-time trawl through the class structures:
-while some effort has been made to make it perform well
-it's still not very fast.
-.PP
-The
-.B sod_convert
-function performs general conversions
-(up-, down-, and cross-casts) on instance pointers.
-Given a class pointer
-.I cls
-and an instance pointer
-.IR obj ,
-.B sod_convert(\c
-.IB cls ,
-.IB obj )
-returns an appropriately converted pointer to
-.I obj
-in the case that
-.I obj
-is an instance of (some subclass of)
-.IR cls ;
-otherwise it returns null.
-This involves a run-time trawl through the class structures:
-while some effort has been made to make it perform well
-it's still not very fast.
-For upcasts (where
-.I cls
-is a superclass of the static type of
-.IR obj )
-the automatically defined conversion macros should be used instead,
-because they're much faster and can't fail.
-When the target class is known statically,
-it's slightly more convenient to use the
-.B SOD_CONVERT
-macro instead.
-.
.\"--------------------------------------------------------------------------
.SH SEE ALSO
.BR sod (1),
~mdw / sod / commitdiff