| 1 | /* -*-c-*- |
| 2 | * |
| 3 | * Sensible Object Design header file |
| 4 | * |
| 5 | * (c) 2009 Straylight/Edgeware |
| 6 | */ |
| 7 | |
| 8 | /*----- Licensing notice --------------------------------------------------* |
| 9 | * |
| 10 | * This file is part of the Sensible Object Design, an object system for C. |
| 11 | * |
| 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. |
| 16 | * |
| 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. |
| 21 | * |
| 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. |
| 26 | */ |
| 27 | |
| 28 | #ifndef SOD_H |
| 29 | #define SOD_H |
| 30 | |
| 31 | #ifdef __cplusplus |
| 32 | extern "C" { |
| 33 | #endif |
| 34 | |
| 35 | /*----- Preliminary utilities ---------------------------------------------*/ |
| 36 | |
| 37 | /* Various hacks for checking compiler versions. */ |
| 38 | #define SOD__GCC_P(maj, min) \ |
| 39 | (__GNUC__ > (maj) || (__GNUC__ == (maj) && __GNUC_MINOR__ >= (min))) |
| 40 | |
| 41 | #ifdef __GNUC__ |
| 42 | # define SOD__EXTENSION __extension__ |
| 43 | #else |
| 44 | # define SOD__EXTENSION |
| 45 | #endif |
| 46 | |
| 47 | /* --- @SOD__HAVE_VARARGS_MACROS@ --- * |
| 48 | * |
| 49 | * Use: Defined if the compiler supports C99-style variadic macros. |
| 50 | * |
| 51 | * This is more complicated than just checking the value of |
| 52 | * @__STDC_VERSION__@ because GCC has traditionally claimed C89 |
| 53 | * by default, but provides the functionality anyway unless it's |
| 54 | * been explicitly turned off. |
| 55 | */ |
| 56 | |
| 57 | #if __STDC_VERSION__ >= 199901 |
| 58 | /* The feature exists. All is well with the world. */ |
| 59 | |
| 60 | # define SOD__HAVE_VARARGS_MACROS |
| 61 | |
| 62 | #elif SOD__GCC_P(3, 0) |
| 63 | /* We're using GCC, which is trying to deny it but we don't believe it. |
| 64 | * Unfortunately there's a fly in the ointment: if `-pedantic' -- or, |
| 65 | * worse, `-pedantic-errors' -- is set, then GCC will warn about these |
| 66 | * macros being defined, and there isn't a way to detect pedantry from the |
| 67 | * preprocessor. |
| 68 | * |
| 69 | * We must deploy bodges. There doesn't seem to be a good way to suppress |
| 70 | * particular warnings from the preprocessor: in particular, messing about |
| 71 | * with `pragma GCC diagnostic' doesn't help. So we're left with this |
| 72 | * hack: just declare all Sod-generated header files which try to do |
| 73 | * varargs macro things to be `system headers', which means that GCC's |
| 74 | * preprocessor will let them get away with all manner of nefarious stuff. |
| 75 | */ |
| 76 | |
| 77 | # define SOD__HAVE_VARARGS_MACROS |
| 78 | # define SOD__VARARGS_MACROS_PREAMBLE _Pragma("GCC system_header") |
| 79 | |
| 80 | #endif |
| 81 | |
| 82 | /* Make sure this gratuitous hack is understood, at least vacuously. */ |
| 83 | #ifndef SOD__VARARGS_MACROS_PREAMBLE |
| 84 | # define SOD__VARARGS_MACROS_PREAMBLE |
| 85 | #endif |
| 86 | |
| 87 | /* We're going to want to make use of this ourselves. */ |
| 88 | SOD__VARARGS_MACROS_PREAMBLE |
| 89 | |
| 90 | /* --- @SOD__ALIGNOF@ --- * |
| 91 | * |
| 92 | * Arguments: @type@ = a C type name, consisting of declaration specifiers |
| 93 | * and `*[QUALIFIERS]' declarator operators |
| 94 | * |
| 95 | * Returns: A sufficient alignment for objects of the given @type@, as a |
| 96 | * @size_t@. |
| 97 | */ |
| 98 | |
| 99 | #if __STDC_VERSION__ >= 201112 |
| 100 | # define SOD__ALIGNOF(type) _Alignof(type) |
| 101 | #elif SOD__GCC_P(4, 7) |
| 102 | # define SOD__ALIGNOF(type) __extension__ _Alignof(type) |
| 103 | #elif defined(__GNUC__) |
| 104 | # define SOD__ALIGNOF(type) __alignof__(type) |
| 105 | #else |
| 106 | # define SOD__ALIGNOF(type) \ |
| 107 | offsetof(struct { char sod__x; type sod__y; }, sod__y) |
| 108 | #endif |
| 109 | |
| 110 | /* --- @SOD__IGNORE@ --- * |
| 111 | * |
| 112 | * Arguments: @var@ = some variable name |
| 113 | * |
| 114 | * Use: Suppress any warning that @var@ isn't used. |
| 115 | */ |
| 116 | |
| 117 | #define SOD__IGNORE(var) ((void)(var)) |
| 118 | |
| 119 | /* --- @SOD__CAR@ --- * |
| 120 | * |
| 121 | * Arguments: @...@ = a nonempty list of arguments |
| 122 | * |
| 123 | * Returns: The first argument only. |
| 124 | */ |
| 125 | |
| 126 | #ifdef SOD__HAVE_VARARGS_MACROS |
| 127 | # define SOD__CAR(...) SOD__CARx(__VA_ARGS__, _) |
| 128 | # define SOD__CARx(a, ...) a |
| 129 | #endif |
| 130 | |
| 131 | /*----- Header files ------------------------------------------------------*/ |
| 132 | |
| 133 | #include <stdarg.h> |
| 134 | #include <stddef.h> |
| 135 | |
| 136 | #include "keyword.h" |
| 137 | #include "sod-base.h" |
| 138 | |
| 139 | /*----- Data structures ---------------------------------------------------*/ |
| 140 | |
| 141 | /* A skeletal vtable structure. At the beginning of every ichain is a |
| 142 | * pointer to one of these. |
| 143 | */ |
| 144 | struct sod_vtable { |
| 145 | const SodClass *_class; /* Pointer to class object */ |
| 146 | size_t _base; /* Offset to instance base */ |
| 147 | }; |
| 148 | |
| 149 | /* A skeletal instance structure. Every instance pointer points to one of |
| 150 | * these. |
| 151 | */ |
| 152 | struct sod_instance { |
| 153 | const struct sod_vtable *_vt; /* Pointer to (chain's) vtable */ |
| 154 | }; |
| 155 | |
| 156 | /* Information about a particular chain of superclasses. In each class, |
| 157 | * there's a pointer to an array of these. If you search hard enough, you'll |
| 158 | * be able to find out a fair amount of information about an instance and its |
| 159 | * class. |
| 160 | */ |
| 161 | struct sod_chain { |
| 162 | size_t n_classes; /* Number of classes in chain */ |
| 163 | const SodClass *const *classes; /* Vector of classes, head first */ |
| 164 | size_t off_ichain; /* Offset of ichain from base */ |
| 165 | const struct sod_vtable *vt; /* Chain's vtable pointer */ |
| 166 | size_t ichainsz; /* Size of the ichain structure */ |
| 167 | }; |
| 168 | |
| 169 | /*----- Infrastructure macros ---------------------------------------------*/ |
| 170 | |
| 171 | /* --- @SOD_XCHAIN@ --- * |
| 172 | * |
| 173 | * Arguments: @chead@ = nickname of target chain's head |
| 174 | * @obj@ = pointer to an instance chain |
| 175 | * |
| 176 | * Returns: Pointer to target chain, as a @void *@. |
| 177 | * |
| 178 | * Use: Utility for implementing cross-chain upcasts. It's probably |
| 179 | * not that clever to use this macro directly; it's used to make |
| 180 | * the automatically-generated upcast macros more palatable. |
| 181 | */ |
| 182 | |
| 183 | #define SOD_XCHAIN(chead, obj) \ |
| 184 | ((void *)((char *)(obj) + (obj)->_vt->_off_##chead)) |
| 185 | |
| 186 | /* --- @SOD_OFFSETDIFF@ --- * |
| 187 | * |
| 188 | * Arguments: @type@ = a simple (i.e., declaratorless) type name |
| 189 | * @mema, memb@ = members of @type@ |
| 190 | * |
| 191 | * Returns: The relative offset from @mema@ to @memb@, as a @ptrdiff_t@. |
| 192 | * |
| 193 | * Use: Computes a signed offset between structure members. |
| 194 | */ |
| 195 | |
| 196 | #define SOD_OFFSETDIFF(type, mema, memb) \ |
| 197 | ((ptrdiff_t)offsetof(type, memb) - (ptrdiff_t)offsetof(type, mema)) |
| 198 | |
| 199 | /* --- @SOD_ILAYOUT@ --- * |
| 200 | * |
| 201 | * Arguments: @cls@ = name of a class |
| 202 | * @chead@ = nickname of chain head of @cls@ |
| 203 | * @obj@ = pointer to the @chead@ ichain of an (exact) instance |
| 204 | * of @cls@ |
| 205 | * |
| 206 | * Returns: A pointer to the instance's base, cast as a pointer to the |
| 207 | * ilayout structure. |
| 208 | * |
| 209 | * Use: Finds an instance's base address given a pointer to one of |
| 210 | * its ichains, if you know precisely the instance's class and |
| 211 | * which chain you're pointing to. If you don't, then (a) you |
| 212 | * want @SOD_INSTBASE@ below, and (b) you'll have the wrong |
| 213 | * ilayout anyway. |
| 214 | * |
| 215 | * This macro is not intended to be used directly outside of |
| 216 | * automatically generated effective method and trampoline |
| 217 | * functions, which have the kinds of specific knowledge |
| 218 | * necessary to use it safely. |
| 219 | */ |
| 220 | |
| 221 | #define SOD_ILAYOUT(cls, chead, obj) \ |
| 222 | ((struct cls##__ilayout *) \ |
| 223 | ((char *)(obj) - offsetof(struct cls##__ilayout, chead))) |
| 224 | |
| 225 | /*----- Utility macros ----------------------------------------------------*/ |
| 226 | |
| 227 | /* --- @SOD_CLASSOF@ --- * |
| 228 | * |
| 229 | * Arguments: @p@ = pointer to an instance chain |
| 230 | * |
| 231 | * Returns: A pointer to the instance's class, as a @const SodClass *@. |
| 232 | */ |
| 233 | |
| 234 | #define SOD_CLASSOF(obj) ((const SodClass *)(obj)->_vt->_class) |
| 235 | |
| 236 | /* --- @SOD_INSTBASE@ --- * |
| 237 | * |
| 238 | * Arguments: @obj@ = pointer to an instance (i.e., the address of one of |
| 239 | * its instance chains) |
| 240 | * |
| 241 | * Returns: The base address of @obj@'s instance layout, as a @void *@. |
| 242 | * |
| 243 | * Use: Finds the base address of an instance. If you know the |
| 244 | * dynamic class of the object then @SOD_ILAYOUT@ is faster. If |
| 245 | * you don't, this is the right macro, but your options for |
| 246 | * doing something sensible with the result are limited, mostly |
| 247 | * to simple memory management operations such as freeing or |
| 248 | * zeroizing the instance structure. |
| 249 | */ |
| 250 | |
| 251 | #define SOD_INSTBASE(obj) ((void *)((char *)(obj) - (obj)->_vt->_base)) |
| 252 | |
| 253 | /* --- @SOD_CONVERT@ --- * |
| 254 | * |
| 255 | * Arguments: @cls@ = a class type name |
| 256 | * @const void *obj@ = a pointer to an instance |
| 257 | * |
| 258 | * Returns: Pointer to appropriate instance ichain, or null if the |
| 259 | * instance isn't of the specified class. |
| 260 | * |
| 261 | * Use: This is a simple wrapper around the @sod_convert@, which |
| 262 | * you should see for full details. It accepts a class type |
| 263 | * name rather than a pointer to a class object, and arranges to |
| 264 | * return a pointer of the correct type. |
| 265 | */ |
| 266 | |
| 267 | #define SOD_CONVERT(cls, obj) ((cls *)sod_convert(cls##__class, (obj))) |
| 268 | |
| 269 | /* --- @SOD_INIT@ --- * |
| 270 | * |
| 271 | * Arguments: @cls@ = a class type name |
| 272 | * @p@ = pointer to storage to initialize |
| 273 | * @keys@ = a @KWARGS(...)@ keyword argument sequence |
| 274 | * |
| 275 | * Use: Initializes raw storage as an instance of @cls@. |
| 276 | */ |
| 277 | |
| 278 | #define SOD_INIT(cls, p, keys) ((cls *)sod_init(cls##__class, (p), keys)) |
| 279 | |
| 280 | /* --- @SOD_MAKE@ --- * |
| 281 | * |
| 282 | * Arguments: @cls@ = a class type name |
| 283 | * @keys@ = a @KWARGS(...)@ keyword argument sequence |
| 284 | * |
| 285 | * Use: Allocates (using @malloc@) eand initializes storage to be an |
| 286 | * instance of @cls@. Returns a null pointer if allocation |
| 287 | * fails. Use @sod_destroy@ to release the instance. |
| 288 | */ |
| 289 | |
| 290 | #define SOD_MAKE(cls, keys) ((cls *)sod_make(cls##__class, keys)) |
| 291 | |
| 292 | /* --- @SOD_DECL@ --- * |
| 293 | * |
| 294 | * Arguments: @cls@ = a class type name |
| 295 | * @var@ = a variable name |
| 296 | * @keys@ = a @KWARGS(...)@ keyword argument sequence |
| 297 | * |
| 298 | * Use: Declare @var@ as a pointer to an initialized instance of |
| 299 | * @cls@ with automatic lifetime. |
| 300 | */ |
| 301 | |
| 302 | #define SOD_DECL(cls, var, keys) \ |
| 303 | struct cls##__ilayout var##__layout; \ |
| 304 | cls *var = (cls *)sod_init(cls##__class, &var##__layout, keys) |
| 305 | |
| 306 | /*----- Functions provided ------------------------------------------------*/ |
| 307 | |
| 308 | /* --- @sod_subclassp@ --- * |
| 309 | * |
| 310 | * Arguments: @const SodClass *sub, *super@ = pointers to two classes |
| 311 | * |
| 312 | * Returns: Nonzero if @c@ is a subclass of @d@. |
| 313 | */ |
| 314 | |
| 315 | extern int sod_subclassp(const SodClass */*sub*/, const SodClass */*super*/); |
| 316 | |
| 317 | /* --- @sod_convert@ --- * |
| 318 | * |
| 319 | * Arguments: @const SodClass *cls@ = desired class object |
| 320 | * @const void *obj@ = pointer to instance |
| 321 | * |
| 322 | * Returns: Pointer to appropriate ichain of object, or null if the |
| 323 | * instance isn't of the specified class. |
| 324 | * |
| 325 | * Use: General down/cross-casting function. |
| 326 | * |
| 327 | * Upcasts can be performed efficiently using the automatically |
| 328 | * generated macros. In particular, upcasts within a chain are |
| 329 | * trivial; cross-chain upcasts require information from vtables |
| 330 | * but are fairly fast. This function is rather slower, but is |
| 331 | * much more general. |
| 332 | * |
| 333 | * Suppose we have an instance of a class C, referred to by a |
| 334 | * pointer to an instance of one of C's superclasses S. If T |
| 335 | * is some other superclass of C then this function will return |
| 336 | * a pointer to C suitable for use as an instance of T. If T |
| 337 | * is not a superclass of C, then the function returns null. |
| 338 | * (If the pointer doesn't point to an instance of some class |
| 339 | * then the behaviour is undefined.) Note that you don't need |
| 340 | * to know what either C or S actually are. |
| 341 | */ |
| 342 | |
| 343 | extern void *sod_convert(const SodClass */*cls*/, const void */*obj*/); |
| 344 | |
| 345 | /* --- @sod_init@, @sod_initv@ --- * |
| 346 | * |
| 347 | * Arguments: @const SodClass *cls@ = class object for new instance |
| 348 | * @void *p@ = pointer to storage for new instance |
| 349 | * @va_list ap, ...@ = initialization keyword arguments |
| 350 | * |
| 351 | * Returns: Pointer to the initialized instance. |
| 352 | * |
| 353 | * Use: Initializes an instance in pre-allocated storage, and returns |
| 354 | * a pointer to it. |
| 355 | * |
| 356 | * This function will imprint the storage, and then send an |
| 357 | * `initialize' message to the fresh instance containing the |
| 358 | * provided keyword arguments. |
| 359 | * |
| 360 | * It's usually convenient to use the macro @SOD_INIT@ rather |
| 361 | * than calling @sod_init@ directly. |
| 362 | */ |
| 363 | |
| 364 | extern KWCALL void *sod_init(const SodClass */*cls*/, void */*p*/, ...); |
| 365 | extern void *sod_initv(const SodClass */*cls*/, void */*p*/, va_list /*ap*/); |
| 366 | |
| 367 | /* --- @sod_make@, @sod_makev@ --- * |
| 368 | * |
| 369 | * Arguments: @const SodClass *cls@ = class object for new instance |
| 370 | * @va_list ap, ...@ = initialization keyword arguments |
| 371 | * |
| 372 | * Returns: Pointer to the newly-allocated initialized instance, or null. |
| 373 | * |
| 374 | * Use: Allocates storage for a new instance, initializes it, and |
| 375 | * returns a pointer to it. If allocation fails, a null pointer |
| 376 | * is returned instead. |
| 377 | * |
| 378 | * This function will allocate the storage using @malloc@, and |
| 379 | * then initialize it as for @sod_init@. |
| 380 | * |
| 381 | * It's usually convenient to use the macro @SOD_MAKE@ rather |
| 382 | * than calling @sod_make@ directly. |
| 383 | * |
| 384 | * (This function is not available in freestanding environments |
| 385 | * lacking @malloc@ and @free@.) |
| 386 | */ |
| 387 | |
| 388 | extern KWCALL void *sod_make(const SodClass */*cls*/, ...); |
| 389 | extern void *sod_makev(const SodClass */*cls*/, va_list /*ap*/); |
| 390 | |
| 391 | /* --- @sod_teardown@ --- * |
| 392 | * |
| 393 | * Arguments: @void *p@ = pointer to an instance to be torn down |
| 394 | * |
| 395 | * Returns: Zero if the object is torn down; nonzero if it refused for |
| 396 | * some reason. |
| 397 | * |
| 398 | * Use: Invokes the instance's `teardown' method to release any held |
| 399 | * resources. |
| 400 | * |
| 401 | * If this function returns nonzero, then the object is still |
| 402 | * active, and may still hold important resources. This is not |
| 403 | * intended to be a failure condition: failures in teardown are |
| 404 | * usually unrecoverable (or very hard to recover from) and |
| 405 | * should probably cause the program to abort. A refusal, on |
| 406 | * the other hand, means that the object is still live and |
| 407 | * shouldn't be deallocated, but that this is a normal situation |
| 408 | * and the caller shouldn't worry about it. |
| 409 | */ |
| 410 | |
| 411 | extern int sod_teardown(void */*p*/); |
| 412 | |
| 413 | /* --- @sod_destroy@ --- * |
| 414 | * |
| 415 | * Arguments: @void *p@ = pointer to an instance to be torn down, or null |
| 416 | * |
| 417 | * Returns: Zero if the object was freed; nonzero if it refused for some |
| 418 | * reason. |
| 419 | * |
| 420 | * Use: Invokes the instance's `teardown' method to release any held |
| 421 | * resources, and then calls @free@ to release the instance's |
| 422 | * storage. See @sod_teardown@ for details, especially |
| 423 | * regarding the return value's meaning. |
| 424 | * |
| 425 | * If @p@ is null, then this function does nothing except |
| 426 | * returns zero. |
| 427 | * |
| 428 | * (This function is not available in freestanding environments |
| 429 | * lacking @malloc@ and @free@.) |
| 430 | */ |
| 431 | |
| 432 | extern int sod_destroy(void */*p*/); |
| 433 | |
| 434 | /*----- That's all, folks -------------------------------------------------*/ |
| 435 | |
| 436 | #ifdef __cplusplus |
| 437 | } |
| 438 | #endif |
| 439 | |
| 440 | #endif |