NativeDllEngine Workers
The NativeDllEngine loads per-architecture native shared libraries (.so / .dylib / .dll) into the (NativeAOT-compiled) WorkManager.Runtime process that hosts the worker. Workers implement a small C ABI defined in virtufin_worker_api_c.h (ABI v2, or v3 with the worker lifecycle) and exchange CloudEvents with the engine in the worker wire protocol: one protobuf CloudEvent in, one protobuf CloudEventBatch out (CloudEvents Protobuf format, io.cloudevents.v1).
Scope:
NativeDllEngineruns inside the Runtime process. A segfault, illegal instruction, or stack overflow in a native worker terminates that Runtime pod and every worker it hosts. Authors MUST treat the worker as part of the engine's address space — defensive bounds checks, NULL checks, and input validation are required. See Caveats below.
Quick Start
1. Vendor the C headers
# From your native worker project
cp /path/to/workmanager/src/Virtufin.Worker.Host/Schemas/virtufin_worker_api_c.h .
cp /path/to/workmanager/src/Virtufin.Worker.Host/Schemas/virtufin_worker_api_pb.h .
virtufin_worker_api_c.h is the ABI: the VirtufinHost struct, the Process/FreeResult signatures and the status codes. virtufin_worker_api_pb.h is a header-only C99 codec for the two protobuf messages; it needs no protobuf runtime. Both headers also compile as C++. A worker in another language can use any protobuf library with the CloudEvents cloudevents.proto instead of the codec header.
2. Implement the Worker
The worker exports two functions. This one replies to every event with one greeting, under an id derived from the input's and keeping the input's correlationid:
#include <stdint.h>
#include <stdlib.h>
#include <string.h>
#include "virtufin_worker_api_c.h"
#include "virtufin_worker_api_pb.h"
int32_t Process(const VirtufinHost* host,
const uint8_t* in_buf,
int32_t in_len,
uint8_t** out_buf,
int32_t* out_len) {
vf_cloud_event in;
vf_writer reply, batch;
const vf_attr* correlation;
static const char suffix[] = "/reply";
uint8_t* reply_id;
vf_bytes reply_id_bytes;
*out_buf = NULL;
*out_len = 0;
/* 1. Decode the request: views into in_buf, no allocation. */
if (in_len < 0 || vf_decode_cloud_event(in_buf, (size_t)in_len, &in) != VF_OK) {
static const char msg[] = "myworker: malformed CloudEvent";
uint8_t* bytes = malloc(sizeof msg - 1);
if (bytes == NULL) return VIRTUFIN_STATUS_INTERNAL_FAILURE;
memcpy(bytes, msg, sizeof msg - 1);
*out_buf = bytes;
*out_len = sizeof msg - 1;
return VIRTUFIN_STATUS_WORKER_ERROR; /* reported as this event's error */
}
host->log(host->engine_ptr, 2, "myworker: received an event");
/* 2. The output's own id: the input's plus a suffix, never the input's. */
reply_id_bytes.len = in.id.len + sizeof suffix - 1;
reply_id = malloc(reply_id_bytes.len);
if (reply_id == NULL) return VIRTUFIN_STATUS_INTERNAL_FAILURE;
memcpy(reply_id, in.id.ptr, in.id.len);
memcpy(reply_id + in.id.len, suffix, sizeof suffix - 1);
reply_id_bytes.ptr = reply_id;
/* 3. Build the outputs: one vf_writer per event, appended in publish order. */
vf_writer_init(&reply);
vf_writer_init(&batch);
vf_event_core(&reply, reply_id_bytes, VF_STR("urn:com.example.myworker"), VF_STR("com.example.myworker.reply"));
free(reply_id); /* the writer copied it */
vf_event_attr_string(&reply, VF_STR("inputid"), in.id);
vf_event_attr_string(&reply, VF_STR("datacontenttype"), VF_STR("application/json"));
correlation = vf_find_attr(&in, "correlationid");
if (correlation != NULL) vf_event_attr(&reply, correlation);
vf_event_text_data(&reply, VF_STR("{\"greeting\":\"hello\"}"));
vf_batch_add(&batch, &reply);
vf_writer_free(&reply);
if (batch.failed) {
vf_writer_free(&batch);
return VIRTUFIN_STATUS_INTERNAL_FAILURE;
}
/* 4. Hand the malloc()ed batch to the engine; it calls FreeResult. */
*out_buf = batch.buf;
*out_len = (int32_t)batch.len;
return VIRTUFIN_STATUS_OK;
}
void FreeResult(uint8_t* result) {
free(result);
}
Every output needs an id of its own, derived from the input's (here the input's id plus /reply, with the input's id in inputid), so a second delivery of the input produces the same output ids again. An output must not reuse its input's id: a pub/sub broker that drops duplicates by event id takes it for a second copy of the input and drops it, while the publish still reports success. NATS JetStream does this across every topic of a stream, for as long as the stream's duplicate window.
No output is an empty batch, which encodes to zero bytes: return VIRTUFIN_STATUS_OK with *out_buf = NULL. Several outputs are several vf_batch_add calls; the Runtime publishes them in order, each to its own publishtopic (else its ce-type). The complete example is examples/native-worker-c/hello.c.
3. Add a <virtufin*> extension to the nuspec
The engine reads Virtufin-specific metadata from virtufin* elements in the worker's .nuspec (lives inside <metadata>):
<?xml version="1.0" encoding="utf-8"?>
<package xmlns="http://schemas.microsoft.com/packaging/2013/05/nuspec.xsd">
<metadata>
<id>Virtufin.Worker.MyWorker</id>
<version>0.0.1</version>
<authors>...</authors>
<description>...</description>
<!-- Virtufin extensions (all optional; defaults shown). -->
<virtufinAbiVersion>2</virtufinAbiVersion>
<virtufinEntryPoint>Process</virtufinEntryPoint>
<virtufinFreeResult>FreeResult</virtufinFreeResult>
<virtufinLibrary>myworker</virtufinLibrary>
</metadata>
</package>
| Element | Required | Default | Notes |
|---|---|---|---|
<id> |
yes | — | Standard NuGet id. Used as fallback for virtufinLibrary. |
<version> |
yes | — | Standard NuGet version. Informational. |
virtufinAbiVersion |
no | 2 |
Integer. The engine supports { 2 }; any other value is rejected at load. |
virtufinLibrary |
no | <id> |
Library basename (no extension, no lib prefix). Must match [A-Za-z0-9_.-]+, no .., length ≤ 128. |
virtufinEntryPoint |
no | Process |
The name of the exported function the engine calls. |
virtufinFreeResult |
no | FreeResult |
The name of the exported function that releases the result buffer. |
4. Build per-architecture
The worker nupkg follows the standard NuGet convention: runtimes/<rid>/native/<file>. Supported RIDs in v1 are linux-x64 and linux-arm64. The engine looks up the entry whose RID matches RuntimeInformation.RuntimeIdentifier of the running process.
worker.nupkg/
├── Virtufin.Worker.MyWorker.nuspec
└── runtimes/
└── linux-x64/
└── native/
└── libmyworker.so
Build script (Linux x86_64 example, pure-C worker):
#!/usr/bin/env bash
set -euo pipefail
RID="${1:-linux-x64}"
OUT="runtimes/${RID}/native"
mkdir -p "${OUT}"
cc -std=c99 -O2 -fPIC -shared \
-I. \
-o "${OUT}/libmyworker.so" \
myworker.c
# Package as a nupkg. -j flattens the .nuspec into the zip root;
# -r packages the runtimes/ tree recursively.
rm -f worker.nupkg
zip -j worker.nupkg Virtufin.Worker.MyWorker.nuspec >/dev/null
( cd runtimes && zip -r ../worker.nupkg . >/dev/null )
For Windows and macOS support, change the file extension to .dll and .dylib respectively. The engine's LibraryName.BuildFileName derives the right filename per platform.
5. Deploy
Create the worker with mime type application/x-native-dll, inline or from a
URL (see the API reference), e.g. with grpcurl:
grpcurl -plaintext -d "{
\"mime_type\": \"application/x-native-dll\",
\"topics\": [\"commands.myworker\"],
\"code_source\": {\"content\": \"$(base64 -i worker.nupkg)\"}
}" localhost:5002 virtufin.WorkManager/CreateWorker
grpcurl -plaintext -d '{"id": "<worker id>"}' localhost:5002 virtufin.WorkManager/StartWorker
Discovery
The engine loads the worker's library via NativeLibrary.Load and resolves two exports via NativeLibrary.GetExport:
entry_point(defaultProcess) — invoked once per CloudEvent the engine delivers to the worker.free_result(defaultFreeResult) — invoked exactly once perProcesscall that returned a non-null*out_buf, whatever the status.
A worker is considered "found" if both exports resolve; otherwise the engine refuses the load with a clear error.
The C ABI
Process function
int32_t Process(const VirtufinHost* host,
const uint8_t* in_buf,
int32_t in_len,
uint8_t** out_buf,
int32_t* out_len);
| Parameter | Direction | Notes |
|---|---|---|
host |
in | Opaque pointer to a VirtufinHost* struct. Always non-null. See below. |
in_buf |
in | One protobuf CloudEvent (io.cloudevents.v1). Length in in_len. |
in_len |
in | Byte length of in_buf. |
out_buf |
out | A buffer the worker allocated via malloc (or compatible): the CloudEventBatch on status 0, the error message on status 1. May be NULL (an empty batch, or status 2). |
out_len |
out | Byte length of *out_buf. |
Return value:
| Status | Constant | *out_buf |
Engine behavior |
|---|---|---|---|
0 |
VIRTUFIN_STATUS_OK |
protobuf CloudEventBatch (zero bytes = empty) |
Publishes every event, in order. |
1 |
VIRTUFIN_STATUS_WORKER_ERROR |
UTF-8 error message (not NUL-terminated) | Throws InvalidOperationException(message); the event fails like any worker error. |
2 |
VIRTUFIN_STATUS_INTERNAL_FAILURE |
may be NULL | Throws InvalidWorkerResponseException. |
Any other value is treated like 2.
FreeResult function
void FreeResult(uint8_t* result);
Releases a buffer previously returned by Process via *out_buf. The engine calls this exactly once per non-null *out_buf, whatever Process returned. The worker MUST use the same allocator (malloc) that this function releases (free).
VirtufinHost struct
typedef struct VirtufinHost {
void* engine_ptr; // opaque GCHandle to the engine
int32_t abi_version; // VIRTUFIN_ABI_VERSION (3)
void (*log)(void*, int32_t, const char*);
int32_t (*gateway_call)(void*, const char*, const char*,
const uint8_t*, int32_t,
uint8_t**, int32_t*);
void (*free_response)(void*, uint8_t*);
/* ABI v3 */
int32_t (*publish)(void*, const uint8_t*, int32_t);
int32_t (*report_status)(void*, const uint8_t*, int32_t,
const uint8_t*, int32_t);
} VirtufinHost;
| Field | Type | Purpose |
|---|---|---|
engine_ptr |
opaque | Workers MUST NOT dereference this. It's an opaque handle for the engine's use. |
abi_version |
int32 | 3 (the host's version). Workers may branch on this for forward-compat; a v2 worker reads only the fields up to free_response. |
log |
fn | Structured logging callback. level: 0=trace, 1=debug, 2=info, 3=warn, 4=error. message is a NUL-terminated UTF-8 string valid for the duration of the call. |
gateway_call |
fn | Call a virtufin-api Gateway service. Returns 0 on success; engine-allocated response is freed by free_response. |
free_response |
fn | Releases a buffer returned by gateway_call. |
publish |
fn | v3: publish a protobuf CloudEventBatch through the host (its outbox and ownership gate), each event routed like a returned output. Returns VIRTUFIN_PUBLISH_OK (0), VIRTUFIN_PUBLISH_REFUSED (1: not started, stopping, no longer owned) or VIRTUFIN_PUBLISH_FAILED (-1). |
report_status |
fn | v3: report the worker's health (state, detail as UTF-8 bytes; detail may be NULL). Returns 0 on success. |
The struct layout is 56 bytes on 64-bit platforms (void* = 8, int32_t = 4 padded to 8, five function pointers = 40); the v3 fields come after everything a v2 worker reads. On 32-bit platforms the layout differs and is not currently supported.
Lifecycle (ABI v3)
A library whose nuspec declares <virtufinAbiVersion>3</virtufinAbiVersion> must also export:
int32_t Start(const VirtufinHost* host, const uint8_t* ctx_buf, int32_t ctx_len,
uint8_t** out_buf, int32_t* out_len);
int32_t Stop(const VirtufinHost* host, int32_t budget_ms);
Startis called once per activation, before the firstProcess, withctx_buf= UTF-8 JSON{"workerId": "...", "config": {...}, "secrets": {...}}(config and secrets may be absent). It returns when the worker runs; a long-running loop is the worker's own thread. On failure it returnsVIRTUFIN_STATUS_WORKER_ERRORwith a UTF-8 message in*out_buf, released withFreeResult.- From
StartuntilStopreturns, the worker may callhost->publishandhost->report_statusfrom any thread. The host pointer stays valid for that time. Stopmeans "the host no longer owns you" (stopped, reloaded, deleted, its lease lost): publish nothing more, release everything, return withinbudget_ms.Processis never called after it; a publish from then on is refused. A laterStartis a new activation.- The engine rejects a v3 nuspec whose library lacks either export. A v2 library keeps working and gets no lifecycle calls.
A C# NativeAOT worker gets this from AotNative<W>: declare Start/Stop exports delegating to AotNative<W>.StartStatic/StopStatic and set VirtufinWorkerAbiVersion to 3; the worker's IWorkerContext then publishes and reports through the host vtable.
Wire format
Both buffers are CloudEvents Protobuf (io.cloudevents.v1), the same encoding every other hop of the worker wire protocol uses (WorkManager → Runtime actor, subprocess engines, DotNetDll bridge):
- Request: one
CloudEvent.id,source,spec_versionandtypeare message fields. Every other attribute (datacontenttype,dataschema,subject,time, extensions such ascorrelationidorpublishtopic) is an entry of theattributesmap, typed by itsCloudEventAttributeValuekind (ce_string,ce_integer,ce_boolean,ce_timestamp,ce_bytes,ce_uri,ce_uri_ref). Data istext_datafor text (JSON included) orbinary_datafor bytes (e.g. an order book image), never base64. - Response: one
CloudEventBatch(repeated CloudEvent events = 1), in publish order. An output withouttypeand without apublishtopicattribute is not published.
Errors never travel inside a CloudEvent: they are the status code.
Caveats
Crash isolation
A native worker runs in the same address space as the AOT-compiled WorkManager.Runtime process hosting it. An unrecoverable native fault (segfault, illegal instruction, stack overflow) terminates that Runtime pod, with every worker it hosts, — there is no managed try/catch that can rescue such a fault.
| Engine | Crash isolation |
|---|---|
PythonEngine |
Process boundary (subprocess) |
DotNetDllEngine |
Assembly only (AssemblyLoadContext) — shares the Runtime process |
CSharpSourceEngine |
Process boundary (CSharpSource.Bridge subprocess) |
NativeDllEngine |
None — shares the Runtime process |
Author defensively: bounds-check every input length, validate pointers, prefer malloc-family allocation that the engine can free, and unit-test your worker against malformed inputs.
NativeAOT libraries are never unloaded
A worker built with .NET NativeAOT (e.g. AotNative<W>) embeds its own .NET runtime, whose threads keep running in the library's code. Unloading it (dlclose) segfaults the process, so the engine never unloads a library that exports DotNetRuntimeDebugHeader (every NativeAOT shared library does): deleting or reloading such a worker leaves its library mapped until the Runtime pod restarts (~25 MB per load for HttpGet). Plain C/C++/Rust libraries are unloaded as before.
Unmanaged timeout
The engine checks the call's CancellationToken only before it calls Process; cancellation does not interrupt native code, and no lifecycle event reports a hung call. A hung Process blocks that worker's message processing until it returns or the process crashes.
Workers that may run for a long time should bound their own work (e.g. a watchdog thread setting a "should stop" flag the worker polls) so that Process always returns.
ABI version policy
The engine accepts workers declaring an ABI version in VirtufinWorkerNuspec.SupportedAbiVersions (currently { 2, 3 }) and refuses any other at load, with an error naming the supported set. v3 is v2 plus the lifecycle; a nupkg without the element is v2. ABI v1 (FlatBuffers WorkerResponse) was removed in WorkManager 0.28.0 without a transition release; rebuild v1 workers against the v2 headers.
Performance
| Phase | Duration (typical) |
|---|---|
First LoadCodeAsync (per-RID library resolve + dlopen) |
~10 ms |
Per-message ProcessAsync (protobuf encode + native call + decode) |
~50-200 µs |
DisposeAsync (library unload, except NativeAOT libraries + host struct free + temp file delete) |
~5 ms |
Compared to DotNetDllEngine, NativeDllEngine has the same isolation profile (shares the Runtime process) and trades a per-message protobuf round-trip for no JIT startup cost. Compared to CSharpSourceEngine, NativeDllEngine skips Roslyn compilation at load time (the library is pre-compiled) but adds a per-message protobuf round-trip.
Debugging
- The engine logs each
LoadCodeAsyncandDisposeAsyncat info level with the resolved entry path, library basename, and ABI version. - Native worker logs flow through the engine's
Logcallback and appear in the WorkManager log as[Information] Native worker: <message>or[Warning] / [Error]depending on the worker's chosen level. - Set
Logging:LogLevel:Virtufin.WorkManager.Engine.NativeDlltoDebugto see the per-call host callback invocations.
CI Notes
The engine's integration test (Virtufin.WorkManager.Engine.NativeDll.Tests) builds a small C shim (Resources/echo_worker.c → libecho_worker.dylib/.so, against virtufin_worker_api_pb.h) via a BeforeTargets="Build" target that invokes Resources/build_echo_worker.sh. The script is a no-op when cc is not on PATH, so CI runners without a C compiler build the test project without the shim, and the tests that need it skip ([NativeToolchainFact]). Local macOS dev builds have cc via xcode-select and run the script normally. To force the shim build off in any environment, pass -p:BuildEchoWorkerShim=false to dotnet build.