Very ragged work-in-progress.

[sod] / sod.h

/* -*-c-*-
 *
 * Sensible Object Design header file
 *
 * (c) 2009 Straylight/Edgeware
 */

/*----- Licensing notice --------------------------------------------------*
 *
 * This file is part of the Simple Object Definition system.
 *
 * 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 {
  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_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)))

/*----- Functions provided ------------------------------------------------*/

/* --- @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 with 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 S'
 *		is some other superclass of C then this function will return
 *		a pointer to C suitable for use as an instance of S'.  If S'
 *		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 C or S actually are.
 */

extern void *sod_convert(const SodClass */*cls*/, void */*p*/);

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

#ifdef __cplusplus
  }
#endif

#endif