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 \begin{describe}[SOD_CAR]{mac} {@<arg> SOD_CAR(@<arg>, @<other-arg>^*);}
  91   Accepts one or more arguments and expands to just its first argument,
  92   discarding the others.
  93
  94   It is only defined if the C implementation advertises support for C99.  It
  95   is used in the definitions of message convenience macros for messages which
  96   accept a variable number of arguments but no required arguments, and is
  97   exported because the author has found such a thing useful in other
  98   contexts.
  99 \end{describe}
 100
 101 %%%--------------------------------------------------------------------------
 102 \section{Utility macros} \label{sec:runtime.utility}
 103
 104 The following macros are expected to be useful in Sod method definitions and
 105 client code.
 106
 107 \begin{describe}[SOD_CLASSOF]{mac}
 108     {const void *SOD_CLASSOF(const @<cls> *@<obj>);}
 109   Returns the class object describing an instance's dynamic class.
 110
 111   Given a pointer @<obj> to an instance, @|SOD_CLASSOF| returns a pointer to
 112   @<obj>'s dynamic class, which (assuming @<obj> is typed correctly in the
 113   first place) will be a subclass of @<cls>.  (If you wanted the class object
 114   for @<cls> itself, it's called @|@<cls>{}__class|.)
 115 \end{describe}
 116
 117 \begin{describe}[SOD_INSTBASE]{mac}{void *SOD_INSTBASE(const @<cls> *@<obj>)}
 118   Finds the base address of an instance's layout.
 119
 120   Given a pointer @<obj> to an instance, @|SOD_INSTBASE| returns the base
 121   address of the storage allocated to @<obj>.  This is useful if you want to
 122   free a dynamically allocated instance, for example.
 123
 124   This macro needs to look up an offset in @<obj>'s vtable to do its work.
 125   Compare @|SOD_ILAYOUT| above, which is faster but requires precise
 126   knowledge of the instance's dynamic class.
 127 \end{describe}
 128
 129 \begin{describe}[SOD_CONVERT]{mac}
 130     {@<cls> *SOD_CONVERT(@<cls>, const void *@<obj>);}
 131
 132   Perform general conversions (up-, down-, and cross-casts) on instance
 133   pointers.
 134
 135   Given a class name @<cls> and a pointer @<obj> to an instance,
 136   @|SOD_CONVERT| returns an appropriately converted pointer to @<obj> if
 137   @<obj> is indeed an instance of (some subclass of) @<cls>; otherwise it
 138   returns a null pointer.
 139
 140   This macro is a simple wrapper around the @|sod_convert| function described
 141   below, which is useful in the common case that the target class is known
 142   statically.
 143 \end{describe}
 144
 145 \begin{describe}[SOD_DECL]{mac}{SOD_DECL(@<cls>, @<var>);}
 146   Declares and initializes an instance with automatic storage duration.
 147
 148   Given a class name @<cls> and an identifier @<var>, @|SOD_DECL| declares
 149   @<var> to be a pointer to an instance of @<cls>.  The instance is
 150   initialized in the sense that its vtable and class pointers have been set
 151   up, and slots for which initializers are defined are set to the appropriate
 152   initial values.
 153
 154   The instance has automatic storage duration: pointers to it will become
 155   invalid when control exits the scope of the declaration.
 156 \end{describe}
 157
 158 %%%--------------------------------------------------------------------------
 159 \section{Functions} \label{sec:runtime.functions}
 160
 161 The following functions are provided in @|libsod|.
 162
 163 \begin{describe}[sod_subclassp]{fun}
 164     {int sod_subclassp(const SodClass *sub, const SodClass *super);}
 165
 166   Decide whether one class @<sub> is actually a subclass of another class
 167   @<super>.
 168
 169   The @<sod_subclassp> function returns nonzero if and only if
 170   @<sub> is a subclass of @<super>.
 171
 172   This involves a run-time trawl through the class structures: while some
 173   effort has been made to make it perform well it's still not very fast.
 174 \end{describe}
 175
 176 \begin{describe}[sod_convert]{fun}
 177     {void *sod_convert(const SodClass *cls, const void *obj);}
 178   Performs general conversions (up-, down-, and cross-casts) on instance
 179   pointers.
 180
 181   Given a class pointer @<cls> and an instance pointer @<obj>, @|sod_convert|
 182   returns an appropriately converted pointer to @<obj> in the case that
 183   @<obj> is an instance of (some subclass of) @<cls>; otherwise it returns
 184   null.
 185
 186   This involves a run-time trawl through the class structures: while some
 187   effort has been made to make it perform well it's still not very fast.  For
 188   upcasts (where @<cls> is a superclass of the static type of @<obj>) the
 189   automatically defined conversion macros should be used instead, because
 190   they're much faster and can't fail.  When the target class is known
 191   statically, it's slightly more convenient to use the @|SOD_CONVERT| macro
 192   instead.
 193 \end{describe}
 194
 195 %%%----- That's all, folks --------------------------------------------------
 196
 197 %%% Local variables:
 198 %%% mode: LaTeX
 199 %%% TeX-master: "sod.tex"
 200 %%% TeX-PDF-mode: t
 201 %%% End: