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 | . |
6bed6ea3 MW |
27 | .\"-------------------------------------------------------------------------- |
28 | .so ../common/defs.man \" @@@PRE@@@ | |
47de28ae MW |
29 | . |
30 | .\"-------------------------------------------------------------------------- | |
31 | .TH sod 3 "8 September 2015" "Straylight/Edgeware" "Sensible Object Design" | |
32 | . | |
33 | .SH NAME | |
34 | sod \- Sensible Object Design runtime library | |
35 | . | |
36 | .\"-------------------------------------------------------------------------- | |
37 | .SH SYNOPSIS | |
38 | .B #include <sod/sod.h> | |
39 | .PP | |
40 | .B void *\c | |
41 | .B SOD_XCHAIN(\c | |
42 | .IB chead , | |
43 | .BI "const " cls " *" obj ); | |
44 | .br | |
45 | .B ptrdiff_t | |
46 | .B SOD_OFFSETDIFF(\c | |
47 | .IB type , | |
48 | .IB mema , | |
49 | .IB memb ); | |
50 | .br | |
51 | .IB cls "__ilayout *" \c | |
52 | .B SOD_ILAYOUT(\c | |
53 | .IB cls , | |
54 | .IB chead , | |
55 | .BI "const void *" obj ); | |
47de28ae MW |
56 | .br |
57 | .B void *\c | |
58 | .B SOD_INSTBASE(\c | |
59 | .BI "const " cls " *" obj ); | |
47de28ae | 60 | .PP |
4e3a7cb2 MW |
61 | .B const void *\c |
62 | .B SOD_CLASSOF(\c | |
63 | .BI "const " cls " *" obj ); | |
64 | .br | |
47de28ae MW |
65 | .B int |
66 | .B sod_subclassp(\c | |
67 | .BI "const SodClass *" sub , | |
68 | .BI "const SodClass *" super ); | |
4e3a7cb2 MW |
69 | .PP |
70 | .IB cls " *" \c | |
71 | .B SOD_CONVERT(\c | |
72 | .IB cls , | |
73 | .BI "const void *" obj ); | |
47de28ae MW |
74 | .br |
75 | .B int | |
76 | .B sod_convert(\c | |
77 | .BI "const SodClass *" cls , | |
78 | .BI "const void *" obj ); | |
4e3a7cb2 | 79 | .PP |
a142609c MW |
80 | .IB cls " *" \c |
81 | .B SOD_INIT(\c | |
82 | .IB cls , | |
83 | .BI "void *" p , | |
84 | .IB keywords ); | |
85 | .br | |
86 | .B void *\c | |
87 | .B sod_init(\c | |
88 | .BI "const SodClass *" cls , | |
89 | .BI "void *" p , | |
90 | .B ...); | |
91 | .br | |
92 | .B void *\c | |
93 | .B sod_initv(\c | |
94 | .BI "const SodClass *" cls , | |
95 | .BI "void *" p , | |
96 | .BI "va_list " ap ); | |
97 | .br | |
bacf2ba6 MW |
98 | .B void |
99 | .B sod_teardown(\c | |
100 | .BI "void *" p ); | |
101 | .br | |
4e3a7cb2 MW |
102 | .B SOD_DECL(\c |
103 | .IB cls , | |
104 | .IB var ); | |
bacf2ba6 MW |
105 | .br |
106 | .IB cls " *" \c | |
107 | .B SOD_MAKE(\c | |
108 | .IB cls , | |
109 | .IB keywords ); | |
110 | .br | |
111 | .B void *\c | |
112 | .B sod_make(\c | |
113 | .BI "const SodClass *" cls , | |
114 | .B ...); | |
115 | .br | |
116 | .B void *\c | |
117 | .B sod_makev(\c | |
118 | .BI "const SodClass *" cls , | |
119 | .BI "va_list " ap ); | |
120 | .br | |
121 | .B int | |
122 | .B sod_destroy(\c | |
123 | .BI "void *" p ); | |
4e3a7cb2 | 124 | .PP |
47de28ae MW |
125 | . |
126 | .\"-------------------------------------------------------------------------- | |
127 | .SH DESCRIPTION | |
128 | . | |
129 | The functions and macros defined here generally expect that | |
130 | instances and classes inherit from the standard | |
131 | .B SodObject | |
132 | root object. | |
133 | While the translator can (at some effort) support alternative roots, | |
134 | they will require different run-time support machinery. | |
558e70ee MW |
135 | .PP |
136 | Some of Sod's macros include runtime checking by default. | |
137 | This checking can be disabled if you value performance | |
138 | more than early diagnosis of problems. | |
139 | Define | |
140 | .B SOD_RECKLESS | |
141 | to a nonzero value | |
142 | before including | |
143 | .B <sod/sod.h> | |
144 | to inhibit the runtime checking. | |
47de28ae | 145 | . |
4e3a7cb2 MW |
146 | .SS Layout utilities |
147 | The following macros are useful in | |
148 | finding one's way around an instance layout structure, | |
149 | given various levels of information about | |
150 | what kind of object one is dealing with, | |
151 | or for computing the tables which are used for | |
152 | this kind of navigation. | |
153 | .PP | |
154 | These macros are mostly intended for use in | |
155 | code generated by the Sod translator. | |
47de28ae MW |
156 | Others may find them useful for special effects, |
157 | but they can be tricky to understand and use correctly | |
158 | and can't really be recommended for general use. | |
159 | .PP | |
160 | The | |
47de28ae MW |
161 | .B SOD_OFFSETDIFF |
162 | macro returns the signed offset between | |
163 | two members of a structure or union type. | |
164 | Given a structure or union type | |
165 | .IR type , | |
166 | and two member names | |
167 | .I mema | |
168 | and | |
169 | .IR memb , | |
170 | then | |
171 | .B SOD_OFFSETDIFF(\c | |
172 | .IB type , | |
173 | .IB mema , | |
174 | .IB memb ) | |
175 | gives the difference, in bytes, | |
176 | between the objects | |
177 | .IB x . mema | |
178 | and | |
179 | .IB x . memb | |
180 | for any object | |
181 | .I x | |
182 | of type | |
183 | .IR type . | |
184 | This macro is used internally when generating vtables | |
185 | and is not expected to be very useful elsewhere. | |
186 | .PP | |
187 | The | |
188 | .B SOD_ILAYOUT | |
189 | macro recovers the instance layout base address | |
190 | from a pointer to one of its instance chains. | |
191 | Specifically, given a class name | |
192 | .IR cls , | |
193 | the nickname | |
194 | .I chead | |
195 | of the least specific class in one of | |
196 | .IR cls 's | |
197 | superclass chains, | |
198 | and a pointer | |
199 | .I obj | |
200 | to the instance storage for the chain containing | |
201 | .I chead | |
202 | within an exact instance of | |
203 | .I cls | |
204 | (i.e., not an instance of any proper subclass), | |
205 | .B SOD_ILAYOUT(\c | |
206 | .IB cls , | |
207 | .IB chead , | |
208 | .IB obj ) | |
209 | returns the a pointer to the layout structure containing | |
210 | .IB obj . | |
211 | This macro is used internally in effective method bodies | |
212 | and is not expected to be very useful elsewhere | |
213 | since it's unusual to have such specific knowledge | |
214 | about the dynamic type of an instance. | |
215 | The | |
216 | .B SOD_INSTBASE | |
217 | macro (described below) is more suited to general use. | |
4e3a7cb2 MW |
218 | .PP |
219 | The | |
220 | .B SOD_INSTBASE | |
221 | macro finds the base address of an instance's layout. | |
222 | Given a pointer | |
223 | .BI "const " cls " *" obj | |
224 | to an instance, | |
225 | .BI SOD_INSTBASE( obj ) | |
226 | returns the base address of the storage allocated to | |
227 | .IR obj . | |
228 | This is useful if you want to free a dynamically allocated instance, | |
229 | for example. | |
230 | This macro needs to look up an offset in | |
231 | .IR obj 's | |
232 | vtable to do its work. | |
233 | Compare | |
234 | .B SOD_ILAYOUT | |
235 | above, | |
236 | which is faster but requires | |
237 | precise knowledge of the instance's dynamic class. | |
47de28ae | 238 | . |
4e3a7cb2 MW |
239 | .SS Classes |
240 | The following macros and functions | |
241 | query the runtime relationhips between | |
242 | instances and classes. | |
47de28ae MW |
243 | .PP |
244 | The | |
245 | .B SOD_CLASSOF | |
246 | macro returns the class object describing an instance's dynamic class. | |
247 | Given a pointer | |
248 | .BI "const " cls " *" obj | |
249 | to an instance, | |
250 | .BI SOD_CLASSOF( obj ) | |
251 | returns a pointer to | |
252 | .IR obj 's | |
253 | dynamic class, | |
254 | which | |
255 | (assuming | |
256 | .I obj | |
257 | is typed correctly in the first place) | |
258 | will be a subclass of | |
259 | .IR cls . | |
260 | (If you wanted the class object for | |
261 | .I cls | |
262 | itself, | |
263 | it's called | |
264 | .IB cls __class \fR.) | |
265 | .PP | |
266 | The | |
4e3a7cb2 MW |
267 | .B sod_subclassp |
268 | function answers whether one class | |
269 | .I sub | |
270 | is actually a subclass of another class | |
271 | .IR super . | |
272 | .B sod_subclassp(\c | |
273 | .IB sub , | |
274 | .IB super ) | |
275 | returns nonzero if and only if | |
276 | .I sub | |
277 | is a subclass of | |
278 | .IR super . | |
279 | This involves a run-time trawl through the class structures: | |
280 | while some effort has been made to make it perform well | |
281 | it's still not very fast. | |
282 | . | |
283 | .SS Conversions | |
284 | The following macros and functions are used | |
285 | to convert instance pointers of some (static) type | |
286 | into instance pointers of other static types | |
287 | to the same instance. | |
288 | .PP | |
289 | The | |
290 | .B SOD_XCHAIN | |
291 | macro performs a `cross-chain upcast'. | |
47de28ae | 292 | Given a pointer |
4e3a7cb2 MW |
293 | .I cls |
294 | .BI * obj | |
295 | to an instance of a class of type | |
296 | .I cls | |
297 | and the nickname | |
298 | .I chead | |
299 | of the least specific class in one of | |
300 | .IR cls 's | |
301 | superclass chains which does not contain | |
302 | .I cls | |
303 | itself, | |
304 | .B SOD_XCHAIN(\c | |
305 | .IB chead , | |
306 | .IB obj ) | |
307 | returns the address of that chain's storage | |
308 | within the instance layout as a raw | |
309 | .B void * | |
310 | pointer. | |
311 | (Note that | |
312 | .I cls | |
313 | is not mentioned explicitly.) | |
314 | This macro is used by the generated | |
315 | .IB cls __CONV_ c | |
316 | conversion macros, | |
317 | which you are encouraged to use instead where possible. | |
47de28ae MW |
318 | .PP |
319 | The | |
320 | .B SOD_CONVERT | |
4e3a7cb2 MW |
321 | macro |
322 | and | |
323 | .B sod_convert | |
324 | function | |
325 | perform general conversions | |
47de28ae | 326 | (up-, down-, and cross-casts) on instance pointers. |
4e3a7cb2 | 327 | Given a class |
47de28ae MW |
328 | .I cls |
329 | and a pointer | |
330 | .BI "const void *" obj | |
331 | to an instance, | |
4e3a7cb2 | 332 | they return an appropriately converted pointer to |
47de28ae MW |
333 | .I obj |
334 | if | |
335 | .I obj | |
336 | is indeed an instance of (some subclass of) | |
337 | .IR cls ; | |
4e3a7cb2 MW |
338 | otherwise they return a null pointer. |
339 | .PP | |
340 | The | |
341 | .B SOD_CONVERT | |
342 | macro expects | |
343 | .I cls | |
344 | to be a class name; | |
345 | the | |
346 | .B sod_convert | |
347 | function | |
348 | expects a pointer to a class object instead. | |
349 | .PP | |
350 | This involves a run-time trawl through the class structures: | |
351 | while some effort has been made to make it perform well | |
352 | it's still not very fast. | |
353 | For upcasts (where | |
354 | .I cls | |
355 | is a superclass of the static type of | |
356 | .IR obj ) | |
357 | the automatically defined conversion macros should be used instead, | |
358 | because they're much faster and can't fail. | |
359 | .PP | |
360 | When the target class is known statically, | |
361 | it's slightly more convenient to use the | |
362 | .B SOD_CONVERT | |
363 | macro rather than the | |
47de28ae | 364 | .B sod_convert |
4e3a7cb2 MW |
365 | function, |
366 | since the class object name is longer and uglier, | |
367 | and the macro returns a pointer of the correct type. | |
368 | . | |
369 | .SS Instance lifecycle | |
370 | The following macros and functions | |
371 | manage the standard steps along | |
372 | an instance's lifecycle. | |
47de28ae MW |
373 | .PP |
374 | The | |
a142609c MW |
375 | .B SOD_INIT |
376 | macro, | |
377 | and the | |
378 | .B sod_init | |
379 | and | |
380 | .B sod_initv | |
381 | functions, | |
382 | imprint and initialize an instance of a class | |
383 | .I cls | |
384 | in the storage starting at address | |
385 | .IR p . | |
386 | .PP | |
387 | The direct class for the new instance is specified as | |
388 | a class name to | |
389 | .BR SOD_INIT , | |
390 | or a pointer to a class object to the functions. | |
391 | .PP | |
392 | Keyword arguments for the initialization message may be provided. | |
393 | The | |
394 | .B SOD_INIT | |
395 | macro expects a single preprocessor-time argument | |
396 | which is a use of one of | |
397 | .B KWARGS | |
398 | or | |
399 | .B NO_KWARGS | |
400 | (see | |
401 | .BR keyword (3)); | |
402 | the | |
403 | .B sod_init | |
404 | function expects the keywords as | |
405 | a variable-length argument tail; | |
406 | and | |
407 | .B sod_initv | |
408 | expects the keywords to be passed indirectly, | |
409 | through the captured argument-tail cursor | |
410 | .IR ap . | |
411 | .PP | |
412 | The return value is an instance pointer for the class | |
413 | .IR cls ; | |
414 | the | |
415 | .B SOD_INIT | |
416 | macro will have converted it to the correct type, | |
417 | so it should probably be used where possible. | |
418 | In fact, this is guaranteed to be equal to | |
419 | .I p | |
420 | by the layout rules described in | |
421 | .BR sod-structs (3). | |
422 | .PP | |
423 | The | |
bacf2ba6 MW |
424 | .B sod_teardown |
425 | function tears down an instance of a class, | |
426 | releasing any resources it holds. | |
427 | .PP | |
428 | This function is a very thin wrapper around sending the | |
429 | .B obj.teardown | |
430 | message. | |
431 | It returns an integer flag. | |
432 | A zero value means that the instance is safe to deallocate. | |
433 | A nonzero value means that the instance should not be deallocated, | |
434 | and that it is safe for the caller to simply forget about it. | |
435 | (For example, the object may maintain a reference count, | |
436 | and knows that other references remain active.) | |
437 | .PP | |
438 | The | |
47de28ae MW |
439 | .B SOD_DECL |
440 | macro declares and initializes an instance | |
441 | with automatic storage duration. | |
442 | Given a class name | |
443 | .I cls | |
444 | and an identifier | |
445 | .IR var , | |
446 | .B SOD_DECL(\c | |
447 | .IB cls , | |
448 | .IB var ) | |
449 | declares | |
450 | .I var | |
451 | to be a pointer to an instance of | |
452 | .IR cls . | |
453 | The instance is initialized in the sense that | |
454 | its vtable and class pointers have been set up, | |
455 | and slots for which initializers are defined | |
456 | are set to the appropriate initial values. | |
457 | The instance has automatic storage duration: | |
458 | pointers to it will become invalid when control | |
459 | exits the scope of the declaration. | |
bacf2ba6 MW |
460 | .PP |
461 | Keyword arguments for the initialization message may be provided. | |
462 | The macro expects a single preprocessor-time argument | |
463 | which is a use of one of | |
464 | .B KWARGS | |
465 | or | |
466 | .B NO_KWARGS | |
467 | (see | |
468 | .BR keyword (3)). | |
469 | .PP | |
470 | The instance has automatic storage duration: | |
471 | pointers to it will become invalid | |
472 | when control exits the scope of the declaration. | |
473 | If necessary, | |
474 | the instance should be torn down before this happens, | |
475 | using the | |
476 | .B sod_teardown | |
477 | function. | |
5ffbe794 MW |
478 | It may be appropriate to |
479 | .BR assert (3) | |
480 | that the object is ready for deallocation at this time. | |
bacf2ba6 | 481 | .PP |
3b7437bc MW |
482 | By default, this macro will abort the program |
483 | if the size allocated for the instance doesn't match | |
484 | the size required by the class object; | |
485 | set | |
486 | .B SOD_RECKLESS | |
487 | to inhibit this check. | |
488 | .PP | |
bacf2ba6 MW |
489 | The |
490 | .B SOD_MAKE | |
491 | macro, | |
492 | and the | |
493 | .B sod_make | |
494 | and | |
495 | .B sod_makev | |
496 | functions, | |
497 | construct and return a pointer to a new instance of a class. | |
498 | .PP | |
499 | The direct class for the new instance is specified as a class name to | |
500 | .BR SOD_MAKE , | |
501 | or as a class object to the functions. | |
502 | .PP | |
503 | Keyword arguments for the initialization message may be provided. | |
504 | The | |
505 | .B SOD_MAKE | |
506 | macro expects a single preprocessor-time argument | |
507 | which is a use of one of | |
508 | .B KWARGS | |
509 | or | |
510 | .B NO_KWARGS | |
511 | (see | |
512 | .BR keyword (3)); | |
513 | the | |
514 | .B sod_init | |
515 | function expects the keywords as | |
516 | a variable-length argument tail; | |
517 | and | |
518 | .B sod_makev | |
519 | expects the keywords to be passed indirectly, | |
520 | through the captured argument-tail cursor | |
521 | .IR ap . | |
522 | .PP | |
523 | Storage for the new instance will have been allocated | |
524 | using the standard | |
525 | .BR malloc (3) | |
526 | function. | |
527 | The easiest way to destroy the instance, | |
528 | when it is no longer needed, | |
529 | is probably to call the | |
530 | .B sod_destroy | |
531 | function. | |
532 | .PP | |
533 | The return value is an instance pointer for the class | |
534 | .IR cls ; | |
535 | the | |
536 | .B SOD_MAKE | |
537 | macro will have converted it to the correct type, | |
538 | so it should probably be used where possible. | |
539 | .PP | |
540 | The | |
541 | .B sod_destroy | |
542 | function tears down and frees an instance allocated using | |
543 | .BR malloc (3). | |
544 | .PP | |
545 | The pointer | |
546 | .I p | |
547 | should be an instance pointer, | |
548 | i.e., a pointer to any of an instance's chains. | |
549 | The instance is torn down, | |
550 | by sending it the | |
551 | .B obj.teardown | |
552 | message. | |
553 | If the instance reports itself ready for deallocation, | |
554 | then its storage is released using | |
555 | .BR free (3). | |
556 | The return value is the value returned by the | |
557 | .B obj.teardown | |
558 | message. | |
47de28ae | 559 | . |
47de28ae MW |
560 | .\"-------------------------------------------------------------------------- |
561 | .SH SEE ALSO | |
a142609c | 562 | .BR keyword (3), |
9ed8eb2a | 563 | .BR sod (1), |
47de28ae MW |
564 | .BR sod-structs (3). |
565 | . | |
566 | .\"-------------------------------------------------------------------------- | |
567 | .SH AUTHOR | |
568 | Mark Wooding, <mdw@distorted.org.uk> | |
569 | . | |
570 | .\"----- That's all, folks -------------------------------------------------- |