New feature: proper object lifecycle protocol; init and teardown fragments.

[sod] / doc / structures.tex

diff --git a/doc/structures.tex b/doc/structures.tex
index c31503e..42739ef 100644 (file)
--- 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}