thunk: deprecate thunk_dispatch_keep()

Enable callees to control lifecycle via return values
in thunk_dispatch() instead.

The thunk_dispatch_keep() function encuraged caller-determined
lifecycles which really doesn't work in practice.

Now if a thunk returns <= 0 it will be freed, negative values are
expected to be used for propagating out fatal errors.  A positive
value (conventionally will just be 1) will bypass the free, which
is expected to be used in thunk reuse situations like iterators.

1 files changed, 7 insertions, 10 deletions

diff --git a/thunk.h b/thunk.h
index f02aff8..d1f407e 100644
--- a/thunk.h
+++ b/thunk.h
@@ -706,25 +706,22 @@ struct thunk_t {
  *
  * After the thunked function returns, the instance is automatically freed,
  * including any payload if THUNK_ALLOC() was used.
+ *
+ * The thunk may suppress automatic freeing by returning 1 (or anything > 0),
+ * giving the callee ability to influence instance life-cycle.  This is
+ * important for iterators/visitor patterns where the thunk should be reused
+ * until either finding a desired entry or reaching the end.
  */
 static inline int thunk_dispatch(thunk_t *thunk) {
 	int	r;
 
 	r = thunk->dispatch(thunk);
-	thunk->free(thunk);
+	if (r <= 0)
+		thunk->free(thunk);
 
 	return r;
 }
 
-/* Same as thunk_dispatch() but without the free.
- * Callers can trivially free thunk instances w/thunk_free().
- * So when a thunk needs to be used repeatedly in a loop for instance, use
- * this, then just free the thunk yourself.
- */
-static inline int thunk_dispatch_keep(thunk_t *thunk) {
-	return thunk->dispatch(thunk);
-}
-
 static inline void thunk_free(thunk_t *thunk) {
 	return thunk->free(thunk);
 }