src/c-types-class-impl.lisp (find-sod-class): Improve error reporting.

[sod] / lib / sod-structs.3

diff --git a/lib/sod-structs.3 b/lib/sod-structs.3
index 6cfbb75bbf1c836ee79e3f5885822b4040c2168c..7ac5cccd701560fed89392322506333d96488276 100644 (file)
--- a/lib/sod-structs.3
+++ b/lib/sod-structs.3
@@ -72,6 +72,7 @@ struct SodObject__vt_obj {
 \h'2n'struct SodObject__vtmsgs_obj {
 \h'4n'void (*init)(SodObject *\fIme\fB, ...);
 \h'4n'void (*init__v)(SodObject *\fIme\fB, va_list);
+\h'4n'int (*teardown)(SodObject *\fIme\fB);
 \h'2n'} obj;
 };
 
@@ -92,10 +93,11 @@ struct SodClass__vt_obj {
 \h'2n'struct SodClass__vtmsgs_obj {
 \h'4n'void (*init)(SodClass *\fIme\fB, ...);
 \h'4n'void (*init__v)(SodClass *\fIme\fB, va_list);
+\h'4n'int (*teardown)(SodClass *\fIme\fB);
 \h'2n'} obj;
 };
 
-struct SodObject__ilayout {
+struct SodClass__ilayout {
 \h'2n'union {
 \h'4n'struct SodClass__ichain_obj {
 \h'6n'const struct SodClass__vt_obj *_vt;
@@ -103,6 +105,7 @@ struct SodObject__ilayout {
 \h'8n'const char *name;
 \h'8n'const char *nick;
 \h'8n'size_t initsz;
+\h'8n'size_t align;
 \h'8n'void *(*imprint)(void *\fIp\fB);
 \h'8n'size_t n_supers;
 \h'8n'const SodClass *const *supers;
@@ -254,19 +257,21 @@ if some method calls on its
 function more than once.
 .PP
 This default behaviour is to initialize the instance's slots
-using the defined slot initializers:
-each slot is initialized
+using the defined slot initializers,
+and execute the initialization fragments.
+Each slot is initialized
 using the most specific applicable initializer,
 if any.
 Slots without an initializer
 are left uninitialized.
 .PP
-Slots are initialized in reverse-precedence order
-of their defining classes;
-i.e., slots defined by a less specific superclass are initialized
-earlier than slots defined by a more specific superclass.
-Slots defined by the same class are initialized in the order in which
-they appear in the class definition.
+Slots are initialized and initialization fragments executed together,
+a superclass at a time:
+first, the superclass's slots are initialized (if any);
+then the superclass's initialization fragments (if any) are executed,
+starting with the least specific superclass first.
+Slots and initialization fragments defined by the same class
+are processed in the order in which they appear in the class definition.
 .PP
 There are no standard keyword arguments;
 methods on subclasses are free to
@@ -277,6 +282,38 @@ It is usual to provide complex initialization behaviour as
 methods.
 This ensures that slots have been initialized as necessary
 before the method executes.
+.PP
+The
+.B teardown
+message is used to tear down an instance which is no longer required.
+.PP
+The message returns an integer flag.
+A zero value means that the instance is safe to deallocate.
+A nonzero value means that the instance should not be deallocated,
+and that it is safe for the caller to simply forget about it.
+This simple protocol may be used, for example,
+to implement a reference-counting system.
+.PP
+This message uses a custom method combination
+which works like the standard method combination
+except that default behaviour is invoked if
+no primary or around method overrides.
+This default behaviour is to execute
+each superclass's teardown fragments,
+most specific first,
+and then return zero to indicate
+that the object is ready for deallocation.
+Teardown fragments defined by the same class
+are processed in the order in which they appear
+in the class definition.
+.PP
+It is usual to provide complex teardown behaviour as
+.B before
+methods.
+Logic to decide whether to allow deallocation
+is usually implemented as
+.B around
+methods.
 .
 .SS The SodClass class
 The
@@ -298,6 +335,9 @@ A pointer to the class's nickname.
 .B size_t initsz;
 The size in bytes required to store an instance of the class.
 .TP
+.B size_t align;
+A sufficient alignment for the class's instance storage.
+.TP
 .BI "void *(*imprint)(void *" p );
 A pointer to a function:
 given a pointer
@@ -586,13 +626,9 @@ for each of
 superclasses
 .IR A
 in the same chain in some (unimportant) order.
-A `pointer to
-.IR C '
-is always assumed
-(and, indeed, defined in C's type system)
-to be a pointer to the
-.B struct
-.IB C __ichain_ h \fR.
+The (somewhat obtuse) purpose of this union is to
+engage the `common initial sequence' rule of
+C99 (clause 6.5.2.3).
 .PP
 The
 .B ichain
@@ -624,6 +660,14 @@ then the last member is
 .IB C __islots 
 .IB c ;
 .PP
+A `pointer to
+.IR C '
+is always assumed
+(and, indeed, defined in C's type system)
+to be a pointer to the
+.B struct
+.IB C __ichain_ h \fR.
+.PP
 Finally, the
 .B islots
 structure simply contains one member for each slot defined by
@@ -695,6 +739,12 @@ extern const union \fIC\fB__vtu_\fIh\fB \fIC\fB__vtable_\fIh\fB;
 .ft P
 .fi
 .PP
+In the following,
+let
+.I M
+be the metaclass of
+.IR C .
+.PP
 The outer layer is a
 .B union
 .IB C __vtu_ h