[sod] / lib / sod.h

/* -*-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.
 *
 * The SOD Runtime Library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Library General Public License as
 * published by the Free Software Foundation; either version 2 of the
 * License, or (at your option) any later version.
 *
 * The SOD Runtime 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 Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library 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
 *              @obj@ = 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, obj) ((char *)(obj) + (obj)->_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@
 *              @obj@ = 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) you
 *              want @SOD_INSTBASE@ below, 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, obj)                                    \
  ((struct cls##__ilayout *)                                            \
   ((char *)(obj) - 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(obj) ((const SodClass *)(obj)->_vt->_class)

/* --- @SOD_INSTBASE@ --- *
 *
 * Arguments:   @obj@ = pointer to an instance (i.e., the address of one of
 *                      its instance chains)
 *
 * Returns:     The base address of @obj@'s instance layout, as a @void *@.
 *
 * Use:         Finds the base address of an instance.  If you know the
 *              dynamic class of the object then @SOD_ILAYOUT@ is faster.  If
 *              you don't, this is the right macro, but your options for
 *              doing something sensible with the result are limited, mostly
 *              to simple memory management operations such as freeing or
 *              zeroizing the instance structure.
 */

#define SOD_INSTBASE(obj) ((void *)((char *)(obj) - (obj)->_vt->_base))

/* --- @SOD_CONVERT@ --- *
 *
 * Arguments:   @cls@ = a class type name
 *              @const void *obj@ = a pointer to an instance
 *
 * Returns:     Pointer to appropriate instance ichain, or null if the
 *              instance isn't of the specified class.
 *
 * Use:         This is a simple wrapper around the @sod_convert@, which
 *              you should see for full details.  It accepts a class type
 *              name rather than a pointer to a class object, and arranges to
 *              return a pointer of the correct type.
 */

#define SOD_CONVERT(cls, obj) ((cls *)sod_convert(cls##__class, (obj)))

/*----- 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*/, const void */*obj*/);

/*----- That's all, folks -------------------------------------------------*/

#ifdef __cplusplus
  }
#endif

#endif