Commit | Line | Data |
---|---|---|
47de28ae MW |
1 | .\" -*-nroff-*- |
2 | .\" | |
3 | .\" The Sod runtime library | |
4 | .\" | |
5 | .\" (c) 2015 Straylight/Edgeware | |
6 | .\" | |
7 | . | |
8 | .\"----- Licensing notice --------------------------------------------------- | |
9 | .\" | |
e0808c47 | 10 | .\" This file is part of the Sensible Object Design, an object system for C. |
47de28ae MW |
11 | .\" |
12 | .\" SOD is free software; you can redistribute it and/or modify | |
65aaa02c MW |
13 | .\" it under the terms of the GNU Library General Public License as |
14 | .\" published by the Free Software Foundation; either version 2 of the | |
15 | .\" License, or (at your option) any later version. | |
47de28ae MW |
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 | |
65aaa02c | 20 | .\" GNU Library General Public License for more details. |
47de28ae | 21 | .\" |
65aaa02c MW |
22 | .\" You should have received a copy of the GNU Library General Public |
23 | .\" License along with SOD; if not, write to the Free | |
24 | .\" Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, | |
25 | .\" MA 02111-1307, USA. | |
47de28ae | 26 | . |
9ed8eb2a | 27 | .\" Highlight using terminal escapes, rather than overstriking. |
47de28ae | 28 | .\"\X'tty: sgr 1' |
9ed8eb2a | 29 | . |
47de28ae MW |
30 | .\" String definitions and font selection. |
31 | .ie t \{\ | |
32 | . ds o \(bu | |
33 | . if \n(.g .fam P | |
34 | .\} | |
35 | .el \{\ | |
36 | . ds o o | |
37 | .\} | |
38 | . | |
39 | .\" .hP TEXT -- start an indented paragraph with TEXT hanging off to the left | |
40 | .de hP | |
41 | .IP | |
42 | \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c | |
43 | .. | |
44 | . | |
45 | .\"-------------------------------------------------------------------------- | |
46 | .TH sod 3 "8 September 2015" "Straylight/Edgeware" "Sensible Object Design" | |
47 | . | |
48 | .SH NAME | |
49 | sod \- Sensible Object Design runtime library | |
50 | . | |
51 | .\"-------------------------------------------------------------------------- | |
52 | .SH SYNOPSIS | |
53 | .B #include <sod/sod.h> | |
54 | .PP | |
55 | .B void *\c | |
56 | .B SOD_XCHAIN(\c | |
57 | .IB chead , | |
58 | .BI "const " cls " *" obj ); | |
59 | .br | |
60 | .B ptrdiff_t | |
61 | .B SOD_OFFSETDIFF(\c | |
62 | .IB type , | |
63 | .IB mema , | |
64 | .IB memb ); | |
65 | .br | |
66 | .IB cls "__ilayout *" \c | |
67 | .B SOD_ILAYOUT(\c | |
68 | .IB cls , | |
69 | .IB chead , | |
70 | .BI "const void *" obj ); | |
71 | .br | |
72 | .B SOD_CAR(\c | |
73 | .IB arg , | |
74 | .RB ... ); | |
75 | .PP | |
76 | .B const void *\c | |
77 | .B SOD_CLASSOF(\c | |
78 | .BI "const " cls " *" obj ); | |
79 | .br | |
80 | .B void *\c | |
81 | .B SOD_INSTBASE(\c | |
82 | .BI "const " cls " *" obj ); | |
83 | .br | |
84 | .IB cls " *" \c | |
85 | .B SOD_CONVERT(\c | |
86 | .IB cls , | |
87 | .BI "const void *" obj ); | |
88 | .br | |
89 | .B SOD_DECL(\c | |
90 | .IB cls , | |
91 | .IB var ); | |
92 | .PP | |
93 | .B int | |
94 | .B sod_subclassp(\c | |
95 | .BI "const SodClass *" sub , | |
96 | .BI "const SodClass *" super ); | |
97 | .br | |
98 | .B int | |
99 | .B sod_convert(\c | |
100 | .BI "const SodClass *" cls , | |
101 | .BI "const void *" obj ); | |
102 | . | |
103 | .\"-------------------------------------------------------------------------- | |
104 | .SH DESCRIPTION | |
105 | . | |
106 | The functions and macros defined here generally expect that | |
107 | instances and classes inherit from the standard | |
108 | .B SodObject | |
109 | root object. | |
110 | While the translator can (at some effort) support alternative roots, | |
111 | they will require different run-time support machinery. | |
112 | . | |
113 | .SS Infrastructure macros | |
114 | These macros are mostly intended for use in code | |
115 | generated by the Sod translator. | |
116 | Others may find them useful for special effects, | |
117 | but they can be tricky to understand and use correctly | |
118 | and can't really be recommended for general use. | |
119 | .PP | |
120 | The | |
121 | .B SOD_XCHAIN | |
122 | macro performs a `cross-chain upcast'. | |
123 | Given a pointer | |
124 | .I cls | |
125 | .BI * obj | |
126 | to an instance of a class of type | |
127 | .I cls | |
128 | and the nickname | |
129 | .I chead | |
130 | of the least specific class in one of | |
131 | .IR cls 's | |
132 | superclass chains which does not contain | |
133 | .I cls | |
134 | itself, | |
135 | .B SOD_XCHAIN(\c | |
136 | .IB chead , | |
137 | .IB obj ) | |
138 | returns the address of that chain's storage | |
139 | within the instance layout as a raw | |
140 | .B void * | |
141 | pointer. | |
142 | (Note that | |
143 | .I cls | |
144 | is not mentioned explicitly.) | |
145 | This macro is used by the generated | |
146 | .IB CLASS __CONV_ CLS | |
147 | conversion macros, | |
148 | which you are encouraged to use instead where possible. | |
149 | .PP | |
150 | The | |
151 | .B SOD_OFFSETDIFF | |
152 | macro returns the signed offset between | |
153 | two members of a structure or union type. | |
154 | Given a structure or union type | |
155 | .IR type , | |
156 | and two member names | |
157 | .I mema | |
158 | and | |
159 | .IR memb , | |
160 | then | |
161 | .B SOD_OFFSETDIFF(\c | |
162 | .IB type , | |
163 | .IB mema , | |
164 | .IB memb ) | |
165 | gives the difference, in bytes, | |
166 | between the objects | |
167 | .IB x . mema | |
168 | and | |
169 | .IB x . memb | |
170 | for any object | |
171 | .I x | |
172 | of type | |
173 | .IR type . | |
174 | This macro is used internally when generating vtables | |
175 | and is not expected to be very useful elsewhere. | |
176 | .PP | |
177 | The | |
178 | .B SOD_ILAYOUT | |
179 | macro recovers the instance layout base address | |
180 | from a pointer to one of its instance chains. | |
181 | Specifically, given a class name | |
182 | .IR cls , | |
183 | the nickname | |
184 | .I chead | |
185 | of the least specific class in one of | |
186 | .IR cls 's | |
187 | superclass chains, | |
188 | and a pointer | |
189 | .I obj | |
190 | to the instance storage for the chain containing | |
191 | .I chead | |
192 | within an exact instance of | |
193 | .I cls | |
194 | (i.e., not an instance of any proper subclass), | |
195 | .B SOD_ILAYOUT(\c | |
196 | .IB cls , | |
197 | .IB chead , | |
198 | .IB obj ) | |
199 | returns the a pointer to the layout structure containing | |
200 | .IB obj . | |
201 | This macro is used internally in effective method bodies | |
202 | and is not expected to be very useful elsewhere | |
203 | since it's unusual to have such specific knowledge | |
204 | about the dynamic type of an instance. | |
205 | The | |
206 | .B SOD_INSTBASE | |
207 | macro (described below) is more suited to general use. | |
208 | .PP | |
209 | The | |
210 | .B SOD_CAR | |
211 | macro accepts one or more arguments | |
212 | and expands to just its first argument, | |
213 | discarding the others. | |
214 | It is only defined if the C implementation | |
215 | advertises support for C99. | |
216 | It is used in the definitions of message convenience macros | |
217 | for messages which accept a variable number of arguments | |
218 | but no required arguments, | |
219 | and is exported because the author has found such a thing useful in | |
220 | other contexts. | |
221 | . | |
222 | .SS Utility macros | |
223 | The following macros are expected to be useful | |
224 | in Sod method definitions and client code. | |
225 | .PP | |
226 | The | |
227 | .B SOD_CLASSOF | |
228 | macro returns the class object describing an instance's dynamic class. | |
229 | Given a pointer | |
230 | .BI "const " cls " *" obj | |
231 | to an instance, | |
232 | .BI SOD_CLASSOF( obj ) | |
233 | returns a pointer to | |
234 | .IR obj 's | |
235 | dynamic class, | |
236 | which | |
237 | (assuming | |
238 | .I obj | |
239 | is typed correctly in the first place) | |
240 | will be a subclass of | |
241 | .IR cls . | |
242 | (If you wanted the class object for | |
243 | .I cls | |
244 | itself, | |
245 | it's called | |
246 | .IB cls __class \fR.) | |
247 | .PP | |
248 | The | |
249 | .B SOD_INSTBASE | |
250 | macro finds the base address of an instance's layout. | |
251 | Given a pointer | |
252 | .BI "const " cls " *" obj | |
253 | to an instance, | |
254 | .BI SOD_INSTBASE( obj ) | |
255 | returns the base address of the storage allocated to | |
256 | .IR obj . | |
257 | This is useful if you want to free a dynamically allocated instance, | |
258 | for example. | |
259 | This macro needs to look up an offset in | |
260 | .IR obj 's | |
261 | vtable to do its work. | |
262 | Compare | |
263 | .B SOD_ILAYOUT | |
264 | above, | |
265 | which is faster but requires | |
266 | precise knowledge of the instance's dynamic class. | |
267 | .PP | |
268 | The | |
269 | .B SOD_CONVERT | |
270 | macro performs general conversions | |
271 | (up-, down-, and cross-casts) on instance pointers. | |
272 | Given a class name | |
273 | .I cls | |
274 | and a pointer | |
275 | .BI "const void *" obj | |
276 | to an instance, | |
277 | .B SOD_CONVERT(\c | |
278 | .IB cls , | |
279 | .IB obj ) | |
280 | returns an appropriately converted pointer to | |
281 | .I obj | |
282 | if | |
283 | .I obj | |
284 | is indeed an instance of (some subclass of) | |
285 | .IR cls ; | |
286 | otherwise it returns a null pointer. | |
287 | This macro is a simple wrapper around the | |
288 | .B sod_convert | |
289 | function described below, | |
290 | which is useful in the common case that | |
291 | the target class is known statically. | |
292 | .PP | |
293 | The | |
294 | .B SOD_DECL | |
295 | macro declares and initializes an instance | |
296 | with automatic storage duration. | |
297 | Given a class name | |
298 | .I cls | |
299 | and an identifier | |
300 | .IR var , | |
301 | .B SOD_DECL(\c | |
302 | .IB cls , | |
303 | .IB var ) | |
304 | declares | |
305 | .I var | |
306 | to be a pointer to an instance of | |
307 | .IR cls . | |
308 | The instance is initialized in the sense that | |
309 | its vtable and class pointers have been set up, | |
310 | and slots for which initializers are defined | |
311 | are set to the appropriate initial values. | |
312 | The instance has automatic storage duration: | |
313 | pointers to it will become invalid when control | |
314 | exits the scope of the declaration. | |
315 | . | |
316 | .SS Functions | |
317 | The following functions are provided. | |
318 | .PP | |
319 | The | |
320 | .B sod_subclassp | |
321 | function answers whether one class | |
322 | .I sub | |
323 | is actually a subclass of another class | |
324 | .IR super . | |
325 | .B sod_subclassp(\c | |
326 | .IB sub , | |
327 | .IB super ) | |
328 | returns nonzero if and only if | |
329 | .I sub | |
330 | is a subclass of | |
331 | .IR super . | |
332 | This involves a run-time trawl through the class structures: | |
333 | while some effort has been made to make it perform well | |
334 | it's still not very fast. | |
335 | .PP | |
336 | The | |
337 | .B sod_convert | |
338 | function performs general conversions | |
339 | (up-, down-, and cross-casts) on instance pointers. | |
340 | Given a class pointer | |
341 | .I cls | |
342 | and an instance pointer | |
343 | .IR obj , | |
344 | .B sod_convert(\c | |
345 | .IB cls , | |
346 | .IB obj ) | |
347 | returns an appropriately converted pointer to | |
348 | .I obj | |
349 | in the case that | |
350 | .I obj | |
351 | is an instance of (some subclass of) | |
352 | .IR cls ; | |
353 | otherwise it returns null. | |
354 | This involves a run-time trawl through the class structures: | |
355 | while some effort has been made to make it perform well | |
356 | it's still not very fast. | |
357 | For upcasts (where | |
358 | .I cls | |
359 | is a superclass of the static type of | |
360 | .IR obj ) | |
361 | the automatically defined conversion macros should be used instead, | |
362 | because they're much faster and can't fail. | |
363 | When the target class is known statically, | |
364 | it's slightly more convenient to use the | |
365 | .B SOD_CONVERT | |
366 | macro instead. | |
367 | . | |
368 | .\"-------------------------------------------------------------------------- | |
369 | .SH SEE ALSO | |
9ed8eb2a | 370 | .BR sod (1), |
47de28ae MW |
371 | .BR sod-structs (3). |
372 | . | |
373 | .\"-------------------------------------------------------------------------- | |
374 | .SH AUTHOR | |
375 | Mark Wooding, <mdw@distorted.org.uk> | |
376 | . | |
377 | .\"----- That's all, folks -------------------------------------------------- |