X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/a142609c5dc2a7c3df02497235881beaf47088bf..4faea17df1052a4c4f44f75b6ed537ebe9598c24:/doc/runtime.tex?ds=sidebyside diff --git a/doc/runtime.tex b/doc/runtime.tex index 6a1941d..a8abf85 100644 --- a/doc/runtime.tex +++ b/doc/runtime.tex @@ -42,10 +42,10 @@ calling functions which make use of keyword arguments; see \xref{sec:concepts.ke The header file defines two simple structure types, and a function type which will be described later. -\begin{describe}[struct kwval]{type} - {struct kwval \{ \\ \ind - const char *kw; \\ - const void *val; \- \\ +\begin{describe}{type}[struct kwval] + {struct kwval \{ \\ \ind + const char *kw; \\ + const void *val; \-\\ \};} The @|kwval| structure describes a keyword argument name/value pair. The @@ -55,10 +55,10 @@ will be described later. the actual argument type.) \end{describe} -\begin{describe}[struct kwtab]{type} - {struct kwtab \{ \\ \ind - const struct kwval *v; \\ - size_t n; \- \\ +\begin{describe}{type}[struct kwtab] + {struct kwtab \{ \\ \ind + const struct kwval *v; \\ + size_t n; \-\\ \};} The @|kwtab| structure describes a list of keyword arguments, represented @@ -136,7 +136,7 @@ result will be unbounded recursion or some other bad outcome. The following macros are intended to help with constructing keyword argument lists. Their use is not essential, but may help prevent errors. -\begin{describe}[KWARGS]{mac}{KWARGS(@
)} +\begin{describe}{mac}[KWARGS]{KWARGS(@)} The @ encloses a sequence of keyword arguments expressed as calls to argument consists of a sequence of calls to the keyword-argument macros described below, one after another without any separation. @@ -158,18 +158,18 @@ lists. Their use is not essential, but may help prevent errors. The following keyword-argument macros can be used within the @|KWARGS| @ argument. -\begin{describe}[K]{mac}{K(@, @ , \dots);}
- \dhead[sod_initv]{fun}
+ \dhead{fun}[sod_initv]
{void *sod_initv(const SodClass *@ , va_list @ .
@@ -764,10 +767,19 @@ deallocation, and applications are free to use any suitable mechanism.
\xref{sec:structures.layout.instance}.
\end{describe*}
+\begin{describe}{fun}[sod_teardown]{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.
-\begin{describe}[SOD_DECL]{mac}{SOD_DECL(@ );}
+ 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 --------------------------------------------------