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 ,
118 .\"--------------------------------------------------------------------------
121 The functions and macros defined here generally expect that
122 instances and classes inherit from the standard
125 While the translator can (at some effort) support alternative roots,
126 they will require different run-time support machinery.
129 The following macros are useful in
130 finding one's way around an instance layout structure,
131 given various levels of information about
132 what kind of object one is dealing with,
133 or for computing the tables which are used for
134 this kind of navigation.
136 These macros are mostly intended for use in
137 code generated by the Sod translator.
138 Others may find them useful for special effects,
139 but they can be tricky to understand and use correctly
140 and can't really be recommended for general use.
144 macro returns the signed offset between
145 two members of a structure or union type.
146 Given a structure or union type
157 gives the difference, in bytes,
166 This macro is used internally when generating vtables
167 and is not expected to be very useful elsewhere.
171 macro recovers the instance layout base address
172 from a pointer to one of its instance chains.
173 Specifically, given a class name
177 of the least specific class in one of
182 to the instance storage for the chain containing
184 within an exact instance of
186 (i.e., not an instance of any proper subclass),
191 returns the a pointer to the layout structure containing
193 This macro is used internally in effective method bodies
194 and is not expected to be very useful elsewhere
195 since it's unusual to have such specific knowledge
196 about the dynamic type of an instance.
199 macro (described below) is more suited to general use.
203 macro finds the base address of an instance's layout.
205 .BI "const " cls " *" obj
207 .BI SOD_INSTBASE( obj )
208 returns the base address of the storage allocated to
210 This is useful if you want to free a dynamically allocated instance,
212 This macro needs to look up an offset in
214 vtable to do its work.
218 which is faster but requires
219 precise knowledge of the instance's dynamic class.
222 The following macros and functions
223 query the runtime relationhips between
224 instances and classes.
228 macro returns the class object describing an instance's dynamic class.
230 .BI "const " cls " *" obj
232 .BI SOD_CLASSOF( obj )
239 is typed correctly in the first place)
240 will be a subclass of
242 (If you wanted the class object for
246 .IB cls __class \fR.)
250 function answers whether one class
252 is actually a subclass of another class
257 returns nonzero if and only if
261 This involves a run-time trawl through the class structures:
262 while some effort has been made to make it perform well
263 it's still not very fast.
266 The following macros and functions are used
267 to convert instance pointers of some (static) type
268 into instance pointers of other static types
269 to the same instance.
273 macro performs a `cross-chain upcast'.
277 to an instance of a class of type
281 of the least specific class in one of
283 superclass chains which does not contain
289 returns the address of that chain's storage
290 within the instance layout as a raw
295 is not mentioned explicitly.)
296 This macro is used by the generated
299 which you are encouraged to use instead where possible.
307 perform general conversions
308 (up-, down-, and cross-casts) on instance pointers.
312 .BI "const void *" obj
314 they return an appropriately converted pointer to
318 is indeed an instance of (some subclass of)
320 otherwise they return a null pointer.
330 expects a pointer to a class object instead.
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.
337 is a superclass of the static type of
339 the automatically defined conversion macros should be used instead,
340 because they're much faster and can't fail.
342 When the target class is known statically,
343 it's slightly more convenient to use the
345 macro rather than the
348 since the class object name is longer and uglier,
349 and the macro returns a pointer of the correct type.
351 .SS Instance lifecycle
352 The following macros and functions
353 manage the standard steps along
354 an instance's lifecycle.
364 imprint and initialize an instance of a class
366 in the storage starting at address
369 The direct class for the new instance is specified as
372 or a pointer to a class object to the functions.
374 Keyword arguments for the initialization message may be provided.
377 macro expects a single preprocessor-time argument
378 which is a use of one of
386 function expects the keywords as
387 a variable-length argument tail;
390 expects the keywords to be passed indirectly,
391 through the captured argument-tail cursor
394 The return value is an instance pointer for the class
398 macro will have converted it to the correct type,
399 so it should probably be used where possible.
400 In fact, this is guaranteed to be equal to
402 by the layout rules described in
407 macro declares and initializes an instance
408 with automatic storage duration.
418 to be a pointer to an instance of
420 The instance is initialized in the sense that
421 its vtable and class pointers have been set up,
422 and slots for which initializers are defined
423 are set to the appropriate initial values.
424 The instance has automatic storage duration:
425 pointers to it will become invalid when control
426 exits the scope of the declaration.
428 .\"--------------------------------------------------------------------------
434 .\"--------------------------------------------------------------------------
436 Mark Wooding, <mdw@distorted.org.uk>
438 .\"----- That's all, folks --------------------------------------------------