Module host 

A transport the host implements: callbacks that cross the C boundary.

Everything else in this crate drives a transport pamoja wrote. This module goes the other way: the host supplies the functions that connect, send, subscribe, and receive, and pamoja wraps them in a transport that composes like any other, as a ladder rung, under a fault injector, or driven directly. It is how a link pamoja does not ship, a vendor SDK, a proprietary radio, a cloud client, or a class in a language binding, takes its place on a node.

The contract

A host fills a PamojaTransportCallbacks and hands it, with a user_data pointer, to pamoja_transport_from_callbacks. Every callback receives that pointer back. The callbacks are ordinary blocking functions:

• connect, send, and subscribe are called one at a time per transport, from a thread pamoja owns, never the caller’s thread. Each returns PamojaStatus::Ok or a status describing the failure; a host that wants the failure explained sets the text with pamoja_last_error_set on the same thread before returning.
• recv is optional. A link that only sends, an uplink, leaves it null and is never listened on. When present it is called repeatedly from one background thread, from the moment connect succeeds, each call as soon as the previous returned. It blocks until a message is available, builds the message with pamoja_message_new, stores it in out_message, and returns PamojaStatus::Ok; it stores null and returns PamojaStatus::Ok once the link has ended and no further messages will arrive, which stops the calls. A failure status stops them too, and the next receive through pamoja reports that failure, with the text set by pamoja_last_error_set. The next connect starts the calls again. Because it runs on its own thread, it may overlap with the other three callbacks.
• release is optional. It is called once, after the transport is dropped and after every callback still running has returned, so it may free whatever user_data points at.

Messages the host delivers are queued inside the transport, so a receive through pamoja is cancel-safe whatever the host’s recv does.

Structs

CallbackTransport

A transport whose every operation is a host callback.

PamojaTransportCallbacks

The functions a host supplies to stand as a transport.

Functions

pamoja_last_error_set^⚠

Records the text a host callback wants attached to the status it returns.

pamoja_message_new^⚠

Builds a message for a host’s recv callback to deliver.

pamoja_transport_from_callbacks^⚠

Wraps host callbacks in a transport.