X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/6bc944c3cebb89056d9ed0b53eff6260909291a9..342d5d1d830b7cd5c88d61ba52836f6c59299f9a:/lib/sod.h diff --git a/lib/sod.h b/lib/sod.h index cb6b046..3ad4250 100644 --- a/lib/sod.h +++ b/lib/sod.h @@ -7,7 +7,7 @@ /*----- 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. * * 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 @@ -32,11 +32,137 @@ 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 #include +#include "keyword.h" #include "sod-base.h" /*----- Data structures ---------------------------------------------------*/ @@ -53,7 +179,7 @@ struct sod_vtable { * 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, @@ -76,14 +202,15 @@ struct sod_chain { * Arguments: @chead@ = nickname of target chain's head * @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, obj) ((char *)(obj) + (obj)->_vt->_off_##chead) +#define SOD_XCHAIN(chead, obj) \ + ((void *)((char *)(obj) + (obj)->_vt->_off_##chead)) /* --- @SOD_OFFSETDIFF@ --- * * @@ -124,25 +251,13 @@ struct sod_chain { ((struct cls##__ilayout *) \ ((char *)(obj) - offsetof(struct cls##__ilayout, chead))) -/* --- @SOD__CAR@ --- * - * - * Arguments: @...@ = a nonempty list of arguments - * - * Returns: The first argument only. - */ - -#if __STDC_VERSION__ >= 199901 -# define SOD__CAR(...) SOD__CARx(__VA_LIST__, _) -# define SOD__CARx(a, ...) a -#endif - /*----- Utility macros ----------------------------------------------------*/ /* --- @SOD_CLASSOF@ --- * * * Arguments: @p@ = pointer to an instance chain * - * Returns: A pointer to the instance's class, as a const SodClass. + * Returns: A pointer to the instance's class, as a @const SodClass *@. */ #define SOD_CLASSOF(obj) ((const SodClass *)(obj)->_vt->_class) @@ -180,26 +295,69 @@ struct sod_chain { #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 + * @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. + * Use: Declare @var@ as a pointer to an initialized instance of + * @cls@ with automatic lifetime. */ -#define SOD_DECL(cls_, var_) \ - struct cls_##__ilayout var_##__layout; \ - cls_ *var_ = cls_##__class->cls.init(&var_##__layout) +#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*/); @@ -232,6 +390,95 @@ extern int sod_subclassp(const SodClass */*sub*/, const SodClass */*super*/); 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