3 .\" The Sod runtime library
5 .\" (c) 2015 Straylight/Edgeware
8 .\"----- Licensing notice ---------------------------------------------------
10 .\" This file is part of the Sensble 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 General Public License as published by
14 .\" the Free Software Foundation; either version 2 of the License, or
15 .\" (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 General Public License for more details.
22 .\" You should have received a copy of the GNU General Public License
23 .\" along with SOD; if not, write to the Free Software Foundation,
24 .\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
27 .\" String definitions and font selection.
36 .\" .hP TEXT -- start an indented paragraph with TEXT hanging off to the left
39 \h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
42 .\"--------------------------------------------------------------------------
43 .TH sod 3 "8 September 2015" "Straylight/Edgeware" "Sensible Object Design"
46 sod \- Sensible Object Design runtime library
48 .\"--------------------------------------------------------------------------
50 .B #include <sod/sod.h>
55 .BI "const " cls " *" obj );
63 .IB cls "__ilayout *" \c
67 .BI "const void *" obj );
75 .BI "const " cls " *" obj );
79 .BI "const " cls " *" obj );
84 .BI "const void *" obj );
92 .BI "const SodClass *" sub ,
93 .BI "const SodClass *" super );
97 .BI "const SodClass *" cls ,
98 .BI "const void *" obj );
100 .\"--------------------------------------------------------------------------
103 The functions and macros defined here generally expect that
104 instances and classes inherit from the standard
107 While the translator can (at some effort) support alternative roots,
108 they will require different run-time support machinery.
110 .SS Infrastructure macros
111 These macros are mostly intended for use in code
112 generated by the Sod translator.
113 Others may find them useful for special effects,
114 but they can be tricky to understand and use correctly
115 and can't really be recommended for general use.
119 macro performs a `cross-chain upcast'.
123 to an instance of a class of type
127 of the least specific class in one of
129 superclass chains which does not contain
135 returns the address of that chain's storage
136 within the instance layout as a raw
141 is not mentioned explicitly.)
142 This macro is used by the generated
143 .IB CLASS __CONV_ CLS
145 which you are encouraged to use instead where possible.
149 macro returns the signed offset between
150 two members of a structure or union type.
151 Given a structure or union type
162 gives the difference, in bytes,
171 This macro is used internally when generating vtables
172 and is not expected to be very useful elsewhere.
176 macro recovers the instance layout base address
177 from a pointer to one of its instance chains.
178 Specifically, given a class name
182 of the least specific class in one of
187 to the instance storage for the chain containing
189 within an exact instance of
191 (i.e., not an instance of any proper subclass),
196 returns the a pointer to the layout structure containing
198 This macro is used internally in effective method bodies
199 and is not expected to be very useful elsewhere
200 since it's unusual to have such specific knowledge
201 about the dynamic type of an instance.
204 macro (described below) is more suited to general use.
208 macro accepts one or more arguments
209 and expands to just its first argument,
210 discarding the others.
211 It is only defined if the C implementation
212 advertises support for C99.
213 It is used in the definitions of message convenience macros
214 for messages which accept a variable number of arguments
215 but no required arguments,
216 and is exported because the author has found such a thing useful in
220 The following macros are expected to be useful
221 in Sod method definitions and client code.
225 macro returns the class object describing an instance's dynamic class.
227 .BI "const " cls " *" obj
229 .BI SOD_CLASSOF( obj )
236 is typed correctly in the first place)
237 will be a subclass of
239 (If you wanted the class object for
243 .IB cls __class \fR.)
247 macro finds the base address of an instance's layout.
249 .BI "const " cls " *" obj
251 .BI SOD_INSTBASE( obj )
252 returns the base address of the storage allocated to
254 This is useful if you want to free a dynamically allocated instance,
256 This macro needs to look up an offset in
258 vtable to do its work.
262 which is faster but requires
263 precise knowledge of the instance's dynamic class.
267 macro performs general conversions
268 (up-, down-, and cross-casts) on instance pointers.
272 .BI "const void *" obj
277 returns an appropriately converted pointer to
281 is indeed an instance of (some subclass of)
283 otherwise it returns a null pointer.
284 This macro is a simple wrapper around the
286 function described below,
287 which is useful in the common case that
288 the target class is known statically.
292 macro declares and initializes an instance
293 with automatic storage duration.
303 to be a pointer to an instance of
305 The instance is initialized in the sense that
306 its vtable and class pointers have been set up,
307 and slots for which initializers are defined
308 are set to the appropriate initial values.
309 The instance has automatic storage duration:
310 pointers to it will become invalid when control
311 exits the scope of the declaration.
314 The following functions are provided.
318 function answers whether one class
320 is actually a subclass of another class
325 returns nonzero if and only if
329 This involves a run-time trawl through the class structures:
330 while some effort has been made to make it perform well
331 it's still not very fast.
335 function performs general conversions
336 (up-, down-, and cross-casts) on instance pointers.
337 Given a class pointer
339 and an instance pointer
344 returns an appropriately converted pointer to
348 is an instance of (some subclass of)
350 otherwise it returns null.
351 This involves a run-time trawl through the class structures:
352 while some effort has been made to make it perform well
353 it's still not very fast.
356 is a superclass of the static type of
358 the automatically defined conversion macros should be used instead,
359 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
365 .\"--------------------------------------------------------------------------
369 .\"--------------------------------------------------------------------------
371 Mark Wooding, <mdw@distorted.org.uk>
373 .\"----- That's all, folks --------------------------------------------------