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

[sod] / doc / runtime.tex

diff --git a/doc/runtime.tex b/doc/runtime.tex
index 6a1941d..7afe8bf 100644 (file)
--- a/doc/runtime.tex
+++ b/doc/runtime.tex
@@ -764,6 +764,15 @@ deallocation, and applications are free to use any suitable mechanism.
   \xref{sec:structures.layout.instance}.
 \end{describe*}
 
+\begin{describe}[sod_teardown]{fun}{int sod_teardown(void *@<p>);}
+  Tears down an instance of a class, releasing any resources it holds.
+
+  This function is a very thin wrapper around sending the @|obj.teardown|
+  message.  See the description of that message
+  (page~\pageref{msg:obj.teardown}) and \xref{sec:concepts.lifecycle.death}
+  for details.
+\end{describe}
+
 \subsubsection{Automatic storage duration}
 The following macro constructs an instance with automatic storage duration.
 
@@ -781,7 +790,51 @@ The following macro constructs an instance with automatic storage duration.
   \descref{KWARGS}{mac} or \descref{NO_KWARGS}{mac}.
 
   The instance has automatic storage duration: pointers to it will become
-  invalid when control exits the scope of the declaration.
+  invalid when control exits the scope of the declaration.  If necessary, the
+  instance should be torn down before this happens, using the
+  \descref{sod_teardown}[function]{fun}.
+\end{describe}
+
+\subsubsection{Dynamic allocation}
+The following macros and functions deal with objects allocated from the
+standard C heap.  They don't work in freestanding implementations where
+@|malloc| and @|free| are not available.
+
+\begin{describe*}
+    {\dhead[SOD_MAKE]{mac}{@<cls> *SOD_MAKE(@<cls>, @<keywords>);}
+     \dhead[sod_make]{fun}{void *sod_make(const SodClass *@<cls>, \dots);}
+     \dhead[sod_makev]{fun}
+       {void *sod_makev(const SodClass *@<cls>, va_list @<ap>);}}
+  Constructs and returns a pointer to a new instance of @<cls>.
+
+  The direct class for the new instance is specified as a class name to
+  @|SOD_MAKE|, or a class object to the functions.
+
+  Keyword arguments for the initialization message may be provided.  The
+  @|SOD_MAKE| macro expects a single preprocessor-time argument which is
+  a use of one of \descref{KWARGS}{mac} or \descref{NO_KWARGS}{mac}; the
+  @|sod_make| function expects the keywords as a variable-length argument
+  tail; and @|sod_makev| expects the keywords to be passed indirectly,
+  through the captured argument-tail cursor @<ap>.
+
+  Storage for the new instance will have been allocated using the standard
+  @|malloc| function.  The easiest way to destroy the instance, when it is no
+  longer needed, is probably to call the
+  \descref{sod_destroy}[function]{fun}.
+
+  The return value is an instance pointer for the class @<cls>; the
+  @|SOD_MAKE| macro will have converted it to the correct type, so it should
+  probably be used where possible.
+\end{describe*}
+
+\begin{describe}[sod_destroy]{fun}{int sod_destroy(void *@<p>);}
+  Tears down and frees an instance allocated using @|malloc|.
+
+  The pointer @<p> should be an instance pointer, i.e., a pointer to any of
+  an instance's chains.  The instance is torn down, by sending it the
+  \descref{obj.teardown}[message]{msg}.  If the instance reports itself ready
+  for deallocation, then its storage is released using @|free|.  The return
+  value is the value returned by the @|obj.teardown| message.
 \end{describe}
 
 %%%----- That's all, folks --------------------------------------------------