From 6396cce7e094022dc22288d377aa97d73268b657 Mon Sep 17 00:00:00 2001
From: Hayodea Hekol <hayodea@protonmail.com>
Date: Tue, 19 May 2026 09:57:24 -0400
Subject: [PATCH] Impl NonViralNonPostingInvoker; rename other invokers around
 posting behaviour

---
 include/spinscale/co/group.h             |   2 +-
 include/spinscale/co/invokers.h          |  68 +++++++++++---
 include/spinscale/co/nonPostingInvoker.h |  63 +++++++++++++
 include/spinscale/co/nonPostingPromise.h | 108 +++++++++++++++++++++++
 include/spinscale/puppetApplication.h    |  10 +--
 src/puppetApplication.cpp                |  10 +--
 6 files changed, 240 insertions(+), 21 deletions(-)
 create mode 100644 include/spinscale/co/nonPostingInvoker.h
 create mode 100644 include/spinscale/co/nonPostingPromise.h

diff --git a/include/spinscale/co/group.h b/include/spinscale/co/group.h
index e0e5b64..ff6f895 100644
--- a/include/spinscale/co/group.h
+++ b/include/spinscale/co/group.h
@@ -471,7 +471,7 @@ struct Group
 		std::size_t settlementIndex) noexcept
 	{
 		/**	EXPLANATION:
-		 * It's very convenient that our design for the NonViralNonSuspendingInvoker
+		 * It's very convenient that our design for the NonViralPostingInvoker
 		 * coincidentally allows us to supply a lambda that can be used to test
 		 * for the settlement conditions that are being waited on by the Group's
 		 * co_awaiter.
diff --git a/include/spinscale/co/invokers.h b/include/spinscale/co/invokers.h
index a182ad8..dc70399 100644
--- a/include/spinscale/co/invokers.h
+++ b/include/spinscale/co/invokers.h
@@ -10,6 +10,7 @@
 #include <thread>
 #include <type_traits>
 
+#include <spinscale/co/nonPostingInvoker.h>
 #include <spinscale/co/postingInvoker.h>
 
 namespace sscl::co {
@@ -21,7 +22,7 @@ namespace sscl::co {
  *	from get_return_object(). ~PostingInvoker destroys the callee frame.
  */
 template <template <typename> class PostingPromiseTemplate>
-struct NonViralNonSuspendingInvoker
+struct NonViralPostingInvoker
 :	public PostingInvoker<PostingPromiseTemplate<void>, void>
 {
 	struct promise_type
@@ -29,10 +30,10 @@ struct NonViralNonSuspendingInvoker
 	{
 		using PostingPromiseTemplate<void>::PostingPromiseTemplate;
 
-		NonViralNonSuspendingInvoker<PostingPromiseTemplate> get_return_object()
+		NonViralPostingInvoker<PostingPromiseTemplate> get_return_object()
 		{
 #ifdef CONFIG_LIBSSCL_DEBUG_CO
-			std::cout << __func__ << ": " << std::this_thread::get_id() << " Returning NonViralNonSuspendingInvoker.\n";
+			std::cout << __func__ << ": " << std::this_thread::get_id() << " Returning NonViralPostingInvoker.\n";
 #endif
 			if (!this->callerLambda)
 			{
@@ -53,7 +54,7 @@ struct NonViralNonSuspendingInvoker
 			this->setSelfSchedHandle(
 				std::coroutine_handle<promise_type>::from_promise(*this));
 
-			return NonViralNonSuspendingInvoker<PostingPromiseTemplate>(*this);
+			return NonViralPostingInvoker<PostingPromiseTemplate>(*this);
 		}
 	};
 
@@ -62,7 +63,7 @@ struct NonViralNonSuspendingInvoker
 	bool await_ready() const noexcept
 		{ std::terminate(); }
 
-	void await_suspend(std::coroutine_handle<NonViralNonSuspendingInvoker<PostingPromiseTemplate>>) noexcept
+	void await_suspend(std::coroutine_handle<NonViralPostingInvoker<PostingPromiseTemplate>>) noexcept
 		{ std::terminate(); }
 
 	void await_resume() noexcept
@@ -76,7 +77,7 @@ struct NonViralNonSuspendingInvoker
  *	~PostingInvoker destroys the callee frame (not await_resume).
  */
 template <template <typename> class PostingPromiseTemplate, typename T>
-struct ViralSuspendingInvoker
+struct ViralPostingInvoker
 :	public PostingInvoker<PostingPromiseTemplate<T>, T>
 {
 	struct promise_type
@@ -84,15 +85,15 @@ struct ViralSuspendingInvoker
 	{
 		using PostingPromiseTemplate<T>::PostingPromiseTemplate;
 
-		ViralSuspendingInvoker<PostingPromiseTemplate, T> get_return_object() noexcept
+		ViralPostingInvoker<PostingPromiseTemplate, T> get_return_object() noexcept
 		{
 #ifdef CONFIG_LIBSSCL_DEBUG_CO
-			std::cout << __func__ << ": " << std::this_thread::get_id() << " Returning ViralSuspendingInvoker.\n";
+			std::cout << __func__ << ": " << std::this_thread::get_id() << " Returning ViralPostingInvoker.\n";
 #endif
 			this->setSelfSchedHandle(
 				std::coroutine_handle<promise_type>::from_promise(*this));
 
-			return ViralSuspendingInvoker<PostingPromiseTemplate, T>(*this);
+			return ViralPostingInvoker<PostingPromiseTemplate, T>(*this);
 		}
 	};
 
@@ -111,7 +112,7 @@ struct ViralSuspendingInvoker
 	{
 		static_assert(
 			std::is_base_of_v<PromiseChainLink, CallerPromise>,
-			"ViralSuspendingInvoker caller promise must derive from PromiseChainLink");
+			"ViralPostingInvoker caller promise must derive from PromiseChainLink");
 #ifdef CONFIG_LIBSSCL_DEBUG_CO
 		std::cout << __func__ << ": " << std::this_thread::get_id() << " Setting callerSchedHandle.\n";
 #endif
@@ -144,6 +145,53 @@ struct ViralSuspendingInvoker
 	}
 };
 
+/**	Non-viral coroutine entry that must not be co_awaited: runs on the caller
+ *	thread (initial_suspend is never) and invokes the completion lambda directly
+ *	from final_suspend (no cross-thread posting).
+ *
+ *	The invoker must outlive the callee frame: do not discard the return object
+ *	from get_return_object(). ~NonPostingInvoker destroys the callee frame.
+ */
+struct NonViralNonPostingInvoker
+:	public NonPostingInvoker<NonPostingPromise>
+{
+	struct promise_type
+	:	public NonPostingPromise
+	{
+		using NonPostingPromise::NonPostingPromise;
+
+		NonViralNonPostingInvoker get_return_object()
+		{
+#ifdef CONFIG_LIBSSCL_DEBUG_CO
+			std::cout << __func__ << ": " << std::this_thread::get_id() << " Returning NonViralNonPostingInvoker.\n";
+#endif
+			if (!this->callerLambda)
+			{
+				std::ostringstream oss;
+				oss << std::this_thread::get_id()
+					<< ": Missing completion lambda: non-viral coroutines require a completion lambda.";
+				throw std::runtime_error(oss.str());
+			}
+
+			this->setSelfSchedHandle(
+				std::coroutine_handle<promise_type>::from_promise(*this));
+
+			return NonViralNonPostingInvoker(*this);
+		}
+	};
+
+	using NonPostingInvoker<NonPostingPromise>::NonPostingInvoker;
+
+	bool await_ready() const noexcept
+		{ std::terminate(); }
+
+	void await_suspend(std::coroutine_handle<NonViralNonPostingInvoker>) noexcept
+		{ std::terminate(); }
+
+	void await_resume() noexcept
+		{ std::terminate(); }
+};
+
 } // namespace sscl::co
 
 #endif // INVOKERS_H
diff --git a/include/spinscale/co/nonPostingInvoker.h b/include/spinscale/co/nonPostingInvoker.h
new file mode 100644
index 0000000..659e64c
--- /dev/null
+++ b/include/spinscale/co/nonPostingInvoker.h
@@ -0,0 +1,63 @@
+#ifndef NON_POSTING_INVOKER_H
+#define NON_POSTING_INVOKER_H
+
+#include <config.h>
+#include <coroutine>
+#include <iostream>
+#include <thread>
+#include <utility>
+
+#include <spinscale/co/nonPostingPromise.h>
+
+namespace sscl::co {
+
+template <typename PromiseType>
+class NonPostingInvoker
+{
+public:
+	explicit NonPostingInvoker(PromiseType &_calleePromise) noexcept
+	: calleePromise(_calleePromise)
+	{}
+
+	NonPostingInvoker(const NonPostingInvoker &) = delete;
+	NonPostingInvoker &operator=(const NonPostingInvoker &) = delete;
+
+	NonPostingInvoker(NonPostingInvoker &&other) noexcept
+	: calleePromise(other.calleePromise),
+	ownsFrameDestroy_(std::exchange(other.ownsFrameDestroy_, false))
+	{}
+
+	NonPostingInvoker &operator=(NonPostingInvoker &&other) = delete;
+
+	~NonPostingInvoker() noexcept
+	{
+		if (!ownsFrameDestroy_) { return; }
+
+		std::coroutine_handle<> handle = calleePromise.selfSchedHandle;
+		if (handle) {
+			handle.destroy();
+		}
+	}
+
+	ReturnValues<void> &completedReturnValues() noexcept
+		{ return calleePromise.returnValues; }
+
+	const ReturnValues<void> &completedReturnValues() const noexcept
+		{ return calleePromise.returnValues; }
+
+private:
+	PromiseType &calleePromise;
+
+	/**	Every live invoker owns destruction of its callee coroutine frame in
+	 *	~NonPostingInvoker (via calleePromise.selfSchedHandle).
+	 *
+	 *	The only time frame destruction is skipped is for a moved-from invoker
+	 *	after move construction, so we do not double-destroy the same handle
+	 *	when get_return_object() returns the invoker by value.
+	 */
+	bool ownsFrameDestroy_ = true;
+};
+
+} // namespace sscl::co
+
+#endif // NON_POSTING_INVOKER_H
diff --git a/include/spinscale/co/nonPostingPromise.h b/include/spinscale/co/nonPostingPromise.h
new file mode 100644
index 0000000..b7c5a7c
--- /dev/null
+++ b/include/spinscale/co/nonPostingPromise.h
@@ -0,0 +1,108 @@
+#ifndef NON_POSTING_PROMISE_H
+#define NON_POSTING_PROMISE_H
+
+#include <config.h>
+#include <coroutine>
+#include <exception>
+#include <functional>
+#include <iostream>
+#include <thread>
+#include <utility>
+
+#include <spinscale/co/coQutex.h>
+#include <spinscale/co/promiseChainLink.h>
+#include <spinscale/co/promises.h>
+
+namespace sscl::co {
+
+struct NonPostingPromise
+:	public PromiseChainLink
+{
+	/**	Completion work must run from this awaiter's await_suspend, not
+	 *	synchronously inside promise.final_suspend() before it returns: the
+	 *	hidden coroutine segment index in the coroutine state is only advanced
+	 *	after final_suspend exits. See docs/prompts/post-to-and-back-in-invokables.md.
+	 */
+	struct FinalSuspendNonPostingInvoker
+	:	public std::suspend_always
+	{
+		explicit FinalSuspendNonPostingInvoker(NonPostingPromise &calleePromiseIn) noexcept
+		:	calleePromise(calleePromiseIn)
+		{}
+
+		bool await_suspend(std::coroutine_handle<> const) noexcept
+		{
+			if (calleePromise.callerLambda)
+			{
+#ifdef CONFIG_LIBSSCL_DEBUG_CO
+				std::cout << "final_suspend" << ": " << std::this_thread::get_id()
+					<< " Non-viral non-posting: invoking callerLambda directly.\n";
+#endif
+				if (calleePromise.returnValues.myExceptionPtr) {
+					std::rethrow_exception(
+						calleePromise.returnValues.myExceptionPtr);
+				}
+
+				calleePromise.callerLambda();
+			}
+			return true;
+		}
+
+		NonPostingPromise &calleePromise;
+	};
+
+	NonPostingPromise() noexcept
+	: returnValues()
+	{}
+
+	template <typename... TailArgs>
+	NonPostingPromise(
+		std::exception_ptr &callerExceptionPtr,
+		std::function<void()> callerLambdaIn,
+		TailArgs &&...) noexcept
+	: returnValues(callerExceptionPtr),
+	callerLambda(std::move(callerLambdaIn))
+	{}
+
+	~NonPostingPromise() noexcept
+	{
+#ifdef CONFIG_LIBSSCL_DEBUG_CO
+		std::cout << __func__ << ": " << std::this_thread::get_id() << " Destructing.\n";
+#endif
+	}
+
+	std::suspend_never initial_suspend() noexcept
+		{ return {}; }
+
+	auto final_suspend() noexcept
+		{ return FinalSuspendNonPostingInvoker(*this); }
+
+	void return_void() noexcept
+		{ return; }
+
+	void unhandled_exception() noexcept
+	{
+		returnValues.myExceptionPtr = std::current_exception();
+	}
+
+	void removeAcquiredLock(CoQutex &coQutex) noexcept override
+	{
+		eraseFirstMatchingAcquiredLock(coQutex);
+	}
+
+	void setSelfSchedHandle(std::coroutine_handle<> schedHandle) noexcept
+	{
+		selfSchedHandle = schedHandle;
+	}
+
+	ReturnValues<void> returnValues;
+	std::function<void()> callerLambda;
+	std::coroutine_handle<> selfSchedHandle;
+
+	template <typename>
+	friend class NonPostingInvoker;
+};
+
+} // namespace sscl::co
+
+#endif // NON_POSTING_PROMISE_H
diff --git a/include/spinscale/puppetApplication.h b/include/spinscale/puppetApplication.h
index f7bf2d9..1644e8a 100644
--- a/include/spinscale/puppetApplication.h
+++ b/include/spinscale/puppetApplication.h
@@ -20,15 +20,15 @@ public:
 
 	// Thread management methods
 	typedef std::function<void()> puppetThreadLifetimeMgmtOpCbFn;
-	void joltAllPuppetThreadsReq(
+	void joltAllPuppetThreadsCReq(
 		cps::Callback<puppetThreadLifetimeMgmtOpCbFn> callback);
-	void startAllPuppetThreadsReq(
+	void startAllPuppetThreadsCReq(
 		cps::Callback<puppetThreadLifetimeMgmtOpCbFn> callback);
-	void pauseAllPuppetThreadsReq(
+	void pauseAllPuppetThreadsCReq(
 		cps::Callback<puppetThreadLifetimeMgmtOpCbFn> callback);
-	void resumeAllPuppetThreadsReq(
+	void resumeAllPuppetThreadsCReq(
 		cps::Callback<puppetThreadLifetimeMgmtOpCbFn> callback);
-	void exitAllPuppetThreadsReq(
+	void exitAllPuppetThreadsCReq(
 		cps::Callback<puppetThreadLifetimeMgmtOpCbFn> callback);
 
 	// CPU distribution method
diff --git a/src/puppetApplication.cpp b/src/puppetApplication.cpp
index d5836eb..9780aa3 100644
--- a/src/puppetApplication.cpp
+++ b/src/puppetApplication.cpp
@@ -72,7 +72,7 @@ public:
 	}
 };
 
-void PuppetApplication::joltAllPuppetThreadsReq(
+void PuppetApplication::joltAllPuppetThreadsCReq(
 	cps::Callback<puppetThreadLifetimeMgmtOpCbFn> callback
 	)
 {
@@ -106,7 +106,7 @@ void PuppetApplication::joltAllPuppetThreadsReq(
 	}
 }
 
-void PuppetApplication::startAllPuppetThreadsReq(
+void PuppetApplication::startAllPuppetThreadsCReq(
 	cps::Callback<puppetThreadLifetimeMgmtOpCbFn> callback
 	)
 {
@@ -130,7 +130,7 @@ void PuppetApplication::startAllPuppetThreadsReq(
 	}
 }
 
-void PuppetApplication::pauseAllPuppetThreadsReq(
+void PuppetApplication::pauseAllPuppetThreadsCReq(
 	cps::Callback<puppetThreadLifetimeMgmtOpCbFn> callback
 	)
 {
@@ -154,7 +154,7 @@ void PuppetApplication::pauseAllPuppetThreadsReq(
 	}
 }
 
-void PuppetApplication::resumeAllPuppetThreadsReq(
+void PuppetApplication::resumeAllPuppetThreadsCReq(
 	cps::Callback<puppetThreadLifetimeMgmtOpCbFn> callback
 	)
 {
@@ -178,7 +178,7 @@ void PuppetApplication::resumeAllPuppetThreadsReq(
 	}
 }
 
-void PuppetApplication::exitAllPuppetThreadsReq(
+void PuppetApplication::exitAllPuppetThreadsCReq(
 	cps::Callback<puppetThreadLifetimeMgmtOpCbFn> callback
 	)
 {