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 );
83 .BI "const void *" obj );
91 .BI "const SodClass *" sub ,
92 .BI "const SodClass *" super );
96 .BI "const SodClass *" cls ,
97 .BI "const void *" obj );
99 .\"--------------------------------------------------------------------------
102 The functions and macros defined here generally expect that
103 instances and classes inherit from the standard
106 While the translator can (at some effort) support alternative roots,
107 they will require different run-time support machinery.
109 .SS Infrastructure macros
110 These macros are mostly intended for use in code
111 generated by the Sod translator.
112 Others may find them useful for special effects,
113 but they can be tricky to understand and use correctly
114 and can't really be recommended for general use.
118 macro performs a `cross-chain upcast'.
122 to an instance of a class of type
126 of the least specific class in one of
128 superclass chains which does not contain
134 returns the address of that chain's storage
135 within the instance layout as a raw
140 is not mentioned explicitly.)
141 This macro is used by the generated
142 .IB CLASS __CONV_ CLS
144 which you are encouraged to use instead where possible.
148 macro returns the signed offset between
149 two members of a structure or union type.
150 Given a structure or union type
161 gives the difference, in bytes,
170 This macro is used internally when generating vtables
171 and is not expected to be very useful elsewhere.
175 macro recovers the instance layout base address
176 from a pointer to one of its instance chains.
177 Specifically, given a class name
181 of the least specific class in one of
186 to the instance storage for the chain containing
188 within an exact instance of
190 (i.e., not an instance of any proper subclass),
195 returns the a pointer to the layout structure containing
197 This macro is used internally in effective method bodies
198 and is not expected to be very useful elsewhere
199 since it's unusual to have such specific knowledge
200 about the dynamic type of an instance.
203 macro (described below) is more suited to general use.
206 The following macros are expected to be useful
207 in Sod method definitions and client code.
211 macro returns the class object describing an instance's dynamic class.
213 .BI "const " cls " *" obj
215 .BI SOD_CLASSOF( obj )
222 is typed correctly in the first place)
223 will be a subclass of
225 (If you wanted the class object for
229 .IB cls __class \fR.)
233 macro finds the base address of an instance's layout.
235 .BI "const " cls " *" obj
237 .BI SOD_INSTBASE( obj )
238 returns the base address of the storage allocated to
240 This is useful if you want to free a dynamically allocated instance,
242 This macro needs to look up an offset in
244 vtable to do its work.
248 which is faster but requires
249 precise knowledge of the instance's dynamic class.
253 macro performs general conversions
254 (up-, down-, and cross-casts) on instance pointers.
258 .BI "const void *" obj
263 returns an appropriately converted pointer to
267 is indeed an instance of (some subclass of)
269 otherwise it returns a null pointer.
270 This macro is a simple wrapper around the
272 function described below,
273 which is useful in the common case that
274 the target class is known statically.
278 macro declares and initializes an instance
279 with automatic storage duration.
289 to be a pointer to an instance of
291 The instance is initialized in the sense that
292 its vtable and class pointers have been set up,
293 and slots for which initializers are defined
294 are set to the appropriate initial values.
295 The instance has automatic storage duration:
296 pointers to it will become invalid when control
297 exits the scope of the declaration.
300 The following functions are provided.
304 function answers whether one class
306 is actually a subclass of another class
311 returns nonzero if and only if
315 This involves a run-time trawl through the class structures:
316 while some effort has been made to make it perform well
317 it's still not very fast.
321 function performs general conversions
322 (up-, down-, and cross-casts) on instance pointers.
323 Given a class pointer
325 and an instance pointer
330 returns an appropriately converted pointer to
334 is an instance of (some subclass of)
336 otherwise it returns null.
337 This involves a run-time trawl through the class structures:
338 while some effort has been made to make it perform well
339 it's still not very fast.
342 is a superclass of the static type of
344 the automatically defined conversion macros should be used instead,
345 because they're much faster and can't fail.
346 When the target class is known statically,
347 it's slightly more convenient to use the
351 .\"--------------------------------------------------------------------------
356 .\"--------------------------------------------------------------------------
358 Mark Wooding, <mdw@distorted.org.uk>
360 .\"----- That's all, folks --------------------------------------------------