From 5ffbe7949e61a61451bb6ebedc5482e8568d7421 Mon Sep 17 00:00:00 2001
From: Mark Wooding <mdw@distorted.org.uk>
Date: Mon, 5 Aug 2019 10:22:48 +0100
Subject: [PATCH] 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); }
---
 doc/runtime.tex | 3 ++-
 lib/sod.3       | 3 +++
 2 files changed, 5 insertions(+), 1 deletion(-)

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
-- 
2.11.0

