Commit | Line | Data |
---|---|---|
62f9852b MW |
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} | |
09efeb89 | 60 | {ptrdiff_t SOD_OFFSETDIFF(@<type>, @<member>_1, @<member>_2);} |
62f9852b MW |
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} | |
09efeb89 | 73 | {@<cls>{}__ilayout *SOD_ILAYOUT(@<cls>, @<chead>, const void *@<obj>);} |
62f9852b MW |
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 | ||
09efeb89 | 90 | \begin{describe}[SOD_CAR]{mac} {@<arg> SOD_CAR(@<arg>, @<other-arg>^*);} |
62f9852b MW |
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} | |
09efeb89 | 108 | {const void *SOD_CLASSOF(const @<cls> *@<obj>);} |
62f9852b MW |
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} | |
09efeb89 | 130 | {@<cls> *SOD_CONVERT(@<cls>, const void *@<obj>);} |
62f9852b MW |
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 | ||
09efeb89 | 145 | \begin{describe}[SOD_DECL]{mac}{SOD_DECL(@<cls>, @<var>);} |
62f9852b MW |
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} | |
09efeb89 | 164 | {int sod_subclassp(const SodClass *sub, const SodClass *super);} |
62f9852b MW |
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} | |
09efeb89 | 177 | {void *sod_convert(const SodClass *cls, const void *obj);} |
62f9852b MW |
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: |