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 Sensble Object Design, an object system for C.
  11  *
  12  * SOD is free software; you can redistribute it and/or modify
  13  * it under the terms of the GNU General Public License as published by
  14  * the Free Software Foundation; either version 2 of the License, or
  15  * (at your option) any later version.
  16  *
  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 General Public License for more details.
  21  *
  22  * You should have received a copy of the GNU General Public License
  23  * along with SOD; if not, write to the Free Software Foundation,
  24  * Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  25  */
  26
  27 #ifndef SOD_H
  28 #define SOD_H
  29
  30 #ifdef __cplusplus
  31   extern "C" {
  32 #endif
  33
  34 /*----- Header files ------------------------------------------------------*/
  35
  36 #include <stdarg.h>
  37 #include <stddef.h>
  38
  39 #include "sod-base.h"
  40
  41 /*----- Data structures ---------------------------------------------------*/
  42
  43 /* A skeletal vtable structure.  At the beginning of every ichain is a
  44  * pointer to one of these.
  45  */
  46 struct sod_vtable {
  47   const SodClass *_class;               /* Pointer to class object */
  48   size_t _base;                         /* Offset to instance base */
  49 };
  50
  51 /* A skeletal instance structure.  Every instance pointer points to one of
  52  * these.
  53  */
  54 struct sod_instance {
  55   struct sod_vtable *_vt;               /* Pointer to (chain's) vtable */
  56 };
  57
  58 /* Information about a particular chain of superclasses.  In each class,
  59  * there's a pointer to an array of these.  If you search hard enough, you'll
  60  * be able to find out a fair amount of information about an instance and its
  61  * class.
  62  */
  63 struct sod_chain {
  64   size_t n_classes;                     /* Number of classes in chain */
  65   const SodClass *const *classes;       /* Vector of classes, head first */
  66   size_t off_ichain;                    /* Offset of ichain from base */
  67   const struct sod_vtable *vt;          /* Chain's vtable pointer */
  68   size_t ichainsz;                      /* Size of the ichain structure */
  69 };
  70
  71 /*----- Infrastructure macros ---------------------------------------------*/
  72
  73 /* --- @SOD_XCHAIN@ --- *
  74  *
  75  * Arguments:   @chead@ = nickname of target chain's head
  76  *              @p@ = pointer to an instance chain
  77  *
  78  * Returns:     Pointer to target chain, as a @char *@.
  79  *
  80  * Use:         Utility for implementing cross-chain upcasts.  It's probably
  81  *              not that clever to use this macro directly; it's used to make
  82  *              the automatically-generated upcast macros more palatable.
  83  */
  84
  85 #define SOD_XCHAIN(chead, p) ((char *)(p) + (p)->_vt->_off_##chead)
  86
  87 /* --- @SOD_OFFSETDIFF@ --- *
  88  *
  89  * Arguments:   @type@ = a simple (i.e., declaratorless) type name
  90  *              @mema, memb@ = members of @type@
  91  *
  92  * Returns:     The relative offset from @mema@ to @memb@, as a @ptrdiff_t@.
  93  *
  94  * Use:         Computes a signed offset between structure members.
  95  */
  96
  97 #define SOD_OFFSETDIFF(type, mema, memb)                                \
  98   ((ptrdiff_t)offsetof(type, memb) - (ptrdiff_t)offsetof(type, mema))
  99
 100 /* --- @SOD_ILAYOUT@ --- *
 101  *
 102  * Arguments:   @cls@ = name of a class
 103  *              @chead@ = nickname of chain head of @cls@
 104  *              @p@ = pointer to the @chead@ ichain of an (exact) instance of
 105  *                      @cls@
 106  *
 107  * Returns:     A pointer to the instance's base, cast as a pointer to the
 108  *              ilayout structure.
 109  *
 110  * Use:         Finds an instance's base address given a pointer to one of
 111  *              its ichains, if you know precisely the instance's class and
 112  *              which chain you're pointing to.  If you don't, then (a) you
 113  *              want @SOD_INSTBASE@ below, and (b) you'll have the wrong
 114  *              ilayout anyway.
 115  *
 116  *              This macro is not intended to be used directly outside of
 117  *              automatically generated effective method and trampoline
 118  *              functions, which have the kinds of specific knowledge
 119  *              necessary to use it safely.
 120  */
 121
 122 #define SOD_ILAYOUT(cls, chead, p)                                      \
 123   ((struct cls##__ilayout *)                                            \
 124    ((char *)(p) - offsetof(struct cls##__ilayout, chead)))
 125
 126 /* --- @SOD_INSTBASE@ --- *
 127  *
 128  * Arguments:   @p@ = pointer to an instance (i.e., the address of one of its
 129  *                      instance chains)
 130  *
 131  * Returns:     The base address of @p@'s instance layout.
 132  *
 133  * Use:         Finds the base address of an instance.  If you know the
 134  *              dynamic class of the object then @SOD_ILAYOUT@ is faster.  If
 135  *              you don't, this is the right macro, but your options for
 136  *              doing something sensible with the result are limited, mostly
 137  *              to simple memory management operations such as freeing or
 138  *              zeroizing the instance structure.
 139  */
 140
 141 #define SOD_INSTBASE(p) ((void *)((char *)(p) - (p)->_vt->_base))
 142
 143 /*----- Utility macros ----------------------------------------------------*/
 144
 145 /* --- @SOD_CLASSOF@ --- *
 146  *
 147  * Arguments:   @p@ = pointer to an instance chain
 148  *
 149  * Returns:     A pointer to the instance's class, as a const SodClass.
 150  */
 151
 152 #define SOD_CLASSOF(p) ((const SodClass *)(p)->_vt->_class)
 153
 154 /*----- Functions provided ------------------------------------------------*/
 155
 156 /* --- @sod_subclassp@ --- *
 157  *
 158  * Arguments:   @const SodClass *sub, *super@ = pointers to two classes
 159  *
 160  * Returns:     Nonzero if @c@ is a subclass of @d@.
 161  */
 162
 163 extern int sod_subclassp(const SodClass */*sub*/, const SodClass */*super*/);
 164
 165 /* --- @sod_convert@ --- *
 166  *
 167  * Arguments:   @const SodClass *cls@ = desired class object
 168  *              @const void *obj@ = pointer to instance
 169  *
 170  * Returns:     Pointer to appropriate ichain of object, or null if the
 171  *              instance isn't of the specified class.
 172  *
 173  * Use:         General down/cross-casting function.
 174  *
 175  *              Upcasts can be performed efficiently using the automatically
 176  *              generated macros.  In particular, upcasts within a chain are
 177  *              trivial; cross-chain upcasts require information from vtables
 178  *              but are fairly fast.  This function is rather slower, but is
 179  *              much more general.
 180  *
 181  *              Suppose we have an instance of a class C, referred to by a
 182  *              pointer to an instance of one of C's superclasses S.  If T
 183  *              is some other superclass of C then this function will return
 184  *              a pointer to C suitable for use as an instance of T.  If T
 185  *              is not a superclass of C, then the function returns null.
 186  *              (If the pointer doesn't point to an instance of some class
 187  *              then the behaviour is undefined.)  Note that you don't need
 188  *              to know what either C or S actually are.
 189  */
 190
 191 extern void *sod_convert(const SodClass */*cls*/, const void */*p*/);
 192
 193 /*----- That's all, folks -------------------------------------------------*/
 194
 195 #ifdef __cplusplus
 196   }
 197 #endif
 198
 199 #endif