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 | ||
62f9852b MW |
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} | |
09efeb89 | 97 | {const void *SOD_CLASSOF(const @<cls> *@<obj>);} |
62f9852b MW |
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} | |
09efeb89 | 119 | {@<cls> *SOD_CONVERT(@<cls>, const void *@<obj>);} |
62f9852b MW |
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 | ||
09efeb89 | 134 | \begin{describe}[SOD_DECL]{mac}{SOD_DECL(@<cls>, @<var>);} |
62f9852b MW |
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} | |
0ed1c8a9 | 153 | {int sod_subclassp(const SodClass *@<sub>, const SodClass *@<super>);} |
62f9852b MW |
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} | |
0ed1c8a9 | 166 | {void *sod_convert(const SodClass *@<cls>, const void *@<obj>);} |
62f9852b MW |
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: |