Dispatch returns a result envelope

dpm_execute fills a dpm_result on every call: status and error_code
from the module's return value, and a payload the module hands back
through dpm_set_result. The payload's layout belongs to the module and
is documented per command; its release function is carried in the
envelope and invoked by dpm_result_release. The context keeps a stack
of the envelopes in progress, so a module calling a peer receives the
peer's payload in its own envelope and its caller sees only what the
module sets itself.

The good fixture returns a payload and counts its releases, and the
modules test covers the envelope fields, the payload round trip, single
release, discard on a NULL envelope, and a payload set outside any
dispatch. The prose documents describe the envelope and the payload
header a module ships.

tests/CMakeLists.txt

@@ -14,6 +14,10 @@ foreach(fixture good missing_symbols bad_version)
     )
 endforeach()
 
+# The known-good fixture returns a payload through the library, so it
+# links libdpm-core.so the way a module does.
+target_link_libraries(fixture_good PRIVATE dpm-core)
+
 # ---------------------------------------------------------------------
 # API test binaries — one per area of the library, each its own ctest
 # case, so a failure names the area it happened in

tests/fixtures/src/good.cpp

@@ -24,6 +24,23 @@
  */
 #include <cstring>
 
+/* The one library call a module makes to return data, declared here
+   the way the rest of the contract is. */
+extern "C" void dpm_set_result(void* ctx, void* data, void (*release)(void*));
+
+namespace {
+    /* Counts how many times the payload below has been released, so a
+       test can observe the release path. */
+    int releases = 0;
+
+    void release_payload(void* data) {
+        (void)data;
+        releases++;
+    }
+
+    const char* payload = "pong";
+} // namespace
+
 extern "C" const char* dpm_module_version(void) {
     return "1.2.3";
 }
@@ -38,16 +55,23 @@ extern "C" const char* dpm_module_aliases(void) {
     return "goodie, gd";
 }
 
-/* Answers "ping" with 42 so a dispatch round trip is observable, and
-   0 for anything else. */
+/* Answers "ping" with 42 so a dispatch round trip is observable,
+   "payload" with the static payload above, "releases" with the number
+   of times that payload has been released, and 0 for anything else. */
 extern "C" int dpm_module_execute(void* ctx, const char* command,
                                   int argc, char** argv) {
-    (void)ctx;
     (void)argc;
     (void)argv;
 
     if (command && std::strcmp(command, "ping") == 0) {
         return 42;
     }
+    if (command && std::strcmp(command, "payload") == 0) {
+        dpm_set_result(ctx, const_cast<char*>(payload), release_payload);
+        return 0;
+    }
+    if (command && std::strcmp(command, "releases") == 0) {
+        return releases;
+    }
     return 0;
 }

tests/test_modules.cpp

@@ -77,12 +77,64 @@ int main(void) {
 
         /* dispatch returns the module's own value, so a round trip is
            observable with no compile-time knowledge of the module */
-        CHECK(dpm_execute(ctx, good, "ping", 0, nullptr) == 42);
-        CHECK(dpm_execute(ctx, good, "anything_else", 0, nullptr) == 0);
-        CHECK(dpm_execute(ctx, good, nullptr, 0, nullptr) == 0);
+        dpm_result result;
+        CHECK(dpm_execute(ctx, good, "ping", 0, nullptr, &result) == 42);
+        CHECK(result.status == DPM_RESULT_ERROR);
+        CHECK(result.error_code == 42);
+        CHECK(result.data == nullptr);
+        CHECK(result.release == nullptr);
 
-        CHECK(dpm_execute(nullptr, good, "ping", 0, nullptr) == 1);
-        CHECK(dpm_execute(ctx, nullptr, "ping", 0, nullptr) == 1);
+        CHECK(dpm_execute(ctx, good, "anything_else", 0, nullptr, &result) == 0);
+        CHECK(result.status == DPM_RESULT_OK);
+        CHECK(result.error_code == 0);
+        CHECK(result.data == nullptr);
+
+        CHECK(dpm_execute(ctx, good, nullptr, 0, nullptr, &result) == 0);
+        CHECK(result.status == DPM_RESULT_OK);
+
+        CHECK(dpm_execute(nullptr, good, "ping", 0, nullptr, &result) == 1);
+        CHECK(result.status == DPM_RESULT_ERROR);
+        CHECK(dpm_execute(ctx, nullptr, "ping", 0, nullptr, &result) == 1);
+        CHECK(result.status == DPM_RESULT_ERROR);
+    }
+
+    /* ---- a payload reaches the caller and is released once ---- */
+    {
+        dpm_module* good = dpm_require(ctx, "good");
+        CHECK(good != nullptr);
+        if (!good) {
+            dpm_close(ctx);
+            return harness_report("modules");
+        }
+
+        dpm_result result;
+        CHECK(dpm_execute(ctx, good, "payload", 0, nullptr, &result) == 0);
+        CHECK(result.status == DPM_RESULT_OK);
+        CHECK(result.data != nullptr);
+        CHECK(result.release != nullptr);
+        CHECK(result.data != nullptr &&
+              std::strcmp(static_cast<const char*>(result.data), "pong") == 0);
+
+        /* nothing has been released yet */
+        CHECK(dpm_execute(ctx, good, "releases", 0, nullptr, nullptr) == 0);
+
+        dpm_result_release(&result);
+        CHECK(result.data == nullptr);
+        CHECK(result.release == nullptr);
+        CHECK(result.status == DPM_RESULT_OK);
+        CHECK(dpm_execute(ctx, good, "releases", 0, nullptr, nullptr) == 1);
+
+        /* releasing again calls nothing */
+        dpm_result_release(&result);
+        CHECK(dpm_execute(ctx, good, "releases", 0, nullptr, nullptr) == 1);
+
+        /* a NULL envelope discards the payload before dispatch returns */
+        CHECK(dpm_execute(ctx, good, "payload", 0, nullptr, nullptr) == 0);
+        CHECK(dpm_execute(ctx, good, "releases", 0, nullptr, nullptr) == 2);
+
+        /* setting a payload outside any dispatch releases it at once */
+        dpm_set_result(ctx, &result, nullptr);
+        dpm_result_release(nullptr);
     }
 
     dpm_close(ctx);