doc/concepts.tex: Typeset method rôle names as identifiers.

[sod] / lib / sod.h

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

/*----- Licensing notice --------------------------------------------------*
 *
 * This file is part of the Sensible 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

/*----- Preliminary utilities ---------------------------------------------*/

/* Various hacks for checking compiler versions. */
#define SOD__GCC_P(maj, min)						\
	(__GNUC__ > (maj) || (__GNUC__ == (maj) && __GNUC_MINOR__ >= (min)))

#ifdef __GNUC__
#  define SOD__EXTENSION __extension__
#else
#  define SOD__EXTENSION
#endif

/* --- @SOD__HAVE_VARARGS_MACROS@ --- *
 *
 * Use:		Defined if the compiler supports C99-style variadic macros.
 *
 *		This is more complicated than just checking the value of
 *		@__STDC_VERSION__@ because GCC has traditionally claimed C89
 *		by default, but provides the functionality anyway unless it's
 *		been explicitly turned off.
 */

#if __STDC_VERSION__ >= 199901
   /* The feature exists.  All is well with the world. */

#  define SOD__HAVE_VARARGS_MACROS

#elif SOD__GCC_P(3, 0)
   /* We're using GCC, which is trying to deny it but we don't believe it.
    * Unfortunately there's a fly in the ointment: if `-pedantic' -- or,
    * worse, `-pedantic-errors' -- is set, then GCC will warn about these
    * macros being defined, and there isn't a way to detect pedantry from the
    * preprocessor.
    *
    * We must deploy bodges.  There doesn't seem to be a good way to suppress
    * particular warnings from the preprocessor: in particular, messing about
    * with `pragma GCC diagnostic' doesn't help.  So we're left with this
    * hack: just declare all Sod-generated header files which try to do
    * varargs macro things to be `system headers', which means that GCC's
    * preprocessor will let them get away with all manner of nefarious stuff.
    */

#  define SOD__HAVE_VARARGS_MACROS
#  define SOD__VARARGS_MACROS_PREAMBLE _Pragma("GCC system_header")

#endif

/* Make sure this gratuitous hack is understood, at least vacuously. */
#ifndef SOD__VARARGS_MACROS_PREAMBLE
#  define SOD__VARARGS_MACROS_PREAMBLE
#endif

/* We're going to want to make use of this ourselves. */
SOD__VARARGS_MACROS_PREAMBLE

/* --- @SOD__ALIGNOF@ --- *
 *
 * Arguments:	@type@ = a C type name, consisting of declaration specifiers
 *			and `*[QUALIFIERS]' declarator operators
 *
 * Returns:	A sufficient alignment for objects of the given @type@, as a
 *		@size_t@.
 */

#if __STDC_VERSION__ >= 201112
#  define SOD__ALIGNOF(type) _Alignof(type)
#elif SOD__GCC_P(4, 7)
#  define SOD__ALIGNOF(type) __extension__ _Alignof(type)
#elif defined(__GNUC__)
#  define SOD__ALIGNOF(type) __alignof__(type)
#else
#  define SOD__ALIGNOF(type)						\
offsetof(struct { char sod__x; type sod__y; }, sod__y)
#endif

/* --- @SOD__IGNORE@ --- *
 *
 * Arguments:	@var@ = some variable name
 *
 * Use:		Suppress any warning that @var@ isn't used.
 */

#define SOD__IGNORE(var) ((void)(var))

/* --- @SOD__CAR@ --- *
 *
 * Arguments:	@...@ = a nonempty list of arguments
 *
 * Returns:	The first argument only.
 */

#ifdef SOD__HAVE_VARARGS_MACROS
#  define SOD__CAR(...) SOD__CARx(__VA_ARGS__, _)
#  define SOD__CARx(a, ...) a
#endif

/*----- Header files ------------------------------------------------------*/

#include <stdarg.h>
#include <stddef.h>

#include "keyword.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 {
  const 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 @void *@.
 *
 * 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)						\
  ((void *)((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)))

/* --- @SOD_INIT@ --- *
 *
 * Arguments:	@cls@ = a class type name
 *		@p@ = pointer to storage to initialize
 *		@keys@ = a @KWARGS(...)@ keyword argument sequence
 *
 * Use:		Initializes raw storage as an instance of @cls@.
 */

#define SOD_INIT(cls, p, keys) ((cls *)sod_init(cls##__class, (p), keys))

