3 .\" The Sod runtime library
5 .\" (c) 2015 Straylight/Edgeware
8 .\"----- Licensing notice ---------------------------------------------------
10 .\" This file is part of the Sensible Object Design, an object system for C.
12 .\" SOD is free software; you can redistribute it and/or modify
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.
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 Library General Public License for more details.
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.
27 .\" Highlight using terminal escapes, rather than overstriking.
30 .\" String definitions and font selection.
39 .\" .hP TEXT -- start an indented paragraph with TEXT hanging off to the left
42 \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
45 .\"--------------------------------------------------------------------------
46 .TH sod 3 "8 September 2015" "Straylight/Edgeware" "Sensible Object Design"
49 sod \- Sensible Object Design runtime library
51 .\"--------------------------------------------------------------------------
53 .B #include <sod/sod.h>
58 .BI "const " cls " *" obj );
66 .IB cls "__ilayout *" \c
70 .BI "const void *" obj );
74 .BI "const " cls " *" obj );
78 .BI "const " cls " *" obj );
82 .BI "const SodClass *" sub ,
83 .BI "const SodClass *" super );
88 .BI "const void *" obj );
92 .BI "const SodClass *" cls ,
93 .BI "const void *" obj );
103 .BI "const SodClass *" cls ,
109 .BI "const SodClass *" cls ,
128 .BI "const SodClass *" cls ,
133 .BI "const SodClass *" cls ,
141 .\"--------------------------------------------------------------------------
144 The functions and macros defined here generally expect that
145 instances and classes inherit from the standard
148 While the translator can (at some effort) support alternative roots,
149 they will require different run-time support machinery.
151 Some of Sod's macros include runtime checking by default.
152 This checking can be disabled if you value performance
153 more than early diagnosis of problems.
159 to inhibit the runtime checking.
162 The following macros are useful in
163 finding one's way around an instance layout structure,
164 given various levels of information about
165 what kind of object one is dealing with,
166 or for computing the tables which are used for
167 this kind of navigation.
169 These macros are mostly intended for use in
170 code generated by the Sod translator.
171 Others may find them useful for special effects,
172 but they can be tricky to understand and use correctly
173 and can't really be recommended for general use.
177 macro returns the signed offset between
178 two members of a structure or union type.
179 Given a structure or union type
190 gives the difference, in bytes,
199 This macro is used internally when generating vtables
200 and is not expected to be very useful elsewhere.
204 macro recovers the instance layout base address
205 from a pointer to one of its instance chains.
206 Specifically, given a class name
210 of the least specific class in one of
215 to the instance storage for the chain containing
217 within an exact instance of
219 (i.e., not an instance of any proper subclass),
224 returns the a pointer to the layout structure containing
226 This macro is used internally in effective method bodies
227 and is not expected to be very useful elsewhere
228 since it's unusual to have such specific knowledge
229 about the dynamic type of an instance.
232 macro (described below) is more suited to general use.
236 macro finds the base address of an instance's layout.
238 .BI "const " cls " *" obj
240 .BI SOD_INSTBASE( obj )
241 returns the base address of the storage allocated to
243 This is useful if you want to free a dynamically allocated instance,
245 This macro needs to look up an offset in
247 vtable to do its work.
251 which is faster but requires
252 precise knowledge of the instance's dynamic class.
255 The following macros and functions
256 query the runtime relationhips between
257 instances and classes.
261 macro returns the class object describing an instance's dynamic class.
263 .BI "const " cls " *" obj
265 .BI SOD_CLASSOF( obj )
272 is typed correctly in the first place)
273 will be a subclass of
275 (If you wanted the class object for
279 .IB cls __class \fR.)
283 function answers whether one class
285 is actually a subclass of another class
290 returns nonzero if and only if
294 This involves a run-time trawl through the class structures:
295 while some effort has been made to make it perform well
296 it's still not very fast.
299 The following macros and functions are used
300 to convert instance pointers of some (static) type
301 into instance pointers of other static types
302 to the same instance.
306 macro performs a `cross-chain upcast'.
310 to an instance of a class of type
314 of the least specific class in one of
316 superclass chains which does not contain
322 returns the address of that chain's storage
323 within the instance layout as a raw
328 is not mentioned explicitly.)
329 This macro is used by the generated
332 which you are encouraged to use instead where possible.
340 perform general conversions
341 (up-, down-, and cross-casts) on instance pointers.
345 .BI "const void *" obj
347 they return an appropriately converted pointer to
351 is indeed an instance of (some subclass of)
353 otherwise they return a null pointer.
363 expects a pointer to a class object instead.
365 This involves a run-time trawl through the class structures:
366 while some effort has been made to make it perform well
367 it's still not very fast.
370 is a superclass of the static type of
372 the automatically defined conversion macros should be used instead,
373 because they're much faster and can't fail.
375 When the target class is known statically,
376 it's slightly more convenient to use the
378 macro rather than the
381 since the class object name is longer and uglier,
382 and the macro returns a pointer of the correct type.
384 .SS Instance lifecycle
385 The following macros and functions
386 manage the standard steps along
387 an instance's lifecycle.
397 imprint and initialize an instance of a class
399 in the storage starting at address
402 The direct class for the new instance is specified as
405 or a pointer to a class object to the functions.
407 Keyword arguments for the initialization message may be provided.
410 macro expects a single preprocessor-time argument
411 which is a use of one of
419 function expects the keywords as
420 a variable-length argument tail;
423 expects the keywords to be passed indirectly,
424 through the captured argument-tail cursor
427 The return value is an instance pointer for the class
431 macro will have converted it to the correct type,
432 so it should probably be used where possible.
433 In fact, this is guaranteed to be equal to
435 by the layout rules described in
440 function tears down an instance of a class,
441 releasing any resources it holds.
443 This function is a very thin wrapper around sending the
446 It returns an integer flag.
447 A zero value means that the instance is safe to deallocate.
448 A nonzero value means that the instance should not be deallocated,
449 and that it is safe for the caller to simply forget about it.
450 (For example, the object may maintain a reference count,
451 and knows that other references remain active.)
455 macro declares and initializes an instance
456 with automatic storage duration.
466 to be a pointer to an instance of
468 The instance is initialized in the sense that
469 its vtable and class pointers have been set up,
470 and slots for which initializers are defined
471 are set to the appropriate initial values.
472 The instance has automatic storage duration:
473 pointers to it will become invalid when control
474 exits the scope of the declaration.
476 Keyword arguments for the initialization message may be provided.
477 The macro expects a single preprocessor-time argument
478 which is a use of one of
485 The instance has automatic storage duration:
486 pointers to it will become invalid
487 when control exits the scope of the declaration.
489 the instance should be torn down before this happens,
493 It may be appropriate to
495 that the object is ready for deallocation at this time.
497 By default, this macro will abort the program
498 if the size allocated for the instance doesn't match
499 the size required by the class object;
502 to inhibit this check.
512 construct and return a pointer to a new instance of a class.
514 The direct class for the new instance is specified as a class name to
516 or as a class object to the functions.
518 Keyword arguments for the initialization message may be provided.
521 macro expects a single preprocessor-time argument
522 which is a use of one of
530 function expects the keywords as
531 a variable-length argument tail;
534 expects the keywords to be passed indirectly,
535 through the captured argument-tail cursor
538 Storage for the new instance will have been allocated
542 The easiest way to destroy the instance,
543 when it is no longer needed,
544 is probably to call the
548 The return value is an instance pointer for the class
552 macro will have converted it to the correct type,
553 so it should probably be used where possible.
557 function tears down and frees an instance allocated using
562 should be an instance pointer,
563 i.e., a pointer to any of an instance's chains.
564 The instance is torn down,
568 If the instance reports itself ready for deallocation,
569 then its storage is released using
571 The return value is the value returned by the
575 .\"--------------------------------------------------------------------------
581 .\"--------------------------------------------------------------------------
583 Mark Wooding, <mdw@distorted.org.uk>
585 .\"----- That's all, folks --------------------------------------------------