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 /* --- @SOD__CAR@ --- *
  38  *
  39  * Arguments:   @...@ = a nonempty list of arguments
  40  *
  41  * Returns:     The first argument only.
  42  */
  43
  44 #if __STDC_VERSION__ >= 199901
  45 #  define SOD__CAR(...) SOD__CARx(__VA_LIST__, _)
  46 #  define SOD__CARx(a, ...) a
  47 #endif
  48
  49 /*----- Header files ------------------------------------------------------*/
  50
  51 #include <stdarg.h>
  52 #include <stddef.h>
  53
  54 #include "sod-base.h"
  55
  56 /*----- Data structures ---------------------------------------------------*/
  57
  58 /* A skeletal vtable structure.  At the beginning of every ichain is a
  59  * pointer to one of these.
  60  */
  61 struct sod_vtable {
  62   const SodClass *_class;               /* Pointer to class object */
  63   size_t _base;                         /* Offset to instance base */
  64 };
  65
  66 /* A skeletal instance structure.  Every instance pointer points to one of
  67  * these.
  68  */
  69 struct sod_instance {
  70   const struct sod_vtable *_vt;         /* Pointer to (chain's) vtable */
  71 };
  72
  73 /* Information about a particular chain of superclasses.  In each class,
  74  * there's a pointer to an array of these.  If you search hard enough, you'll
  75  * be able to find out a fair amount of information about an instance and its
  76  * class.
  77  */
  78 struct sod_chain {
  79   size_t n_classes;                     /* Number of classes in chain */
  80   const SodClass *const *classes;       /* Vector of classes, head first */
  81   size_t off_ichain;                    /* Offset of ichain from base */
  82   const struct sod_vtable *vt;          /* Chain's vtable pointer */
  83   size_t ichainsz;                      /* Size of the ichain structure */
  84 };
  85
  86 /*----- Infrastructure macros ---------------------------------------------*/
  87
  88 /* --- @SOD_XCHAIN@ --- *
  89  *
  90  * Arguments:   @chead@ = nickname of target chain's head
  91  *              @obj@ = pointer to an instance chain
  92  *
  93  * Returns:     Pointer to target chain, as a @void *@.
  94  *
  95  * Use:         Utility for implementing cross-chain upcasts.  It's probably
  96  *              not that clever to use this macro directly; it's used to make
  97  *              the automatically-generated upcast macros more palatable.
  98  */
  99
 100 #define SOD_XCHAIN(chead, obj)                                          \
 101   ((void *)((char *)(obj) + (obj)->_vt->_off_##chead))
 102
 103 /* --- @SOD_OFFSETDIFF@ --- *
 104  *
 105  * Arguments:   @type@ = a simple (i.e., declaratorless) type name
 106  *              @mema, memb@ = members of @type@
 107  *
 108  * Returns:     The relative offset from @mema@ to @memb@, as a @ptrdiff_t@.
 109  *
 110  * Use:         Computes a signed offset between structure members.
 111  */
 112
 113 #define SOD_OFFSETDIFF(type, mema, memb)                                \
 114   ((ptrdiff_t)offsetof(type, memb) - (ptrdiff_t)offsetof(type, mema))
 115
 116 /* --- @SOD_ILAYOUT@ --- *
 117  *
 118  * Arguments:   @cls@ = name of a class
 119  *              @chead@ = nickname of chain head of @cls@
 120  *              @obj@ = pointer to the @chead@ ichain of an (exact) instance
 121  *                      of @cls@
 122  *
 123  * Returns:     A pointer to the instance's base, cast as a pointer to the
 124  *              ilayout structure.
 125  *
 126  * Use:         Finds an instance's base address given a pointer to one of
 127  *              its ichains, if you know precisely the instance's class and
 128  *              which chain you're pointing to.  If you don't, then (a) you
 129  *              want @SOD_INSTBASE@ below, and (b) you'll have the wrong
 130  *              ilayout anyway.
 131  *
 132  *              This macro is not intended to be used directly outside of
 133  *              automatically generated effective method and trampoline
 134  *              functions, which have the kinds of specific knowledge
 135  *              necessary to use it safely.
 136  */
 137
 138 #define SOD_ILAYOUT(cls, chead, obj)                                    \
 139   ((struct cls##__ilayout *)                                            \
 140    ((char *)(obj) - offsetof(struct cls##__ilayout, chead)))
 141
 142 /*----- Utility macros ----------------------------------------------------*/
 143
 144 /* --- @SOD_CLASSOF@ --- *
 145  *
 146  * Arguments:   @p@ = pointer to an instance chain
 147  *
 148  * Returns:     A pointer to the instance's class, as a @const SodClass *@.
 149  */
 150
 151 #define SOD_CLASSOF(obj) ((const SodClass *)(obj)->_vt->_class)
 152
 153 /* --- @SOD_INSTBASE@ --- *
 154  *
 155  * Arguments:   @obj@ = pointer to an instance (i.e., the address of one of
 156  *                      its instance chains)
 157  *
 158  * Returns:     The base address of @obj@'s instance layout, as a @void *@.
 159  *
 160  * Use:         Finds the base address of an instance.  If you know the
 161  *              dynamic class of the object then @SOD_ILAYOUT@ is faster.  If
 162  *              you don't, this is the right macro, but your options for
 163  *              doing something sensible with the result are limited, mostly
 164  *              to simple memory management operations such as freeing or
 165  *              zeroizing the instance structure.
 166  */
 167
 168 #define SOD_INSTBASE(obj) ((void *)((char *)(obj) - (obj)->_vt->_base))
 169
 170 /* --- @SOD_CONVERT@ --- *
 171  *
 172  * Arguments:   @cls@ = a class type name
 173  *              @const void *obj@ = a pointer to an instance
 174  *
 175  * Returns:     Pointer to appropriate instance ichain, or null if the
 176  *              instance isn't of the specified class.
 177  *
 178  * Use:         This is a simple wrapper around the @sod_convert@, which
 179  *              you should see for full details.  It accepts a class type
 180  *              name rather than a pointer to a class object, and arranges to
 181  *              return a pointer of the correct type.
 182  */
 183
 184 #define SOD_CONVERT(cls, obj) ((cls *)sod_convert(cls##__class, (obj)))
 185
 186 /* --- @SOD_DECL@ --- *
 187  *
 188  * Arguments:   @cls_@ = a class type name
 189  *              @var_@ = a variable name
 190  *
 191  * Use:         Declare @var_@ as a pointer to an initialized instance of
 192  *              @cls_@ with automatic lifetime.
 193  */
 194
 195 #define SOD_DECL(cls_, var_)                                            \
 196   struct cls_##__ilayout var_##__layout;                                \
 197   cls_ *var_ = cls_##__class->cls.init(&var_##__layout)
 198
 199 /*----- Functions provided ------------------------------------------------*/
 200
 201 /* --- @sod_subclassp@ --- *
 202  *
 203  * Arguments:   @const SodClass *sub, *super@ = pointers to two classes
 204  *
 205  * Returns:     Nonzero if @c@ is a subclass of @d@.
 206  */
 207
 208 extern int sod_subclassp(const SodClass */*sub*/, const SodClass */*super*/);
 209
 210 /* --- @sod_convert@ --- *
 211  *
 212  * Arguments:   @const SodClass *cls@ = desired class object
 213  *              @const void *obj@ = pointer to instance
 214  *
 215  * Returns:     Pointer to appropriate ichain of object, or null if the
 216  *              instance isn't of the specified class.
 217  *
 218  * Use:         General down/cross-casting function.
 219  *
 220  *              Upcasts can be performed efficiently using the automatically
 221  *              generated macros.  In particular, upcasts within a chain are
 222  *              trivial; cross-chain upcasts require information from vtables
 223  *              but are fairly fast.  This function is rather slower, but is
 224  *              much more general.
 225  *
 226  *              Suppose we have an instance of a class C, referred to by a
 227  *              pointer to an instance of one of C's superclasses S.  If T
 228  *              is some other superclass of C then this function will return
 229  *              a pointer to C suitable for use as an instance of T.  If T
 230  *              is not a superclass of C, then the function returns null.
 231  *              (If the pointer doesn't point to an instance of some class
 232  *              then the behaviour is undefined.)  Note that you don't need
 233  *              to know what either C or S actually are.
 234  */
 235
 236 extern void *sod_convert(const SodClass */*cls*/, const void */*obj*/);
 237
 238 /*----- That's all, folks -------------------------------------------------*/
 239
 240 #ifdef __cplusplus
 241   }
 242 #endif
 243
 244 #endif