Module xaynet::sdk::api

A C-API to communicate model updates between a XayNet participant and an application.

Workflow

1. Initialize a Client with new_client(). The Client takes care of the Participant's PET protocol work as well as the networking with the Coordinator.
2. Start the execution of the Client's tasks with run_client().
3. Optionally request status information:
   • is_next_round() indicates if another round of the PET protocol has started.
   • has_next_model() indicates if another global model is available.
   • is_update_participant() indicates if this Participant is eligible to submit a trained local model in the current round.
4. Create a new zero-initialized model with new_model() or get the latest global model with get_model(). Currently, the primitive data types f32, f64, i32 and i64 are supported. The functions return a fat pointer PrimitiveModel to the cached primitive model, whereas the primitive model itself is cached within the Client. The cached primitive model can then be modified in place, for example for training. The slice is valid across the FFI-boundary until one of the following happens:
   • new_model() reallocates the memory to which PrimitiveModel points to.
   • get_model() reallocates the memory to which PrimitiveModel points to if a new global model is available since the last call to get_model().
   • update_model() frees the memory to which PrimitiveModel points to.
   • drop_model() frees the memory to which PrimitiveModel points to.
   • drop_client() frees the memory of the Client including the model.
5. Register the cached model as an updated local model with update_model().
6. Stop and destroy the Client with drop_client().

Safety

Many functions of this module are marked as unsafe to explicitly announce the possible unsafety of the function body as well as the return value to the caller. At the same time, each unsafe fn uses unsafe blocks to precisely pinpoint the sources of unsafety for reviewers (redundancy warnings will be fixed by #69173).

Note, that the unsafe code has not been externally audited yet!

Structs

FFIClient	A wrapper for a Client within an asynchronous runtime.
PrimitiveModel	A fat pointer to a cached model of primitive data type which can be accessed from C.

Functions

drop_client⚠	Stops and destroys a Client and frees its allocated memory.
drop_model⚠	Destroys a Client's cached primitive model and frees its allocated memory.
get_model⚠	Gets a mutable slice PrimitiveModel to the latest global model converted to the primitive data type dtype.
has_next_model⚠	Checks if the next global model is available.
is_next_round⚠	Checks if the next round has started.
is_update_participant⚠	Checks if the current role of the participant is Update.
new_client⚠	Creates a new Client within an asynchronous runtime.
new_model⚠	Gets a mutable slice PrimitiveModel to a zero-initialized model of given primitive data type dtype and length len.
run_client⚠	Starts the Client and executes its tasks in an asynchronous runtime.
update_model⚠	Registers the cached model as an updated local model.