3 * Sensible Object Design header file
5 * (c) 2009 Straylight/Edgeware
8 /*----- Licensing notice --------------------------------------------------*
10 * This file is part of the Simple Object Definition system.
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.
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.
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.
34 /*----- Header files ------------------------------------------------------*/
41 /*----- Data structures ---------------------------------------------------*/
43 /* A skeletal vtable structure. At the beginning of every ichain is a
44 * pointer to one of these.
47 SodClass
*_class
; /* Pointer to class object */
48 size_t _base
; /* Offset to instance base */
51 /* A skeletal instance structure. Every instance pointer points to one of
55 struct sod_vtable
*_vt
; /* Pointer to (chain's) vtable */
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
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 */
71 /*----- Infrastructure macros ---------------------------------------------*/
73 /* --- @SOD_XCHAIN@ --- *
75 * Arguments: @chead@ = nickname of target chain's head
76 * @p@ = pointer to an instance chain
78 * Returns: Pointer to target chain, as a @char *@.
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.
85 #define SOD_XCHAIN(chead, p) ((char *)(p) + (p)->_vt->_off_##chead)
87 /* --- @SOD_ILAYOUT@ --- *
89 * Arguments: @cls@ = name of a class
90 * @chead@ = nickname of chain head of @cls@
91 * @p@ = pointer to the @chead@ ichain of an (exact) instance of
94 * Returns: A pointer to the instance's base, cast as a pointer to the
97 * Use: Finds an instance's base address given a pointer to one of
98 * its ichains, if you know precisely the instance's class and
99 * which chain you're pointing to. If you don't, then (a)
101 * @(char *)(p) - (p)->_vt->_base@
103 * will do the job just fine, and (b) you'll have the wrong
106 * This macro is not intended to be used directly outside of
107 * automatically generated effective method and trampoline
108 * functions, which have the kinds of specific knowledge
109 * necessary to use it safely.
112 #define SOD_ILAYOUT(cls, chead, p) \
113 ((struct cls##__ilayout *) \
114 ((char *)(p) - offsetof(struct cls##__ilayout, chead)))
116 /*----- Utility macros ----------------------------------------------------*/
118 /* --- @SOD_CLASSOF@ --- *
120 * Arguments: @p@ = pointer to an instance chain
122 * Returns: A pointer to the instance's class, as a const SodClass.
125 #define SOD_CLASSOF(p) ((const SodClass *)(p)->_vt->_class)
127 /*----- Functions provided ------------------------------------------------*/
129 /* --- @sod_subclassp@ --- *
131 * Arguments: @const SodClass *c, *d@ = pointers to two classes
133 * Returns: Nonzero if @c@ is a subclass of @d@.
136 extern int sod_subclassp(const SodClass */
*c*/
, const SodClass */
*d*/
);
138 /* --- @sod_convert@ --- *
140 * Arguments: @const SodClass *cls@ = desired class object
141 * @const void *obj@ = pointer to instance
143 * Returns: Pointer to appropriate ichain of object, or null if the
144 * instance isn't of the specified class.
146 * Use: General down/cross-casting function.
148 * Upcasts can be performed efficiently using the automatically
149 * generated macros. In particular, upcasts with a chain are
150 * trivial; cross-chain upcasts require information from vtables
151 * but are fairly fast. This function is rather slower, but is
154 * Suppose we have an instance of a class C, referred to by a
155 * pointer to an instance of one of C's superclasses S. If S'
156 * is some other superclass of C then this function will return
157 * a pointer to C suitable for use as an instance of S'. If S'
158 * is not a superclass of C, then the function returns null.
159 * (If the pointer doesn't point to an instance of some class
160 * then the behaviour is undefined.) Note that you don't need
161 * to know what C or S actually are.
164 extern void *sod_convert(const SodClass */
*cls*/
, void */
*p*/
);
166 /*----- That's all, folks -------------------------------------------------*/