X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/27ec3825bd945bcdae0dca8ab2b4475c4722b313..8d952432c8b961e4e0891eb78620615a8ae14f05:/doc/structures.tex

diff --git a/doc/structures.tex b/doc/structures.tex
index c31503e..3826bdc 100644
--- a/doc/structures.tex
+++ b/doc/structures.tex
@@ -108,7 +108,8 @@ recommended.
         size_t _base; \\
         struct SodObject__vtmsgs_obj \{ \\ \ind
           void (*init)(SodObject *me, ...); \\
-          void (*init__v)(SodObject *me, va_list); \- \\
+          void (*init__v)(SodObject *me, va_list); \\
+          int (*teardown)(SodObject *me); \- \\
         \} obj; \- \\
       \};
     \end{nprog} \\
@@ -135,7 +136,7 @@ recommended.
   The instance and vtable layout of @|SodObject| is shown in
   \xref{fig:structures.root.sodobject}.
 
-  The following message is defined.
+  The following messages are defined.
 
   \begin{describe}[obj.init]{msg}{void init(?);}
     Initialize a newly allocated instance.
@@ -147,15 +148,16 @@ recommended.
     method calls on its @|next_method| function more than once.
 
     This default behaviour is to initialize the instance's slots using the
-    defined slot initializers: each slot is initialized using the most
-    specific applicable initializer, if any.  Slots without an initializer
-    are left uninitialized.
+    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.
 
-    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.
 
     There are no standard keyword arguments; methods on subclasses are free
     to introduce their own in the usual way.
@@ -167,6 +169,30 @@ recommended.
     For more details on instance construction, see
     \xref{sec:concepts.lifecycle.birth}.
   \end{describe}
+
+  \begin{describe}[obj.teardown]{msg}{int teardown();}
+    Teardown an instance which is no longer required.
+
+    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.
+
+    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.
+
+    It is usual to provide complex teardown behaviour as @|before| methods.
+    Logic to decide whether to allow deallocation is usually implemented as
+    @|around| methods.
+  \end{describe}
 \end{describe}
 
 
@@ -178,6 +204,7 @@ recommended.
        const char *name; \\
        const char *nick; \\
        size_t initsz; \\
+       size_t align; \\
        void *(*imprint)(void *@<p>); \\
        size_t n_supers; \\
        const SodClass *const *supers; \\
@@ -205,6 +232,8 @@ recommended.
 
   \item[initsz] The size in bytes required to store an instance of the class.
 
+  \item[align] A sufficient alignment for the class's instance storage.
+
   \item[imprint] A pointer to a function: given a pointer @<p> to at least
     @<initsz> bytes of appropriately aligned memory, `imprint' this memory it
     so that it becomes a minimally functional instance of the class: all of