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