X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/8c2c58ae77fe3afce6ac4d027e9e47157a535961..342d5d1d830b7cd5c88d61ba52836f6c59299f9a:/lib/sod.h

diff --git a/lib/sod.h b/lib/sod.h
index 943ed4b..3ad4250 100644
--- a/lib/sod.h
+++ b/lib/sod.h
@@ -104,7 +104,45 @@ SOD__VARARGS_MACROS_PREAMBLE
 #  define SOD__ALIGNOF(type) __alignof__(type)
 #else
 #  define SOD__ALIGNOF(type)						\
-offsetof(struct { char sod__x; type sod__y; }, sod__y)
+	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@ --- *
@@ -115,7 +153,7 @@ offsetof(struct { char sod__x; type sod__y; }, sod__y)
  */
 
 #ifdef SOD__HAVE_VARARGS_MACROS
-#  define SOD__CAR(...) SOD__CARx(__VA_LIST__, _)
+#  define SOD__CAR(...) SOD__CARx(__VA_ARGS__, _)
 #  define SOD__CARx(a, ...) a
 #endif
 
@@ -124,6 +162,7 @@ offsetof(struct { char sod__x; type sod__y; }, sod__y)
 #include <stdarg.h>
 #include <stddef.h>
 
+#include "keyword.h"
 #include "sod-base.h"
 
 /*----- Data structures ---------------------------------------------------*/
@@ -256,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*/);
@@ -308,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