/* --- @SOD_MAKE@ --- *
 *
 * Arguments:	@cls@ = a class type name
 *		@keys@ = a @KWARGS(...)@ keyword argument sequence
 *
 * Use:		Allocates (using @malloc@) eand initializes storage to be an
 *		instance of @cls@.  Returns a null pointer if allocation
 *		fails.  Use @sod_destroy@ to release the instance.
 */

#define SOD_MAKE(cls, keys) ((cls *)sod_make(cls##__class, keys))

/* --- @SOD_DECL@ --- *
 *
 * Arguments:	@cls@ = a class type name
 *		@var@ = a variable name
 *		@keys@ = a @KWARGS(...)@ keyword argument sequence
 *
 * Use:		Declare @var@ as a pointer to an initialized instance of
 *		@cls@ with automatic lifetime.
 */

#define SOD_DECL(cls, var, keys)					\
  struct cls##__ilayout var##__layout;					\
  cls *var = (cls *)sod_init(cls##__class, &var##__layout, keys)

/*----- 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*/);

/* --- @sod_init@, @sod_initv@ --- *
 *
 * Arguments:	@const SodClass *cls@ = class object for new instance
 *		@void *p@ = pointer to storage for new instance
 *		@va_list ap, ...@ = initialization keyword arguments
 *
 * Returns:	Pointer to the initialized instance.
 *
 * Use:		Initializes an instance in pre-allocated storage, and returns
 *		a pointer to it.
 *
 *		This function will imprint the storage, and then send an
 *		`initialize' message to the fresh instance containing the
 *		provided keyword arguments.
 *
 *		It's usually convenient to use the macro @SOD_INIT@ rather
 *		than calling @sod_init@ directly.
 */

extern KWCALL void *sod_init(const SodClass */*cls*/, void */*p*/, ...);
extern void *sod_initv(const SodClass */*cls*/, void */*p*/, va_list /*ap*/);

/* --- @sod_make@, @sod_makev@ --- *
 *
 * Arguments:	@const SodClass *cls@ = class object for new instance
 *		@va_list ap, ...@ = initialization keyword arguments
 *
 * Returns:	Pointer to the newly-allocated initialized instance, or null.
 *
 * Use:		Allocates storage for a new instance, initializes it, and
 *		returns a pointer to it.  If allocation fails, a null pointer
 *		is returned instead.
 *
 *		This function will allocate the storage using @malloc@, and
 *		then initialize it as for @sod_init@.
 *
 *		It's usually convenient to use the macro @SOD_MAKE@ rather
 *		than calling @sod_make@ directly.
 *
 *		(This function is not available in freestanding environments
 *		lacking @malloc@ and @free@.)
 */

extern KWCALL void *sod_make(const SodClass */*cls*/, ...);
extern void *sod_makev(const SodClass */*cls*/, va_list /*ap*/);

/* --- @sod_teardown@ --- *
 *
 * Arguments:	@void *p@ = pointer to an instance to be torn down
 *
 * Returns:	Zero if the object is torn down; nonzero if it refused for
 *		some reason.
 *
 * Use:		Invokes the instance's `teardown' method to release any held
 *		resources.
 *
 *		If this function returns nonzero, then the object is still
 *		active, and may still hold important resources.  This is not
 *		intended to be a failure condition: failures in teardown are
 *		usually unrecoverable (or very hard to recover from) and
 *		should probably cause the program to abort.  A refusal, on
 *		the other hand, means that the object is still live and
 *		shouldn't be deallocated, but that this is a normal situation
 *		and the caller shouldn't worry about it.
 */

extern int sod_teardown(void */*p*/);

/* --- @sod_destroy@ --- *
 *
 * Arguments:	@void *p@ = pointer to an instance to be torn down, or null
 *
 * Returns:	Zero if the object was freed; nonzero if it refused for some
 *		reason.
 *
 * Use:		Invokes the instance's `teardown' method to release any held
 *		resources, and then calls @free@ to release the instance's
 *		storage.  See @sod_teardown@ for details, especially
 *		regarding the return value's meaning.
 *
 *		If @p@ is null, then this function does nothing except
 *		returns zero.
 *
 *		(This function is not available in freestanding environments
 *		lacking @malloc@ and @free@.)
 */

extern int sod_destroy(void */*p*/);

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

#ifdef __cplusplus
  }
#endif

#endif