--- /dev/null
+/* -*-c-*-
+ *
+ * Sensible Object Design header file
+ *
+ * (c) 2009 Straylight/Edgeware
+ */
+
+/*----- Licensing notice --------------------------------------------------*
+ *
+ * This file is part of the Sensble Object Design, an object system for C.
+ *
+ * SOD is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; either version 2 of the License, or
+ * (at your option) any later version.
+ *
+ * SOD is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with SOD; if not, write to the Free Software Foundation,
+ * Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+ */
+
+#ifndef SOD_H
+#define SOD_H
+
+#ifdef __cplusplus
+ extern "C" {
+#endif
+
+/*----- Header files ------------------------------------------------------*/
+
+#include <stdarg.h>
+#include <stddef.h>
+
+#include "sod-base.h"
+
+/*----- Data structures ---------------------------------------------------*/
+
+/* A skeletal vtable structure. At the beginning of every ichain is a
+ * pointer to one of these.
+ */
+struct sod_vtable {
+ const SodClass *_class; /* Pointer to class object */
+ size_t _base; /* Offset to instance base */
+};
+
+/* A skeletal instance structure. Every instance pointer points to one of
+ * these.
+ */
+struct sod_instance {
+ struct sod_vtable *_vt; /* Pointer to (chain's) vtable */
+};
+
+/* Information about a particular chain of superclasses. In each class,
+ * there's a pointer to an array of these. If you search hard enough, you'll
+ * be able to find out a fair amount of information about an instance and its
+ * class.
+ */
+struct sod_chain {
+ size_t n_classes; /* Number of classes in chain */
+ const SodClass *const *classes; /* Vector of classes, head first */
+ size_t off_ichain; /* Offset of ichain from base */
+ const struct sod_vtable *vt; /* Chain's vtable pointer */
+ size_t ichainsz; /* Size of the ichain structure */
+};
+
+/*----- Infrastructure macros ---------------------------------------------*/
+
+/* --- @SOD_XCHAIN@ --- *
+ *
+ * Arguments: @chead@ = nickname of target chain's head
+ * @p@ = pointer to an instance chain
+ *
+ * Returns: Pointer to target chain, as a @char *@.
+ *
+ * Use: Utility for implementing cross-chain upcasts. It's probably
+ * not that clever to use this macro directly; it's used to make
+ * the automatically-generated upcast macros more palatable.
+ */
+
+#define SOD_XCHAIN(chead, p) ((char *)(p) + (p)->_vt->_off_##chead)
+
+/* --- @SOD_OFFSETDIFF@ --- *
+ *
+ * Arguments: @type@ = a simple (i.e., declaratorless) type name
+ * @mema, memb@ = members of @type@
+ *
+ * Returns: The relative offset from @mema@ to @memb@, as a @ptrdiff_t@.
+ *
+ * Use: Computes a signed offset between structure members.
+ */
+
+#define SOD_OFFSETDIFF(type, mema, memb) \
+ ((ptrdiff_t)offsetof(type, memb) - (ptrdiff_t)offsetof(type, mema))
+
+/* --- @SOD_ILAYOUT@ --- *
+ *
+ * Arguments: @cls@ = name of a class
+ * @chead@ = nickname of chain head of @cls@
+ * @p@ = pointer to the @chead@ ichain of an (exact) instance of
+ * @cls@
+ *
+ * Returns: A pointer to the instance's base, cast as a pointer to the
+ * ilayout structure.
+ *
+ * Use: Finds an instance's base address given a pointer to one of
+ * its ichains, if you know precisely the instance's class and
+ * which chain you're pointing to. If you don't, then (a)
+ *
+ * @(char *)(p) - (p)->_vt->_base@
+ *
+ * will do the job just fine, and (b) you'll have the wrong
+ * ilayout anyway.
+ *
+ * This macro is not intended to be used directly outside of
+ * automatically generated effective method and trampoline
+ * functions, which have the kinds of specific knowledge
+ * necessary to use it safely.
+ */
+
+#define SOD_ILAYOUT(cls, chead, p) \
+ ((struct cls##__ilayout *) \
+ ((char *)(p) - offsetof(struct cls##__ilayout, chead)))
+
+/*----- Utility macros ----------------------------------------------------*/
+
+/* --- @SOD_CLASSOF@ --- *
+ *
+ * Arguments: @p@ = pointer to an instance chain
+ *
+ * Returns: A pointer to the instance's class, as a const SodClass.
+ */
+
+#define SOD_CLASSOF(p) ((const SodClass *)(p)->_vt->_class)
+
+/*----- Functions provided ------------------------------------------------*/
+
+/* --- @sod_subclassp@ --- *
+ *
+ * Arguments: @const SodClass *sub, *super@ = pointers to two classes
+ *
+ * Returns: Nonzero if @c@ is a subclass of @d@.
+ */
+
+extern int sod_subclassp(const SodClass */*sub*/, const SodClass */*super*/);
+
+/* --- @sod_convert@ --- *
+ *
+ * Arguments: @const SodClass *cls@ = desired class object
+ * @const void *obj@ = pointer to instance
+ *
+ * Returns: Pointer to appropriate ichain of object, or null if the
+ * instance isn't of the specified class.
+ *
+ * Use: General down/cross-casting function.
+ *
+ * Upcasts can be performed efficiently using the automatically
+ * generated macros. In particular, upcasts within a chain are
+ * trivial; cross-chain upcasts require information from vtables
+ * but are fairly fast. This function is rather slower, but is
+ * much more general.
+ *
+ * Suppose we have an instance of a class C, referred to by a
+ * pointer to an instance of one of C's superclasses S. If T
+ * is some other superclass of C then this function will return
+ * a pointer to C suitable for use as an instance of T. If T
+ * is not a superclass of C, then the function returns null.
+ * (If the pointer doesn't point to an instance of some class
+ * then the behaviour is undefined.) Note that you don't need
+ * to know what either C or S actually are.
+ */
+
+extern void *sod_convert(const SodClass */*cls*/, void */*p*/);
+
+/*----- That's all, folks -------------------------------------------------*/
+
+#ifdef __cplusplus
+ }
+#endif
+
+#endif
~mdw / sod / blobdiff