/*----- Licensing notice --------------------------------------------------*
*
- * This file is part of the Sensble Object Design, an object system for C.
+ * This file is part of the Sensible 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.
+ * 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.
*
- * SOD is distributed in the hope that it will be useful,
+ * 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 General Public License for more details.
+ * GNU Library 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.
+ * 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
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__NORETURN@ --- *
+ *
+ * Use: Marks functions which are not expected to return.
+ */
+
+#if SOD__GCC_P(2, 5)
+# define SOD__NORETURN __attribute__((__noreturn__))
+#endif
+
+#ifndef SOD__NORETURN
+# define SOD__NORETURN
+#endif
+
+/* --- @SOD__PARANOIA@ --- *
+ *
+ * Arguments: @cond@ = a condition to check
+ * @conseq@ = a thing to evaluate to if the check passes
+ * @alt@ = a thing to do if the check fails
+ *
+ * Use: Check to make sure something is good at runtime, unless
+ * disabled.
+ */
+
+#if SOD_RECKLESS
+# define SOD__PARANOIA(cond, conseq, alt) (conseq)
+#else
+# define SOD__PARANOIA(cond, conseq, alt) ((cond) ? (conseq) : (alt))
+#endif
+
+/* --- @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 ---------------------------------------------------*/
* these.
*/
struct sod_instance {
- struct sod_vtable *_vt; /* Pointer to (chain's) vtable */
+ const struct sod_vtable *_vt; /* Pointer to (chain's) vtable */
};
/* Information about a particular chain of superclasses. In each class,
/* --- @SOD_XCHAIN@ --- *
*
* Arguments: @chead@ = nickname of target chain's head
- * @p@ = pointer to an instance chain
+ * @obj@ = pointer to an instance chain
*
- * Returns: Pointer to target chain, as a @char *@.
+ * 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, p) ((char *)(p) + (p)->_vt->_off_##chead)
+#define SOD_XCHAIN(chead, obj) \
+ ((void *)((char *)(obj) + (obj)->_vt->_off_##chead))
/* --- @SOD_OFFSETDIFF@ --- *
*
*
* 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@
+ * @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.
* necessary to use it safely.
*/
-#define SOD_ILAYOUT(cls, chead, p) \
+#define SOD_ILAYOUT(cls, chead, obj) \
((struct cls##__ilayout *) \
- ((char *)(p) - offsetof(struct cls##__ilayout, chead)))
+ ((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: @p@ = pointer to an instance (i.e., the address of one of its
- * instance chains)
+ * Arguments: @obj@ = pointer to an instance (i.e., the address of one of
+ * its instance chains)
*
- * Returns: The base address of @p@'s instance layout.
+ * 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
* zeroizing the instance structure.
*/
-#define SOD_INSTBASE(p) ((void *)((char *)(p) - (p)->_vt->_base))
+#define SOD_INSTBASE(obj) ((void *)((char *)(obj) - (obj)->_vt->_base))
-/*----- Utility macros ----------------------------------------------------*/
+/* --- @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.
+ */
-/* --- @SOD_CLASSOF@ --- *
+#define SOD_CONVERT(cls, obj) ((cls *)sod_convert(cls##__class, (obj)))
+
+/* --- @SOD_INIT@ --- *
*
- * Arguments: @p@ = pointer to an instance chain
+ * 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
*
- * Returns: A pointer to the instance's class, as a const SodClass.
+ * Use: Declare @var@ as a pointer to an initialized instance of
+ * @cls@ with automatic lifetime.
*/
-#define SOD_CLASSOF(p) ((const SodClass *)(p)->_vt->_class)
+#define SOD_DECL(cls_, var, keys) \
+ struct cls_##__ilayout var##__layout; \
+ cls_ *var = \
+ SOD__PARANOIA(sizeof(var##__layout) == cls_##__class->cls.initsz, \
+ (cls_ *)sod_init(cls_##__class, &var##__layout, keys), \
+ (sod__chksz_fail(cls_##__class, sizeof(var##__layout)), \
+ (cls_ *)0))
/*----- Functions provided ------------------------------------------------*/
+/* --- @sod__chksz_fail@ --- *
+ *
+ * Arguments: @const SodClass *cls@ = class we were trying to instantiate
+ * @size_t sz@ = size allocated
+ *
+ * Returns: Doesn't.
+ *
+ * Use: Reports instantiation failure caused by a mismatch between
+ * the size allocated (@sz@) and the size required for an
+ * instance of class @cls@.
+ */
+
+extern SOD__NORETURN
+ void sod__chksz_fail(const SodClass */*cls*/, size_t /*sz*/);
+
/* --- @sod_subclassp@ --- *
*
* Arguments: @const SodClass *sub, *super@ = pointers to two classes
*
- * Returns: Nonzero if @c@ is a subclass of @d@.
+ * Returns: Nonzero if @sub@ is a subclass of @super@.
*/
extern int sod_subclassp(const SodClass */*sub*/, const SodClass */*super*/);
* to know what either C or S actually are.
*/
-extern void *sod_convert(const SodClass */*cls*/, void */*p*/);
+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 -------------------------------------------------*/
~mdw / sod / blobdiff