X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/27ec3825bd945bcdae0dca8ab2b4475c4722b313..a42893dda5f4dd2b89fbfe4e497da261159225ca:/doc/runtime.tex diff --git a/doc/runtime.tex b/doc/runtime.tex index 6a1941d..7afe8bf 100644 --- 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 *@
);}
+ 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}{@ );}
+ Tears down and frees an instance allocated using @|malloc|.
+
+ The pointer @ 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 --------------------------------------------------