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 .\"--------------------------------------------------------------------------
28 .so ../common/defs.man \" @@@PRE@@@
30 .\"--------------------------------------------------------------------------
31 .TH sod 3 "8 September 2015" "Straylight/Edgeware" "Sensible Object Design"
34 sod \- Sensible Object Design runtime library
36 .\"--------------------------------------------------------------------------
38 .B #include <sod/sod.h>
43 .BI "const " cls " *" obj );
51 .IB cls "__ilayout *" \c
55 .BI "const void *" obj );
59 .BI "const " cls " *" obj );
63 .BI "const " cls " *" obj );
67 .BI "const SodClass *" sub ,
68 .BI "const SodClass *" super );
73 .BI "const void *" obj );
77 .BI "const SodClass *" cls ,
78 .BI "const void *" obj );
88 .BI "const SodClass *" cls ,
94 .BI "const SodClass *" cls ,
113 .BI "const SodClass *" cls ,
118 .BI "const SodClass *" cls ,
126 .\"--------------------------------------------------------------------------
129 The functions and macros defined here generally expect that
130 instances and classes inherit from the standard
133 While the translator can (at some effort) support alternative roots,
134 they will require different run-time support machinery.
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.
144 to inhibit the runtime checking.
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.
154 These macros are mostly intended for use in
155 code generated by the Sod translator.
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.
162 macro returns the signed offset between
163 two members of a structure or union type.
164 Given a structure or union type
175 gives the difference, in bytes,
184 This macro is used internally when generating vtables
185 and is not expected to be very useful elsewhere.
189 macro recovers the instance layout base address
190 from a pointer to one of its instance chains.
191 Specifically, given a class name
195 of the least specific class in one of
200 to the instance storage for the chain containing
202 within an exact instance of
204 (i.e., not an instance of any proper subclass),
209 returns the a pointer to the layout structure containing
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.
217 macro (described below) is more suited to general use.
221 macro finds the base address of an instance's layout.
223 .BI "const " cls " *" obj
225 .BI SOD_INSTBASE( obj )
226 returns the base address of the storage allocated to
228 This is useful if you want to free a dynamically allocated instance,
230 This macro needs to look up an offset in
232 vtable to do its work.
236 which is faster but requires
237 precise knowledge of the instance's dynamic class.
240 The following macros and functions
241 query the runtime relationhips between
242 instances and classes.
246 macro returns the class object describing an instance's dynamic class.
248 .BI "const " cls " *" obj
250 .BI SOD_CLASSOF( obj )
257 is typed correctly in the first place)
258 will be a subclass of
260 (If you wanted the class object for
264 .IB cls __class \fR.)
268 function answers whether one class
270 is actually a subclass of another class
275 returns nonzero if and only if
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.
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.
291 macro performs a `cross-chain upcast'.
295 to an instance of a class of type
299 of the least specific class in one of
301 superclass chains which does not contain
307 returns the address of that chain's storage
308 within the instance layout as a raw
313 is not mentioned explicitly.)
314 This macro is used by the generated
317 which you are encouraged to use instead where possible.
325 perform general conversions
326 (up-, down-, and cross-casts) on instance pointers.
330 .BI "const void *" obj
332 they return an appropriately converted pointer to
336 is indeed an instance of (some subclass of)
338 otherwise they return a null pointer.
348 expects a pointer to a class object instead.
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.
355 is a superclass of the static type of
357 the automatically defined conversion macros should be used instead,
358 because they're much faster and can't fail.
360 When the target class is known statically,
361 it's slightly more convenient to use the
363 macro rather than the
366 since the class object name is longer and uglier,
367 and the macro returns a pointer of the correct type.
369 .SS Instance lifecycle
370 The following macros and functions
371 manage the standard steps along
372 an instance's lifecycle.
382 imprint and initialize an instance of a class
384 in the storage starting at address
387 The direct class for the new instance is specified as
390 or a pointer to a class object to the functions.
392 Keyword arguments for the initialization message may be provided.
395 macro expects a single preprocessor-time argument
396 which is a use of one of
404 function expects the keywords as
405 a variable-length argument tail;
408 expects the keywords to be passed indirectly,
409 through the captured argument-tail cursor
412 The return value is an instance pointer for the class
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
420 by the layout rules described in
425 function tears down an instance of a class,
426 releasing any resources it holds.
428 This function is a very thin wrapper around sending the
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.)
440 macro declares and initializes an instance
441 with automatic storage duration.
451 to be a pointer to an instance of
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.
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
470 The instance has automatic storage duration:
471 pointers to it will become invalid
472 when control exits the scope of the declaration.
474 the instance should be torn down before this happens,
478 It may be appropriate to
480 that the object is ready for deallocation at this time.
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;
487 to inhibit this check.
497 construct and return a pointer to a new instance of a class.
499 The direct class for the new instance is specified as a class name to
501 or as a class object to the functions.
503 Keyword arguments for the initialization message may be provided.
506 macro expects a single preprocessor-time argument
507 which is a use of one of
515 function expects the keywords as
516 a variable-length argument tail;
519 expects the keywords to be passed indirectly,
520 through the captured argument-tail cursor
523 Storage for the new instance will have been allocated
527 The easiest way to destroy the instance,
528 when it is no longer needed,
529 is probably to call the
533 The return value is an instance pointer for the class
537 macro will have converted it to the correct type,
538 so it should probably be used where possible.
542 function tears down and frees an instance allocated using
547 should be an instance pointer,
548 i.e., a pointer to any of an instance's chains.
549 The instance is torn down,
553 If the instance reports itself ready for deallocation,
554 then its storage is released using
556 The return value is the value returned by the
560 .\"--------------------------------------------------------------------------
566 .\"--------------------------------------------------------------------------
568 Mark Wooding, <mdw@distorted.org.uk>
570 .\"----- That's all, folks --------------------------------------------------