3 * Sensible Object Design header file
5 * (c) 2009 Straylight/Edgeware
8 /*----- Licensing notice --------------------------------------------------*
10 * This file is part of the Sensible Object Design, an object system for C.
12 * The SOD Runtime Library is free software; you can redistribute it and/or
13 * modify 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 * The SOD Runtime 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,
35 /*----- Preliminary utilities ---------------------------------------------*/
37 /* --- @SOD__HAVE_VARARGS_MACROS@ --- *
39 * Use: Defined if the compiler supports C99-style variadic macros.
41 * This is more complicated than just checking the value of
42 * @__STDC_VERSION__@ because GCC has traditionally claimed C89
43 * by default, but provides the functionality anyway unless it's
44 * been explicitly turned off.
47 #if __STDC_VERSION__ >= 199901
48 /* The feature exists. All is well with the world. */
50 # define SOD__HAVE_VARARGS_MACROS
53 /* We're using GCC, which is trying to deny it but we don't believe it.
54 * Unfortunately there's a fly in the ointment: if `-pedantic' -- or,
55 * worse, `-pedantic-errors' -- is set, then GCC will warn about these
56 * macros being defined, and there isn't a way to detect pedantry from the
59 * We must deploy bodges. There doesn't seem to be a good way to suppress
60 * particular warnings from the preprocessor: in particular, messing about
61 * with `pragma GCC diagnostic' doesn't help. So we're left with this
62 * hack: just declare all Sod-generated header files which try to do
63 * varargs macro things to be `system headers', which means that GCC's
64 * preprocessor will let them get away with all manner of nefarious stuff.
67 # define SOD__HAVE_VARARGS_MACROS
68 # define SOD__VARARGS_MACROS_PREAMBLE _Pragma("GCC system_header")
72 /* Make sure this gratuitous hack is understood, at least vacuously. */
73 #ifndef SOD__VARARGS_MACROS_PREAMBLE
74 # define SOD__VARARGS_MACROS_PREAMBLE
77 /* We're going to want to make use of this ourselves. */
78 SOD__VARARGS_MACROS_PREAMBLE
80 /* --- @SOD__CAR@ --- *
82 * Arguments: @...@ = a nonempty list of arguments
84 * Returns: The first argument only.
87 #ifdef SOD__HAVE_VARARGS_MACROS
88 # define SOD__CAR(...) SOD__CARx(__VA_LIST__, _)
89 # define SOD__CARx(a, ...) a
92 /*----- Header files ------------------------------------------------------*/
100 /*----- Data structures ---------------------------------------------------*/
102 /* A skeletal vtable structure. At the beginning of every ichain is a
103 * pointer to one of these.
106 const SodClass
*_class
; /* Pointer to class object */
107 size_t _base
; /* Offset to instance base */
110 /* A skeletal instance structure. Every instance pointer points to one of
113 struct sod_instance
{
114 const struct sod_vtable
*_vt
; /* Pointer to (chain's) vtable */
117 /* Information about a particular chain of superclasses. In each class,
118 * there's a pointer to an array of these. If you search hard enough, you'll
119 * be able to find out a fair amount of information about an instance and its
123 size_t n_classes
; /* Number of classes in chain */
124 const SodClass
*const *classes
; /* Vector of classes, head first */
125 size_t off_ichain
; /* Offset of ichain from base */
126 const struct sod_vtable
*vt
; /* Chain's vtable pointer */
127 size_t ichainsz
; /* Size of the ichain structure */
130 /*----- Infrastructure macros ---------------------------------------------*/
132 /* --- @SOD_XCHAIN@ --- *
134 * Arguments: @chead@ = nickname of target chain's head
135 * @obj@ = pointer to an instance chain
137 * Returns: Pointer to target chain, as a @void *@.
139 * Use: Utility for implementing cross-chain upcasts. It's probably
140 * not that clever to use this macro directly; it's used to make
141 * the automatically-generated upcast macros more palatable.
144 #define SOD_XCHAIN(chead, obj) \
145 ((void *)((char *)(obj) + (obj)->_vt->_off_##chead))
147 /* --- @SOD_OFFSETDIFF@ --- *
149 * Arguments: @type@ = a simple (i.e., declaratorless) type name
150 * @mema, memb@ = members of @type@
152 * Returns: The relative offset from @mema@ to @memb@, as a @ptrdiff_t@.
154 * Use: Computes a signed offset between structure members.
157 #define SOD_OFFSETDIFF(type, mema, memb) \
158 ((ptrdiff_t)offsetof(type, memb) - (ptrdiff_t)offsetof(type, mema))
160 /* --- @SOD_ILAYOUT@ --- *
162 * Arguments: @cls@ = name of a class
163 * @chead@ = nickname of chain head of @cls@
164 * @obj@ = pointer to the @chead@ ichain of an (exact) instance
167 * Returns: A pointer to the instance's base, cast as a pointer to the
170 * Use: Finds an instance's base address given a pointer to one of
171 * its ichains, if you know precisely the instance's class and
172 * which chain you're pointing to. If you don't, then (a) you
173 * want @SOD_INSTBASE@ below, and (b) you'll have the wrong
176 * This macro is not intended to be used directly outside of
177 * automatically generated effective method and trampoline
178 * functions, which have the kinds of specific knowledge
179 * necessary to use it safely.
182 #define SOD_ILAYOUT(cls, chead, obj) \
183 ((struct cls##__ilayout *) \
184 ((char *)(obj) - offsetof(struct cls##__ilayout, chead)))
186 /*----- Utility macros ----------------------------------------------------*/
188 /* --- @SOD_CLASSOF@ --- *
190 * Arguments: @p@ = pointer to an instance chain
192 * Returns: A pointer to the instance's class, as a @const SodClass *@.
195 #define SOD_CLASSOF(obj) ((const SodClass *)(obj)->_vt->_class)
197 /* --- @SOD_INSTBASE@ --- *
199 * Arguments: @obj@ = pointer to an instance (i.e., the address of one of
200 * its instance chains)
202 * Returns: The base address of @obj@'s instance layout, as a @void *@.
204 * Use: Finds the base address of an instance. If you know the
205 * dynamic class of the object then @SOD_ILAYOUT@ is faster. If
206 * you don't, this is the right macro, but your options for
207 * doing something sensible with the result are limited, mostly
208 * to simple memory management operations such as freeing or
209 * zeroizing the instance structure.
212 #define SOD_INSTBASE(obj) ((void *)((char *)(obj) - (obj)->_vt->_base))
214 /* --- @SOD_CONVERT@ --- *
216 * Arguments: @cls@ = a class type name
217 * @const void *obj@ = a pointer to an instance
219 * Returns: Pointer to appropriate instance ichain, or null if the
220 * instance isn't of the specified class.
222 * Use: This is a simple wrapper around the @sod_convert@, which
223 * you should see for full details. It accepts a class type
224 * name rather than a pointer to a class object, and arranges to
225 * return a pointer of the correct type.
228 #define SOD_CONVERT(cls, obj) ((cls *)sod_convert(cls##__class, (obj)))
230 /* --- @SOD_DECL@ --- *
232 * Arguments: @cls_@ = a class type name
233 * @var_@ = a variable name
235 * Use: Declare @var_@ as a pointer to an initialized instance of
236 * @cls_@ with automatic lifetime.
239 #define SOD_DECL(cls_, var_) \
240 struct cls_##__ilayout var_##__layout; \
241 cls_ *var_ = cls_##__class->cls.init(&var_##__layout)
243 /*----- Functions provided ------------------------------------------------*/
245 /* --- @sod_subclassp@ --- *
247 * Arguments: @const SodClass *sub, *super@ = pointers to two classes
249 * Returns: Nonzero if @c@ is a subclass of @d@.
252 extern int sod_subclassp(const SodClass */
*sub*/
, const SodClass */
*super*/
);
254 /* --- @sod_convert@ --- *
256 * Arguments: @const SodClass *cls@ = desired class object
257 * @const void *obj@ = pointer to instance
259 * Returns: Pointer to appropriate ichain of object, or null if the
260 * instance isn't of the specified class.
262 * Use: General down/cross-casting function.
264 * Upcasts can be performed efficiently using the automatically
265 * generated macros. In particular, upcasts within a chain are
266 * trivial; cross-chain upcasts require information from vtables
267 * but are fairly fast. This function is rather slower, but is
270 * Suppose we have an instance of a class C, referred to by a
271 * pointer to an instance of one of C's superclasses S. If T
272 * is some other superclass of C then this function will return
273 * a pointer to C suitable for use as an instance of T. If T
274 * is not a superclass of C, then the function returns null.
275 * (If the pointer doesn't point to an instance of some class
276 * then the behaviour is undefined.) Note that you don't need
277 * to know what either C or S actually are.
280 extern void *sod_convert(const SodClass */
*cls*/
, const void */
*obj*/
);
282 /*----- That's all, folks -------------------------------------------------*/