chiark - git - mdw - sod/blob - doc/runtime.tex

   1 %%% -*-latex-*-
   2 %%%
   3 %%% The runtime library
   4 %%%
   5 %%% (c) 2015 Straylight/Edgeware
   6 %%%
   7
   8 %%%----- Licensing notice ---------------------------------------------------
   9 %%%
  10 %%% This file is part of the Simple Object Definition system.
  11 %%%
  12 %%% SOD is free software; you can redistribute it and/or modify
  13 %%% it under the terms of the GNU General Public License as published by
  14 %%% the Free Software Foundation; either version 2 of the License, or
  15 %%% (at your option) any later version.
  16 %%%
  17 %%% SOD is distributed in the hope that it will be useful,
  18 %%% but WITHOUT ANY WARRANTY; without even the implied warranty of
  19 %%% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20 %%% GNU General Public License for more details.
  21 %%%
  22 %%% You should have received a copy of the GNU General Public License
  23 %%% along with SOD; if not, write to the Free Software Foundation,
  24 %%% Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  25
  26 \chapter{The runtime library} \label{ch:runtime}
  27
  28 This chapter describes the runtime support macros and functions provided by
  29 the Sod library.  The common structure of object instances and classes is
  30 described in \xref{ch:structures}.
  31
  32 %%%--------------------------------------------------------------------------
  33 \section{Object system support} \label{sec:runtime.object}
  34
  35 This section describes the macros and functions exposed in the @|<sod/sod.h>|
  36 header file which provide assistance for working with Sod classes and
  37 objects.
  38
  39 The runtime support functionality defined here generally expects that
  40 instances and classes inherit from the standard @|SodObject| root object.
  41 While the translator can (at some effort) support alternative roots, they
  42 will require different run-time support machinery.
  43
  44
  45 \subsection{Infrastructure macros} \label{ch:runtime.object.infra}
  46
  47 The runtime support functionality defined here generally expects that
  48 instances and classes inherit from the standard @|SodObject| root object.
  49 While the translator can (at some effort) support alternative roots, they
  50 will require different run-time support machinery.
  51
  52 These macros are mostly intended for use in code generated by the Sod
  53 translator.  Others may find them useful for special effects, but they can be
  54 tricky to understand and use correctly and can't really be recommended for
  55 general use.
  56
  57 \begin{describe}[SOD_XCHAIN]{mac}
  58     {void *SOD_CHAIN(@<chead>, const @<cls> *@<obj>);}
  59   Performs a `cross-chain upcast'.
  60
  61   Given a pointer @<obj> to an instance of a class of type @<cls> and the
  62   nickname @<chead> of the least specific class in one of @<cls>'s superclass
  63   chains which does not contain @<cls> itself, @|SOD_XCHAIN| returns the
  64   address of that chain's storage within the instance layout as a raw
  65   @|void~*| pointer.  (Note that @<cls> is not mentioned explicitly.)
  66
  67   This macro is used by the generated @|@<CLASS>{}__CONV_@<CLS>| conversion
  68   macros, which you are encouraged to use instead where possible.
  69 \end{describe}
  70
  71 \begin{describe}[SOD_OFFSETDIFF]{mac}
  72     {ptrdiff_t SOD_OFFSETDIFF(@<type>, @<member>_1, @<member>_2);}
  73   Returns the signed offset between two members of a structure or union type.
  74
  75   Given a structure or union type @<type>, and two member names @<member>_1
  76   and @<member>_2, then @|SOD_OFFSETDIFF| gives the difference, in bytes,
  77   between the addresses of objects @|$x$.@<member>_1| and @|$x$.@<member>_2|
  78   for any object $x$ of type @<type>.
  79
  80   This macro is used internally when generating vtables and is not expected
  81   to be very useful elsewhere.
  82 \end{describe}
  83
  84 \begin{describe}[SOD_ILAYOUT]{mac}
  85     {@<cls>{}__ilayout *SOD_ILAYOUT(@<cls>, @<chead>, const void *@<obj>);}
  86   Recovers the instance layout base address from a pointer to one of its
  87   instance chains.
  88
  89   Specifically, given a class name @<cls>, the nickname @<chead> of the least
  90   specific class in one of @<cls>'s superclass chains, and a pointer @<obj>
  91   to the instance storage for the chain containing @<chead> within a direct
  92   instance of @<cls> (i.e., not an instance of any proper subclass),
  93   @|SOD_ILAYOUT| returns the a pointer to the layout structure containing
  94   @<obj>.
  95
  96   This macro is used internally in effective method bodies and is not
  97   expected to be very useful elsewhere since it's unusual to have such
  98   specific knowledge about the dynamic type of an instance.  The
  99   @|SOD_INSTBASE| macro (described below) is more suited to general use.
 100 \end{describe}
 101
 102
 103 \subsection{Utility macros} \label{sec:runtime.object.utility}
 104
 105 The following macros are expected to be useful in Sod method definitions and
 106 client code.
 107
 108 \begin{describe}[SOD_CLASSOF]{mac}
 109     {const void *SOD_CLASSOF(const @<cls> *@<obj>);}
 110   Returns the class object describing an instance's dynamic class.
 111
 112   Given a pointer @<obj> to an instance, @|SOD_CLASSOF| returns a pointer to
 113   @<obj>'s dynamic class, which (assuming @<obj> is typed correctly in the
 114   first place) will be a subclass of @<cls>.  (If you wanted the class object
 115   for @<cls> itself, it's called @|@<cls>{}__class|.)
 116 \end{describe}
 117
 118 \begin{describe}[SOD_INSTBASE]{mac}{void *SOD_INSTBASE(const @<cls> *@<obj>)}
 119   Finds the base address of an instance's layout.
 120
 121   Given a pointer @<obj> to an instance, @|SOD_INSTBASE| returns the base
 122   address of the storage allocated to @<obj>.  This is useful if you want to
 123   free a dynamically allocated instance, for example.
 124
 125   This macro needs to look up an offset in @<obj>'s vtable to do its work.
 126   Compare @|SOD_ILAYOUT| above, which is faster but requires precise
 127   knowledge of the instance's dynamic class.
 128 \end{describe}
 129
 130 \begin{describe}[SOD_CONVERT]{mac}
 131     {@<cls> *SOD_CONVERT(@<cls>, const void *@<obj>);}
 132
 133   Perform general conversions (up-, down-, and cross-casts) on instance
 134   pointers.
 135
 136   Given a class name @<cls> and a pointer @<obj> to an instance,
 137   @|SOD_CONVERT| returns an appropriately converted pointer to @<obj> if
 138   @<obj> is indeed an instance of (some subclass of) @<cls>; otherwise it
 139   returns a null pointer.
 140
 141   This macro is a simple wrapper around the @|sod_convert| function described
 142   below, which is useful in the common case that the target class is known
 143   statically.
 144 \end{describe}
 145
 146 \begin{describe}[SOD_DECL]{mac}{SOD_DECL(@<cls>, @<var>);}
 147   Declares and initializes an instance with automatic storage duration.
 148
 149   Given a class name @<cls> and an identifier @<var>, @|SOD_DECL| declares
 150   @<var> to be a pointer to an instance of @<cls>.  The instance is
 151   initialized in the sense that its vtable and class pointers have been set
 152   up, and slots for which initializers are defined are set to the appropriate
 153   initial values.
 154
 155   The instance has automatic storage duration: pointers to it will become
 156   invalid when control exits the scope of the declaration.
 157 \end{describe}
 158
 159
 160 \subsection{Functions} \label{sec:runtime.object.functions}
 161
 162 The following functions are provided in @|libsod|.
 163
 164 \begin{describe}[sod_subclassp]{fun}
 165     {int sod_subclassp(const SodClass *@<sub>, const SodClass *@<super>);}
 166
 167   Decide whether one class @<sub> is actually a subclass of another class
 168   @<super>.
 169
 170   The @<sod_subclassp> function returns nonzero if and only if
 171   @<sub> is a subclass of @<super>.
 172
 173   This involves a run-time trawl through the class structures: while some
 174   effort has been made to make it perform well it's still not very fast.
 175 \end{describe}
 176
 177 \begin{describe}[sod_convert]{fun}
 178     {void *sod_convert(const SodClass *@<cls>, const void *@<obj>);}
 179   Performs general conversions (up-, down-, and cross-casts) on instance
 180   pointers.
 181
 182   Given a class pointer @<cls> and an instance pointer @<obj>, @|sod_convert|
 183   returns an appropriately converted pointer to @<obj> in the case that
 184   @<obj> is an instance of (some subclass of) @<cls>; otherwise it returns
 185   null.
 186
 187   This involves a run-time trawl through the class structures: while some
 188   effort has been made to make it perform well it's still not very fast.  For
 189   upcasts (where @<cls> is a superclass of the static type of @<obj>) the
 190   automatically defined conversion macros should be used instead, because
 191   they're much faster and can't fail.  When the target class is known
 192   statically, it's slightly more convenient to use the @|SOD_CONVERT| macro
 193   instead.
 194 \end{describe}
 195
 196 %%%----- That's all, folks --------------------------------------------------
 197
 198 %%% Local variables:
 199 %%% mode: LaTeX
 200 %%% TeX-master: "sod.tex"
 201 %%% TeX-PDF-mode: t
 202 %%% End: