| 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: |