chiark - git - mdw - sod/blob - lib/sod.h

   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__NORETURN@ --- *
 120  *
 121  * Use:         Marks functions which are not expected to return.
 122  */
 123
 124 #if SOD__GCC_P(2, 5)
 125 #  define SOD__NORETURN __attribute__((__noreturn__))
 126 #endif
 127
 128 #ifndef SOD__NORETURN
 129 #  define SOD__NORETURN
 130 #endif
 131
 132 /* --- @SOD__PARANOIA@ --- *
 133  *
 134  * Arguments:   @cond@ = a condition to check
 135  *              @conseq@ = a thing to evaluate to if the check passes
 136  *              @alt@ = a thing to do if the check fails
 137  *
 138  * Use:         Check to make sure something is good at runtime, unless
 139  *              disabled.
 140  */
 141
 142 #if SOD_RECKLESS
 143 #  define SOD__PARANOIA(cond, conseq, alt) (conseq)
 144 #else
 145 #  define SOD__PARANOIA(cond, conseq, alt) ((cond) ? (conseq) : (alt))
 146 #endif
 147
 148 /* --- @SOD__CAR@ --- *
 149  *
 150  * Arguments:   @...@ = a nonempty list of arguments
 151  *
 152  * Returns:     The first argument only.
 153  */
 154
 155 #ifdef SOD__HAVE_VARARGS_MACROS
 156 #  define SOD__CAR(...) SOD__CARx(__VA_ARGS__, _)
 157 #  define SOD__CARx(a, ...) a
 158 #endif
 159
 160 /*----- Header files ------------------------------------------------------*/
 161
 162 #include <stdarg.h>
 163 #include <stddef.h>
 164
 165 #include "keyword.h"
 166 #include "sod-base.h"
 167
 168 /*----- Data structures ---------------------------------------------------*/
 169
 170 /* A skeletal vtable structure.  At the beginning of every ichain is a
 171  * pointer to one of these.
 172  */
 173 struct sod_vtable {
 174   const SodClass *_class;               /* Pointer to class object */
 175   size_t _base;                         /* Offset to instance base */
 176 };
 177
 178 /* A skeletal instance structure.  Every instance pointer points to one of
 179  * these.
 180  */
 181 struct sod_instance {
 182   const struct sod_vtable *_vt;         /* Pointer to (chain's) vtable */
 183 };
 184
 185 /* Information about a particular chain of superclasses.  In each class,
 186  * there's a pointer to an array of these.  If you search hard enough, you'll
 187  * be able to find out a fair amount of information about an instance and its
 188  * class.
 189  */
 190 struct sod_chain {
 191   size_t n_classes;                     /* Number of classes in chain */
 192   const SodClass *const *classes;       /* Vector of classes, head first */
 193   size_t off_ichain;                    /* Offset of ichain from base */
 194   const struct sod_vtable *vt;          /* Chain's vtable pointer */
 195   size_t ichainsz;                      /* Size of the ichain structure */
 196 };
 197
 198 /*----- Infrastructure macros ---------------------------------------------*/
 199
 200 /* --- @SOD_XCHAIN@ --- *
 201  *
 202  * Arguments:   @chead@ = nickname of target chain's head
 203  *              @obj@ = pointer to an instance chain
 204  *
 205  * Returns:     Pointer to target chain, as a @void *@.
 206  *
 207  * Use:         Utility for implementing cross-chain upcasts.  It's probably
 208  *              not that clever to use this macro directly; it's used to make
 209  *              the automatically-generated upcast macros more palatable.
 210  */
 211
 212 #define SOD_XCHAIN(chead, obj)                                          \
 213   ((void *)((char *)(obj) + (obj)->_vt->_off_##chead))
 214
 215 /* --- @SOD_OFFSETDIFF@ --- *
 216  *
 217  * Arguments:   @type@ = a simple (i.e., declaratorless) type name
 218  *              @mema, memb@ = members of @type@
 219  *
 220  * Returns:     The relative offset from @mema@ to @memb@, as a @ptrdiff_t@.
 221  *
 222  * Use:         Computes a signed offset between structure members.
 223  */
 224
 225 #define SOD_OFFSETDIFF(type, mema, memb)                                \
 226   ((ptrdiff_t)offsetof(type, memb) - (ptrdiff_t)offsetof(type, mema))
 227
 228 /* --- @SOD_ILAYOUT@ --- *
 229  *
 230  * Arguments:   @cls@ = name of a class
 231  *              @chead@ = nickname of chain head of @cls@
 232  *              @obj@ = pointer to the @chead@ ichain of an (exact) instance
 233  *                      of @cls@
 234  *
 235  * Returns:     A pointer to the instance's base, cast as a pointer to the
 236  *              ilayout structure.
 237  *
 238  * Use:         Finds an instance's base address given a pointer to one of
 239  *              its ichains, if you know precisely the instance's class and
 240  *              which chain you're pointing to.  If you don't, then (a) you
 241  *              want @SOD_INSTBASE@ below, and (b) you'll have the wrong
 242  *              ilayout anyway.
 243  *
 244  *              This macro is not intended to be used directly outside of
 245  *              automatically generated effective method and trampoline
 246  *              functions, which have the kinds of specific knowledge
 247  *              necessary to use it safely.
 248  */
 249
 250 #define SOD_ILAYOUT(cls, chead, obj)                                    \
 251   ((struct cls##__ilayout *)                                            \
 252    ((char *)(obj) - offsetof(struct cls##__ilayout, chead)))
 253
 254 /*----- Utility macros ----------------------------------------------------*/
 255
 256 /* --- @SOD_CLASSOF@ --- *
 257  *
 258  * Arguments:   @p@ = pointer to an instance chain
 259  *
 260  * Returns:     A pointer to the instance's class, as a @const SodClass *@.
 261  */
 262
 263 #define SOD_CLASSOF(obj) ((const SodClass *)(obj)->_vt->_class)
 264
 265 /* --- @SOD_INSTBASE@ --- *
 266  *
 267  * Arguments:   @obj@ = pointer to an instance (i.e., the address of one of
 268  *                      its instance chains)
 269  *
 270  * Returns:     The base address of @obj@'s instance layout, as a @void *@.
 271  *
 272  * Use:         Finds the base address of an instance.  If you know the
 273  *              dynamic class of the object then @SOD_ILAYOUT@ is faster.  If
 274  *              you don't, this is the right macro, but your options for
 275  *              doing something sensible with the result are limited, mostly
 276  *              to simple memory management operations such as freeing or
 277  *              zeroizing the instance structure.
 278  */
 279
 280 #define SOD_INSTBASE(obj) ((void *)((char *)(obj) - (obj)->_vt->_base))
 281
 282 /* --- @SOD_CONVERT@ --- *
 283  *
 284  * Arguments:   @cls@ = a class type name
 285  *              @const void *obj@ = a pointer to an instance
 286  *
 287  * Returns:     Pointer to appropriate instance ichain, or null if the
 288  *              instance isn't of the specified class.
 289  *
 290  * Use:         This is a simple wrapper around the @sod_convert@, which
 291  *              you should see for full details.  It accepts a class type
 292  *              name rather than a pointer to a class object, and arranges to
 293  *              return a pointer of the correct type.
 294  */
 295
 296 #define SOD_CONVERT(cls, obj) ((cls *)sod_convert(cls##__class, (obj)))
 297
 298 /* --- @SOD_INIT@ --- *
 299  *
 300  * Arguments:   @cls@ = a class type name
 301  *              @p@ = pointer to storage to initialize
 302  *              @keys@ = a @KWARGS(...)@ keyword argument sequence
 303  *
 304  * Use:         Initializes raw storage as an instance of @cls@.
 305  */
 306
 307 #define SOD_INIT(cls, p, keys) ((cls *)sod_init(cls##__class, (p), keys))
 308
 309 /* --- @SOD_MAKE@ --- *
 310  *
 311  * Arguments:   @cls@ = a class type name
 312  *              @keys@ = a @KWARGS(...)@ keyword argument sequence
 313  *
 314  * Use:         Allocates (using @malloc@) eand initializes storage to be an
 315  *              instance of @cls@.  Returns a null pointer if allocation
 316  *              fails.  Use @sod_destroy@ to release the instance.
 317  */
 318
 319 #define SOD_MAKE(cls, keys) ((cls *)sod_make(cls##__class, keys))
 320
 321 /* --- @SOD_DECL@ --- *
 322  *
 323  * Arguments:   @cls_@ = a class type name
 324  *              @var@ = a variable name
 325  *              @keys@ = a @KWARGS(...)@ keyword argument sequence
 326  *
 327  * Use:         Declare @var@ as a pointer to an initialized instance of
 328  *              @cls@ with automatic lifetime.
 329  */
 330
 331 #define SOD_DECL(cls_, var, keys)                                       \
 332   struct cls_##__ilayout var##__layout;                                 \
 333   cls_ *var =                                                           \
 334     SOD__PARANOIA(sizeof(var##__layout) == cls_##__class->cls.initsz,   \
 335                   (cls_ *)sod_init(cls_##__class, &var##__layout, keys), \
 336                   (sod__chksz_fail(cls_##__class, sizeof(var##__layout)), \
 337                    (cls_ *)0))
 338
 339 /*----- Functions provided ------------------------------------------------*/
 340
 341 /* --- @sod__chksz_fail@ --- *
 342  *
 343  * Arguments:   @const SodClass *cls@ = class we were trying to instantiate
 344  *              @size_t sz@ = size allocated
 345  *
 346  * Returns:     Doesn't.
 347  *
 348  * Use:         Reports instantiation failure caused by a mismatch between
 349  *              the size allocated (@sz@) and the size required for an
 350  *              instance of class @cls@.
 351  */
 352
 353 extern SOD__NORETURN
 354   void sod__chksz_fail(const SodClass */*cls*/, size_t /*sz*/);
 355
 356 /* --- @sod_subclassp@ --- *
 357  *
 358  * Arguments:   @const SodClass *sub, *super@ = pointers to two classes
 359  *
 360  * Returns:     Nonzero if @c@ is a subclass of @d@.
 361  */
 362
 363 extern int sod_subclassp(const SodClass */*sub*/, const SodClass */*super*/);
 364
 365 /* --- @sod_convert@ --- *
 366  *
 367  * Arguments:   @const SodClass *cls@ = desired class object
 368  *              @const void *obj@ = pointer to instance
 369  *
 370  * Returns:     Pointer to appropriate ichain of object, or null if the
 371  *              instance isn't of the specified class.
 372  *
 373  * Use:         General down/cross-casting function.
 374  *
 375  *              Upcasts can be performed efficiently using the automatically
 376  *              generated macros.  In particular, upcasts within a chain are
 377  *              trivial; cross-chain upcasts require information from vtables
 378  *              but are fairly fast.  This function is rather slower, but is
 379  *              much more general.
 380  *
 381  *              Suppose we have an instance of a class C, referred to by a
 382  *              pointer to an instance of one of C's superclasses S.  If T
 383  *              is some other superclass of C then this function will return
 384  *              a pointer to C suitable for use as an instance of T.  If T
 385  *              is not a superclass of C, then the function returns null.
 386  *              (If the pointer doesn't point to an instance of some class
 387  *              then the behaviour is undefined.)  Note that you don't need
 388  *              to know what either C or S actually are.
 389  */
 390
 391 extern void *sod_convert(const SodClass */*cls*/, const void */*obj*/);
 392
 393 /* --- @sod_init@, @sod_initv@ --- *
 394  *
 395  * Arguments:   @const SodClass *cls@ = class object for new instance
 396  *              @void *p@ = pointer to storage for new instance
 397  *              @va_list ap, ...@ = initialization keyword arguments
 398  *
 399  * Returns:     Pointer to the initialized instance.
 400  *
 401  * Use:         Initializes an instance in pre-allocated storage, and returns
 402  *              a pointer to it.
 403  *
 404  *              This function will imprint the storage, and then send an
 405  *              `initialize' message to the fresh instance containing the
 406  *              provided keyword arguments.
 407  *
 408  *              It's usually convenient to use the macro @SOD_INIT@ rather
 409  *              than calling @sod_init@ directly.
 410  */
 411
 412 extern KWCALL void *sod_init(const SodClass */*cls*/, void */*p*/, ...);
 413 extern void *sod_initv(const SodClass */*cls*/, void */*p*/, va_list /*ap*/);
 414
 415 /* --- @sod_make@, @sod_makev@ --- *
 416  *
 417  * Arguments:   @const SodClass *cls@ = class object for new instance
 418  *              @va_list ap, ...@ = initialization keyword arguments
 419  *
 420  * Returns:     Pointer to the newly-allocated initialized instance, or null.
 421  *
 422  * Use:         Allocates storage for a new instance, initializes it, and
 423  *              returns a pointer to it.  If allocation fails, a null pointer
 424  *              is returned instead.
 425  *
 426  *              This function will allocate the storage using @malloc@, and
 427  *              then initialize it as for @sod_init@.
 428  *
 429  *              It's usually convenient to use the macro @SOD_MAKE@ rather
 430  *              than calling @sod_make@ directly.
 431  *
 432  *              (This function is not available in freestanding environments
 433  *              lacking @malloc@ and @free@.)
 434  */
 435
 436 extern KWCALL void *sod_make(const SodClass */*cls*/, ...);
 437 extern void *sod_makev(const SodClass */*cls*/, va_list /*ap*/);
 438
 439 /* --- @sod_teardown@ --- *
 440  *
 441  * Arguments:   @void *p@ = pointer to an instance to be torn down
 442  *
 443  * Returns:     Zero if the object is torn down; nonzero if it refused for
 444  *              some reason.
 445  *
 446  * Use:         Invokes the instance's `teardown' method to release any held
 447  *              resources.
 448  *
 449  *              If this function returns nonzero, then the object is still
 450  *              active, and may still hold important resources.  This is not
 451  *              intended to be a failure condition: failures in teardown are
 452  *              usually unrecoverable (or very hard to recover from) and
 453  *              should probably cause the program to abort.  A refusal, on
 454  *              the other hand, means that the object is still live and
 455  *              shouldn't be deallocated, but that this is a normal situation
 456  *              and the caller shouldn't worry about it.
 457  */
 458
 459 extern int sod_teardown(void */*p*/);
 460
 461 /* --- @sod_destroy@ --- *
 462  *
 463  * Arguments:   @void *p@ = pointer to an instance to be torn down, or null
 464  *
 465  * Returns:     Zero if the object was freed; nonzero if it refused for some
 466  *              reason.
 467  *
 468  * Use:         Invokes the instance's `teardown' method to release any held
 469  *              resources, and then calls @free@ to release the instance's
 470  *              storage.  See @sod_teardown@ for details, especially
 471  *              regarding the return value's meaning.
 472  *
 473  *              If @p@ is null, then this function does nothing except
 474  *              returns zero.
 475  *
 476  *              (This function is not available in freestanding environments
 477  *              lacking @malloc@ and @free@.)
 478  */
 479
 480 extern int sod_destroy(void */*p*/);
 481
 482 /*----- That's all, folks -------------------------------------------------*/
 483
 484 #ifdef __cplusplus
 485   }
 486 #endif
 487
 488 #endif