From: Mark Wooding <mdw@distorted.org.uk>
Date: Mon, 5 Aug 2019 09:22:48 +0000 (+0100)
Subject: doc/runtime.tex: Suggest asserting that a stack-allocated object tore down.
X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~mdw/git/sod/commitdiff_plain/5ffbe7949e61a61451bb6ebedc5482e8568d7421?ds=inline

doc/runtime.tex: Suggest asserting that a stack-allocated object tore down.

As discussed, it's not an error in itself if an object refuses teardown:
that just means that you can forget about it and it's someone else's
problem now.  But if you really have to deallocate it right now, that's
not going to work.

It might be an idea to introduce a macro to say, essentially,

	{ int rc = sod_teardown(OBJ); assert(!rc); }
---

diff --git a/doc/runtime.tex b/doc/runtime.tex
index a67d994..46e470e 100644
--- a/doc/runtime.tex
+++ b/doc/runtime.tex
@@ -815,7 +815,8 @@ The following macro constructs an instance with automatic storage duration.
   The instance has automatic storage duration: pointers to it will become
   invalid when control exits the scope of the declaration.  If necessary, the
   instance should be torn down before this happens, using the
-  \descref{fun}{sod_teardown}[function].
+  \descref{fun}{sod_teardown}[function].  It may be appropriate to @|assert|
+  that the object is ready for deallocation at this time.
 \end{describe}
 
 \subsubsection{Dynamic allocation}
diff --git a/lib/sod.3 b/lib/sod.3
index b6bc6dc..9f95c78 100644
--- a/lib/sod.3
+++ b/lib/sod.3
@@ -480,6 +480,9 @@ the instance should be torn down before this happens,
 using the
 .B sod_teardown
 function.
+It may be appropriate to
+.BR assert (3)
+that the object is ready for deallocation at this time.
 .PP
 The
 .B SOD_MAKE