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.
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.
To build and deploy one step by step, see Write a native worker.