quepaxa_ffi/lib.rs
1//! Stable C ABI over the [`quepaxa`] consensus core, for C, C++, Go, Swift, Kotlin/JNI,
2//! Python (ctypes/cffi) or any language that can call C.
3//!
4//! The ABI exposes the same sans-IO [`quepaxa::Replica`]: your program feeds it events and
5//! carries out the actions it returns. Read [`quepaxa::guide::driving`] for the model; this
6//! page covers what is specific to C.
7//!
8//! # Getting the library
9//!
10//! - **Prebuilt:** every GitHub release attaches `quepaxa-ffi-<version>-<target>` archives
11//! with `include/quepaxa.h` and the static and shared libraries for Linux (x86_64,
12//! aarch64; glibc 2.28+), macOS (x86_64, arm64), Windows (x64, arm64, MSVC), Android
13//! (`jniLibs` for four ABIs, 16 KB pages) and iOS (an XCFramework).
14//! - **From source:** `cargo build --release -p quepaxa-ffi` produces
15//! `libquepaxa_ffi.a` / `.so` / `.dylib` (or `quepaxa_ffi.lib` / `.dll`) in
16//! `target/release`; the header is `crates/quepaxa-ffi/include/quepaxa.h`.
17//! - **Linking statically** on Linux also needs `-lpthread -ldl -lm`.
18//!
19//! # The loop in C
20//!
21//! ```c
22//! #include "quepaxa.h"
23//!
24//! uint32_t members[3] = {0, 1, 2};
25//! uint8_t seed[32];
26//! fill_with_csprng(seed, sizeof seed); /* fresh on every start */
27//! qpx_config *cfg;
28//! check(qpx_config_new((const uint8_t *)"my-cluster-0001!", 0, members, 3, seed, &cfg));
29//! check(qpx_config_set(cfg, QPX_CONFIG_MAX_IN_FLIGHT_SLOTS, 32)); /* optional settings */
30//!
31//! qpx_replica *r;
32//! check(qpx_replica_new(cfg, records, n_records, now_ns(), &r)); /* durable records, in order */
33//! qpx_config_free(cfg); /* the replica keeps its own copy */
34//!
35//! for (;;) { /* after every call: drain */
36//! qpx_action a;
37//! int32_t rc = qpx_poll(r, &a);
38//! if (rc == QPX_EMPTY) break;
39//! switch (a.kind) {
40//! case QPX_ACTION_PERSIST: /* qpx_action_record(r, k, ...) for k < a.count: append + fsync, */
41//! /* then send qpx_action_then(r, k, ...) for k < a.then_count, */
42//! /* then, after draining, qpx_persisted(r, now, a.id) */
43//! case QPX_ACTION_SEND: /* send a.bytes to a.peer */
44//! case QPX_ACTION_COMMIT: /* apply qpx_action_entry(r, k, ...) for k < a.count, slot a.slot */
45//! case QPX_ACTION_COMMITTED: /* answer the client of proposal a.id */
46//! default: break; /* new kinds may appear in minor versions */
47//! }
48//! }
49//! uint64_t deadline;
50//! if (qpx_next_deadline(r, &deadline) == QPX_OK) { /* arm a timer; then qpx_handle_timeout */ }
51//! ```
52//!
53//! `examples/smoke.c` in the crate is a complete three-replica program; CI runs it on Linux,
54//! macOS, Windows, an Android emulator and an iOS simulator.
55//!
56//! # Contract
57//!
58//! (Also stated in `include/quepaxa.h`.)
59//!
60//! - Every function returns a `QPX_*` status (`0` = ok, positive = informational,
61//! negative = error) unless stated otherwise. [`qpx_status_str`] names it and
62//! [`qpx_last_error`] describes the most recent failing call on the calling thread.
63//! - **Draining:** after any mutating call, call [`qpx_poll`] until it returns
64//! `QPX_EMPTY` before the next mutating call (`QPX_ERR_NOT_DRAINED` otherwise).
65//! `qpx_persisted` is itself a mutating call: collect persist ids while draining and
66//! acknowledge the highest one afterwards (it covers every earlier persist).
67//! - **Persist before send:** never send a persist's `then` messages before its records
68//! are durable.
69//! - **Borrowed memory:** `qpx_bytes` returned by [`qpx_poll`] and the `qpx_action_*`
70//! accessors borrow from the handle and stay valid until the next call on that handle;
71//! copy what you keep. Inputs are copied by the library; you keep ownership.
72//! - **Threads:** a handle may move between threads, but calls on one handle must not
73//! overlap. Different handles are independent.
74//! - **Panics** never cross the boundary: a panic inside the library returns
75//! `QPX_ERR_PANIC` and poisons the handle; every later call on it returns
76//! `QPX_ERR_POISONED`. Free it with [`qpx_replica_free`].
77//!
78//! # Versioning
79//!
80//! [`qpx_abi_version`] returns `(major << 16) | minor`; compare it with
81//! `QPX_ABI_VERSION_MAJOR`/`MINOR` from the header you compiled against. Settings and
82//! metrics are not structs: the configuration is an opaque object set option by option
83//! ([`qpx_config_set`]) and metrics are read one by one ([`qpx_metric`]), so a new one is a
84//! new constant, and an option or metric the library does not know is an explicit
85//! `QPX_ERR_INVALID_ARGUMENT`. The only structs are outputs with a fixed layout (`qpx_bytes`,
86//! `qpx_action`, `qpx_entry`). Before 1.0 a minor ABI bump may be incompatible; the
87//! changelog says when.
88#![expect(non_camel_case_types)]
89// C naming for exported types
90// Panics across the C ABI are caught, but production code should not rely on that.
91#![cfg_attr(not(test), deny(clippy::unwrap_used, clippy::expect_used, clippy::panic))]
92
93use std::cell::RefCell;
94use std::collections::VecDeque;
95use std::panic::{AssertUnwindSafe, catch_unwind};
96use std::{ptr, slice};
97
98use bytes::Bytes;
99use quepaxa::{Action, Error, Input, NodeId, PersistId, Replica, Slot, Timestamp};
100
101mod actions;
102mod config;
103
104pub use actions::*;
105pub use config::*;
106
107/// ABI major version: incompatible changes bump it. While it is 0 the ABI is unstable and
108/// every minor bump may be incompatible.
109pub const QPX_ABI_VERSION_MAJOR: u32 = 0;
110/// ABI minor version: additive changes bump it (any change while the major is 0).
111/// 0.2: `qpx_install_snapshot` may return `QPX_IGNORED`.
112/// 0.3: size-aware `qpx_config_init`, `qpx_get_metrics`, `qpx_last_error`, strict draining.
113/// 0.4: `qpx_config.leader_order` (appended; older layouts keep the default order).
114/// 0.5: membership changes: `qpx_propose_reconfiguration`, `QPX_ACTION_RECONFIGURED`,
115/// `qpx_action_member`, `QPX_ERR_RECONFIGURATION_PENDING`.
116/// 0.6: `QPX_ACTION_RETIRED`.
117/// 0.7: opaque `qpx_config` (`qpx_config_new`, `qpx_config_set`, `qpx_config_set_leader_order`,
118/// `qpx_config_free`) and `qpx_metric` replace the `qpx_config` and `qpx_metrics` structs,
119/// `qpx_config_init` and `qpx_get_metrics` (incompatible).
120/// 0.8: `QPX_ERR_REQUEST_ID_EXHAUSTED`; read ids use a separate range;
121/// `QPX_METRIC_STEPPED_ASIDE`.
122/// 0.9: `QPX_DROP_SUPERSEDED`, `QPX_DROP_UNRESOLVED`.
123/// 0.10: leader placement: `QPX_CONFIG_PLACEMENT*`, `QPX_METRIC_SUSPICIONS`,
124/// `QPX_METRIC_PLACEMENT_MOVES`, `QPX_METRIC_EPOCH`, `QPX_METRIC_LEADER_POSITION`.
125pub const QPX_ABI_VERSION_MINOR: u32 = 10;
126
127/// Success.
128pub const QPX_OK: i32 = 0;
129/// No action, deadline or value to report.
130pub const QPX_EMPTY: i32 = 1;
131/// The output buffer is too small; the required length was written.
132pub const QPX_BUFFER_TOO_SMALL: i32 = 2;
133/// The call had no effect: the snapshot is older than what the replica already emitted.
134pub const QPX_IGNORED: i32 = 3;
135/// A null pointer, unknown option or metric, out-of-range value or index.
136pub const QPX_ERR_INVALID_ARGUMENT: i32 = -1;
137/// The configuration is invalid.
138pub const QPX_ERR_INVALID_CONFIG: i32 = -2;
139/// A durable record passed to `qpx_replica_new` is corrupt.
140pub const QPX_ERR_CORRUPT_RECORD: i32 = -3;
141/// Too many outstanding proposals.
142pub const QPX_ERR_BUSY: i32 = -4;
143/// The payload does not fit in one batch.
144pub const QPX_ERR_PAYLOAD_TOO_LARGE: i32 = -5;
145/// The replica fenced itself after a storage failure.
146pub const QPX_ERR_FENCED: i32 = -6;
147/// Actions from the previous call were not drained.
148pub const QPX_ERR_NOT_DRAINED: i32 = -7;
149/// Unknown or repeated persist id.
150pub const QPX_ERR_UNKNOWN_PERSIST_ID: i32 = -8;
151/// Malformed core state for `qpx_compact` / `qpx_install_snapshot`.
152pub const QPX_ERR_INVALID_CORE_STATE: i32 = -9;
153/// A membership change has not taken effect yet (ABI 0.5).
154pub const QPX_ERR_RECONFIGURATION_PENDING: i32 = -10;
155/// Request ids exhausted in this incarnation; restart from durable records (ABI 0.8).
156pub const QPX_ERR_REQUEST_ID_EXHAUSTED: i32 = -11;
157/// The library panicked; the handle is now poisoned.
158pub const QPX_ERR_PANIC: i32 = -100;
159/// The handle panicked earlier and is unusable.
160pub const QPX_ERR_POISONED: i32 = -101;
161
162/// Append `records` durably after earlier persists, then send each `then` message, then
163/// call `qpx_persisted(id)`. If `QPX_PERSIST_REPLACE` is set in `flags`, atomically
164/// replace all earlier records instead of appending.
165pub const QPX_ACTION_PERSIST: u32 = 1;
166/// Send `bytes` to `peer`.
167pub const QPX_ACTION_SEND: u32 = 2;
168/// Apply the `count` entries of `slot` (read them with `qpx_action_entry`).
169pub const QPX_ACTION_COMMIT: u32 = 3;
170/// Local proposal `id` committed at or before `slot`.
171pub const QPX_ACTION_COMMITTED: u32 = 4;
172/// Read barrier `id` is ready once commits up to `slot` are applied.
173pub const QPX_ACTION_READ_READY: u32 = 5;
174/// Fetch `peer`'s application snapshot covering `slot` and call `qpx_install_snapshot`.
175pub const QPX_ACTION_SNAPSHOT_NEEDED: u32 = 6;
176/// Local proposal `id` will not be reported again (`flags` = `QPX_DROP_*`). With
177/// `QPX_DROP_FENCED` the outcome is unknown: it may still commit, as after a crash.
178pub const QPX_ACTION_DROPPED: u32 = 7;
179/// A membership change was applied: from slot `slot`, the `count` members (read them with
180/// `qpx_action_member`, preferred leaders first) form epoch `id` (ABI 0.5).
181pub const QPX_ACTION_RECONFIGURED: u32 = 8;
182/// This replica is not a member of epoch `id`, and a majority of that epoch's members
183/// durably know every slot before it: it may shut down, unless a later change added it
184/// back (ABI 0.6).
185pub const QPX_ACTION_RETIRED: u32 = 9;
186
187/// `flags` bit of `QPX_ACTION_PERSIST`: replace all earlier records.
188pub const QPX_PERSIST_REPLACE: u32 = 1;
189/// `flags` of `QPX_ACTION_DROPPED`: the replica is fenced (outcome unknown).
190pub const QPX_DROP_FENCED: u32 = 1;
191/// `flags` of `QPX_ACTION_DROPPED`: a membership change was decided but ignored, because
192/// another change or a rotation came first. Nothing changed (ABI 0.9).
193pub const QPX_DROP_SUPERSEDED: u32 = 2;
194/// `flags` of `QPX_ACTION_DROPPED`: a membership change was decided, but an installed
195/// snapshot hid whether it was applied; check the members in force (ABI 0.9).
196pub const QPX_DROP_UNRESOLVED: u32 = 3;
197
198/// A borrowed byte range. `ptr` may be null when `len` is 0.
199#[repr(C)]
200#[derive(Clone, Copy)]
201pub struct qpx_bytes {
202 /// First byte.
203 pub ptr: *const u8,
204 /// Length in bytes.
205 pub len: usize,
206}
207
208impl qpx_bytes {
209 const EMPTY: Self = Self { ptr: ptr::null(), len: 0 };
210
211 fn of(b: &[u8]) -> Self {
212 Self { ptr: b.as_ptr(), len: b.len() }
213 }
214}
215
216/// An opaque replica handle.
217pub struct qpx_replica {
218 replica: Replica,
219 queue: VecDeque<Action>,
220 current: Option<Action>,
221 /// `qpx_poll` returned `QPX_EMPTY` since the last mutating call.
222 drained: bool,
223 poisoned: bool,
224}
225
226thread_local! {
227 static LAST_ERROR: RefCell<String> = const { RefCell::new(String::new()) };
228}
229
230/// An argument check failed before the call reached the replica.
231fn invalid() -> i32 {
232 set_last_error("invalid argument: null pointer or out-of-range index");
233 QPX_ERR_INVALID_ARGUMENT
234}
235
236fn set_last_error(msg: &str) {
237 // `try_with`: a call from a TLS destructor after ours ran loses the message, not the
238 // process (a panic here would unwind across the C boundary).
239 let _ = LAST_ERROR.try_with(|e| msg.clone_into(&mut e.borrow_mut()));
240}
241
242/// Records a failing status's description unless a more specific one was set.
243fn note(rc: i32) -> i32 {
244 if rc < 0 {
245 let _ = LAST_ERROR.try_with(|e| {
246 if e.borrow().is_empty() {
247 // SAFETY: `qpx_status_str` returns a static NUL-terminated string.
248 let s = unsafe { std::ffi::CStr::from_ptr(qpx_status_str(rc)) };
249 *e.borrow_mut() = s.to_string_lossy().into_owned();
250 }
251 });
252 }
253 rc
254}
255
256impl qpx_replica {
257 fn pull(&mut self) {
258 let mut out = Vec::new();
259 self.replica.poll_actions(&mut out);
260 self.queue.extend(out);
261 }
262}
263
264fn code(e: Error) -> i32 {
265 set_last_error(&e.to_string());
266 match e {
267 Error::InvalidConfig(_) => QPX_ERR_INVALID_CONFIG,
268 Error::CorruptRecord { .. } => QPX_ERR_CORRUPT_RECORD,
269 Error::Busy => QPX_ERR_BUSY,
270 Error::PayloadTooLarge => QPX_ERR_PAYLOAD_TOO_LARGE,
271 Error::Fenced => QPX_ERR_FENCED,
272 Error::NotDrained => QPX_ERR_NOT_DRAINED,
273 Error::UnknownPersistId => QPX_ERR_UNKNOWN_PERSIST_ID,
274 Error::InvalidCoreState => QPX_ERR_INVALID_CORE_STATE,
275 Error::ReconfigurationPending => QPX_ERR_RECONFIGURATION_PENDING,
276 Error::RequestIdExhausted => QPX_ERR_REQUEST_ID_EXHAUSTED,
277 _ => QPX_ERR_INVALID_ARGUMENT,
278 }
279}
280
281/// Runs `f` on a live handle, converting panics and poisoning.
282fn with(h: *mut qpx_replica, f: impl FnOnce(&mut qpx_replica) -> i32) -> i32 {
283 set_last_error("");
284 note(with_inner(h, f))
285}
286
287fn with_inner(h: *mut qpx_replica, f: impl FnOnce(&mut qpx_replica) -> i32) -> i32 {
288 // SAFETY: the caller passes a handle from `qpx_replica_new` that is not used concurrently.
289 let Some(h) = (unsafe { h.as_mut() }) else { return invalid() };
290 if h.poisoned {
291 return QPX_ERR_POISONED;
292 }
293 match catch_unwind(AssertUnwindSafe(|| f(h))) {
294 Ok(rc) => rc,
295 Err(_) => {
296 h.poisoned = true;
297 QPX_ERR_PANIC
298 }
299 }
300}
301
302/// A mutating call: refuses while actions are undrained, then queues new actions.
303fn mutate(h: *mut qpx_replica, f: impl FnOnce(&mut Replica) -> Result<(), Error>) -> i32 {
304 with(h, |h| {
305 if !h.drained {
306 return QPX_ERR_NOT_DRAINED;
307 }
308 h.current = None;
309 let rc = match f(&mut h.replica) {
310 Ok(()) => QPX_OK,
311 Err(e) => code(e),
312 };
313 h.pull();
314 // Nothing new to take means nothing to drain.
315 h.drained = h.queue.is_empty();
316 rc
317 })
318}
319
320/// # Safety
321/// `ptr` must point to `len` readable bytes (or `len` must be 0).
322unsafe fn bytes_from(ptr: *const u8, len: usize) -> Option<Bytes> {
323 if len == 0 {
324 return Some(Bytes::new());
325 }
326 if ptr.is_null() {
327 return None;
328 }
329 // SAFETY: guaranteed by the caller.
330 Some(Bytes::copy_from_slice(unsafe { slice::from_raw_parts(ptr, len) }))
331}
332
333/// `(major << 16) | minor`.
334#[unsafe(no_mangle)]
335pub extern "C" fn qpx_abi_version() -> u32 {
336 (QPX_ABI_VERSION_MAJOR << 16) | QPX_ABI_VERSION_MINOR
337}
338
339/// Static, NUL-terminated description of a status code.
340#[unsafe(no_mangle)]
341pub extern "C" fn qpx_status_str(status: i32) -> *const std::ffi::c_char {
342 let s: &'static [u8] = match status {
343 QPX_OK => b"ok\0",
344 QPX_EMPTY => b"empty\0",
345 QPX_BUFFER_TOO_SMALL => b"buffer too small\0",
346 QPX_IGNORED => b"ignored: snapshot older than the emitted prefix\0",
347 QPX_ERR_INVALID_ARGUMENT => b"invalid argument\0",
348 QPX_ERR_INVALID_CONFIG => b"invalid config\0",
349 QPX_ERR_CORRUPT_RECORD => b"corrupt durable record\0",
350 QPX_ERR_BUSY => b"too many outstanding proposals\0",
351 QPX_ERR_PAYLOAD_TOO_LARGE => b"payload too large\0",
352 QPX_ERR_FENCED => b"replica fenced after a storage failure\0",
353 QPX_ERR_NOT_DRAINED => b"actions not drained\0",
354 QPX_ERR_UNKNOWN_PERSIST_ID => b"unknown persist id\0",
355 QPX_ERR_INVALID_CORE_STATE => b"invalid core state\0",
356 QPX_ERR_RECONFIGURATION_PENDING => b"a membership change has not taken effect yet\0",
357 QPX_ERR_REQUEST_ID_EXHAUSTED => b"request id space exhausted; restart from durable records\0",
358 QPX_ERR_PANIC => b"internal panic; handle poisoned\0",
359 QPX_ERR_POISONED => b"handle poisoned by an earlier panic\0",
360 _ => b"unknown status\0",
361 };
362 s.as_ptr().cast()
363}
364
365/// Creates a replica with configuration `cfg` (copied; free it whenever) from
366/// `n_records` durable records (in persisted order).
367///
368/// # Safety
369/// `cfg` must come from `qpx_config_new`; `records` must point to `n_records` valid
370/// `qpx_bytes`; `out` must be writable. On success `*out` owns a handle to release with `qpx_replica_free`.
371#[unsafe(no_mangle)]
372pub unsafe extern "C" fn qpx_replica_new(
373 cfg: *const qpx_config,
374 records: *const qpx_bytes,
375 n_records: usize,
376 now_ns: u64,
377 out: *mut *mut qpx_replica,
378) -> i32 {
379 set_last_error("");
380 let result = catch_unwind(|| {
381 if out.is_null() {
382 return invalid();
383 }
384 // SAFETY: guaranteed by the caller.
385 let Some(cfg) = (unsafe { cfg.as_ref() }) else { return invalid() };
386 let config = cfg.config.clone();
387 let raw: &[qpx_bytes] = if n_records == 0 {
388 &[]
389 } else if records.is_null() {
390 return invalid();
391 } else {
392 // SAFETY: guaranteed by the caller.
393 unsafe { slice::from_raw_parts(records, n_records) }
394 };
395 let mut durable = Vec::with_capacity(raw.len());
396 for r in raw {
397 // SAFETY: guaranteed by the caller.
398 let Some(b) = (unsafe { bytes_from(r.ptr, r.len) }) else { return invalid() };
399 durable.push(b);
400 }
401 match Replica::new(config, durable, Timestamp(now_ns)) {
402 Ok(replica) => {
403 let mut h = Box::new(qpx_replica {
404 replica,
405 queue: VecDeque::new(),
406 current: None,
407 drained: false,
408 poisoned: false,
409 });
410 h.pull();
411 // SAFETY: checked non-null above.
412 unsafe { out.write(Box::into_raw(h)) };
413 QPX_OK
414 }
415 Err(e) => code(e),
416 }
417 });
418 note(result.unwrap_or(QPX_ERR_PANIC))
419}
420
421/// Releases a handle (null is ignored).
422///
423/// # Safety
424/// `h` must come from `qpx_replica_new` and not be used afterwards.
425#[unsafe(no_mangle)]
426pub unsafe extern "C" fn qpx_replica_free(h: *mut qpx_replica) {
427 if !h.is_null() {
428 // SAFETY: the caller hands back ownership of a handle from `qpx_replica_new`.
429 drop(unsafe { Box::from_raw(h) });
430 }
431}
432
433/// Queues a write; its id is written to `out_id`.
434///
435/// # Safety
436/// `h` must be a live handle; `payload` must point to `len` bytes; `out_id` writable.
437#[unsafe(no_mangle)]
438pub unsafe extern "C" fn qpx_propose(
439 h: *mut qpx_replica,
440 now_ns: u64,
441 payload: *const u8,
442 len: usize,
443 out_id: *mut u64,
444) -> i32 {
445 // SAFETY: guaranteed by the caller.
446 let Some(payload) = (unsafe { bytes_from(payload, len) }) else { return invalid() };
447 if out_id.is_null() {
448 return invalid();
449 }
450 mutate(h, |r| {
451 let id = r.propose(Timestamp(now_ns), payload)?;
452 // SAFETY: checked non-null; the caller guarantees it is writable.
453 unsafe { out_id.write(id.0) };
454 Ok(())
455 })
456}
457
458/// Proposes new membership: `members_len` ids at `members`, with `order_len` ids at
459/// `leader_order` as the preferred leaders (0 and null: by id). Its id is written to
460/// `out_id` and reported like a proposal's; the change takes effect 64 slots after it is
461/// decided (`QPX_ACTION_RECONFIGURED`). `QPX_ERR_RECONFIGURATION_PENDING` while another
462/// change has not taken effect. A joining replica runs with the original configuration.
463/// To change only the leader order, pass the members in force and the new order. A change
464/// computed before another change or a rotation was decided is ignored and reported as
465/// `QPX_ACTION_DROPPED` with `QPX_DROP_SUPERSEDED`.
466///
467/// # Safety
468/// `h` must be a live handle; `members` must point to `members_len` ids and `leader_order`
469/// to `order_len` ids (either may be null when its length is 0); `out_id` writable.
470#[unsafe(no_mangle)]
471pub unsafe extern "C" fn qpx_propose_reconfiguration(
472 h: *mut qpx_replica,
473 now_ns: u64,
474 members: *const u32,
475 members_len: usize,
476 leader_order: *const u32,
477 order_len: usize,
478 out_id: *mut u64,
479) -> i32 {
480 // SAFETY: guaranteed by the caller.
481 let (Some(members), Some(order)) =
482 (unsafe { ids_from(members, members_len) }, unsafe { ids_from(leader_order, order_len) })
483 else {
484 return invalid();
485 };
486 if out_id.is_null() {
487 return invalid();
488 }
489 mutate(h, |r| {
490 let id = r.propose_reconfiguration(Timestamp(now_ns), members, order)?;
491 // SAFETY: checked non-null; the caller guarantees it is writable.
492 unsafe { out_id.write(id.0) };
493 Ok(())
494 })
495}
496
497/// # Safety
498/// `ptr` must point to `len` readable ids (or `len` must be 0).
499unsafe fn ids_from(ptr: *const u32, len: usize) -> Option<Vec<NodeId>> {
500 if len == 0 {
501 return Some(Vec::new());
502 }
503 if ptr.is_null() {
504 return None;
505 }
506 // SAFETY: guaranteed by the caller.
507 Some(unsafe { slice::from_raw_parts(ptr, len) }.iter().copied().map(NodeId).collect())
508}
509
510/// Requests a linearizable read point; its id is written to `out_id`.
511/// Ids are opaque unsigned 64-bit values; read ids use the high bit (ABI 0.8).
512///
513/// # Safety
514/// `h` must be a live handle; `out_id` writable.
515#[unsafe(no_mangle)]
516pub unsafe extern "C" fn qpx_read_barrier(h: *mut qpx_replica, now_ns: u64, out_id: *mut u64) -> i32 {
517 if out_id.is_null() {
518 return invalid();
519 }
520 mutate(h, |r| {
521 let id = r.read_barrier(Timestamp(now_ns))?;
522 // SAFETY: checked non-null; the caller guarantees it is writable.
523 unsafe { out_id.write(id.0) };
524 Ok(())
525 })
526}
527
528/// Feeds a network message exactly as received.
529///
530/// # Safety
531/// `h` must be a live handle; `msg` must point to `len` bytes.
532#[unsafe(no_mangle)]
533pub unsafe extern "C" fn qpx_handle_message(
534 h: *mut qpx_replica,
535 now_ns: u64,
536 msg: *const u8,
537 len: usize,
538) -> i32 {
539 // SAFETY: guaranteed by the caller.
540 let Some(msg) = (unsafe { bytes_from(msg, len) }) else { return invalid() };
541 mutate(h, |r| r.handle(Timestamp(now_ns), Input::Message(msg)))
542}
543
544/// Reports that every persist up to and including `id` is durable.
545///
546/// # Safety
547/// `h` must be a live handle.
548#[unsafe(no_mangle)]
549pub unsafe extern "C" fn qpx_persisted(h: *mut qpx_replica, now_ns: u64, id: u64) -> i32 {
550 mutate(h, |r| r.handle(Timestamp(now_ns), Input::Persisted(PersistId(id))))
551}
552
553/// Reports that persist `id` failed; the replica fences itself.
554///
555/// # Safety
556/// `h` must be a live handle.
557#[unsafe(no_mangle)]
558pub unsafe extern "C" fn qpx_storage_failed(h: *mut qpx_replica, now_ns: u64, id: u64) -> i32 {
559 mutate(h, |r| r.handle(Timestamp(now_ns), Input::StorageFailed(PersistId(id))))
560}
561
562/// Fires timers due at `now_ns`.
563///
564/// # Safety
565/// `h` must be a live handle.
566#[unsafe(no_mangle)]
567pub unsafe extern "C" fn qpx_handle_timeout(h: *mut qpx_replica, now_ns: u64) -> i32 {
568 mutate(h, |r| r.handle_timeout(Timestamp(now_ns)))
569}
570
571/// Writes the next timer deadline to `out_ns`, or returns `QPX_EMPTY` if none.
572///
573/// # Safety
574/// `h` must be a live handle; `out_ns` writable.
575#[unsafe(no_mangle)]
576pub unsafe extern "C" fn qpx_next_deadline(h: *mut qpx_replica, out_ns: *mut u64) -> i32 {
577 if out_ns.is_null() {
578 return invalid();
579 }
580 with(h, |h| match h.replica.next_deadline() {
581 Some(Timestamp(t)) => {
582 // SAFETY: checked non-null; the caller guarantees it is writable.
583 unsafe { out_ns.write(t) };
584 QPX_OK
585 }
586 None => QPX_EMPTY,
587 })
588}
589
590/// Number of contiguous decided slots.
591///
592/// # Safety
593/// `h` must be a live handle; `out` writable.
594#[unsafe(no_mangle)]
595pub unsafe extern "C" fn qpx_commit_index(h: *mut qpx_replica, out: *mut u64) -> i32 {
596 if out.is_null() {
597 return invalid();
598 }
599 with(h, |h| {
600 // SAFETY: checked non-null; the caller guarantees it is writable.
601 unsafe { out.write(h.replica.commit_index()) };
602 QPX_OK
603 })
604}
605
606/// Copies the replica's core state into `buf`. Two-call pattern: with too small a `cap`
607/// it returns `QPX_BUFFER_TOO_SMALL` after writing the needed size to `out_len`.
608///
609/// # Safety
610/// `h` must be a live handle; `buf` writable for `cap` bytes (or null with `cap` 0);
611/// `out_len` writable.
612#[unsafe(no_mangle)]
613pub unsafe extern "C" fn qpx_core_state(
614 h: *mut qpx_replica,
615 buf: *mut u8,
616 cap: usize,
617 out_len: *mut usize,
618) -> i32 {
619 if out_len.is_null() || (buf.is_null() && cap > 0) {
620 return invalid();
621 }
622 with(h, |h| {
623 let state = h.replica.core_state();
624 // SAFETY: checked non-null; the caller guarantees it is writable.
625 unsafe { out_len.write(state.len()) };
626 if cap < state.len() {
627 return QPX_BUFFER_TOO_SMALL;
628 }
629 // SAFETY: `buf` has room for `cap >= state.len()` bytes.
630 unsafe { ptr::copy_nonoverlapping(state.as_ptr(), buf, state.len()) };
631 QPX_OK
632 })
633}
634
635/// Discards log state up to `through`, snapshotted by the application with `state`.
636///
637/// # Safety
638/// `h` must be a live handle; `state` must point to `len` bytes.
639#[unsafe(no_mangle)]
640pub unsafe extern "C" fn qpx_compact(
641 h: *mut qpx_replica,
642 now_ns: u64,
643 through: u64,
644 state: *const u8,
645 len: usize,
646) -> i32 {
647 // SAFETY: guaranteed by the caller.
648 let Some(state) = (unsafe { bytes_from(state, len) }) else { return invalid() };
649 mutate(h, |r| r.compact(Timestamp(now_ns), Slot(through), state))
650}
651
652/// Adopts a snapshot covering slots up to `through`; `QPX_IGNORED` if the replica already
653/// emitted past it (do not rewind the application state in that case).
654///
655/// # Safety
656/// `h` must be a live handle; `state` must point to `len` bytes.
657#[unsafe(no_mangle)]
658pub unsafe extern "C" fn qpx_install_snapshot(
659 h: *mut qpx_replica,
660 now_ns: u64,
661 through: u64,
662 state: *const u8,
663 len: usize,
664) -> i32 {
665 // SAFETY: guaranteed by the caller.
666 let Some(state) = (unsafe { bytes_from(state, len) }) else { return invalid() };
667 let mut adopted = true;
668 let rc = mutate(h, |r| {
669 adopted = r.install_snapshot(Timestamp(now_ns), Slot(through), state)?;
670 Ok(())
671 });
672 if rc == QPX_OK && !adopted { QPX_IGNORED } else { rc }
673}
674
675/// Network messages rejected (malformed, foreign or from non-members).
676pub const QPX_METRIC_MESSAGES_REJECTED: u32 = 1;
677/// Record requests re-sent.
678pub const QPX_METRIC_RETRANSMITS: u32 = 2;
679/// Catch-up requests re-sent.
680pub const QPX_METRIC_CATCH_UP_RETRIES: u32 = 3;
681/// Slots learned as decided.
682pub const QPX_METRIC_SLOTS_DECIDED: u32 = 4;
683/// Own decisions on the leader fast path.
684pub const QPX_METRIC_FAST_PATH_DECISIONS: u32 = 5;
685/// Decided batches that failed to decode.
686pub const QPX_METRIC_CORRUPT_BATCHES: u32 = 6;
687/// Batches forwarded to the leader.
688pub const QPX_METRIC_FORWARDED: u32 = 7;
689/// Own entries proposed directly after the leader was too slow.
690pub const QPX_METRIC_HEDGED: u32 = 8;
691/// Gauge: decided slots held in memory.
692pub const QPX_METRIC_RETAINED_SLOTS: u32 = 9;
693/// Gauge: recorder registers held in memory.
694pub const QPX_METRIC_LIVE_REGISTERS: u32 = 10;
695/// Times this replica stepped aside because a write waited too long on its disk.
696pub const QPX_METRIC_STEPPED_ASIDE: u32 = 11;
697/// Times this replica suspected the member it hands entries to of being silent (ABI 0.10).
698pub const QPX_METRIC_SUSPICIONS: u32 = 12;
699/// Leader-order changes leader placement proposed from this replica (ABI 0.10).
700pub const QPX_METRIC_PLACEMENT_MOVES: u32 = 13;
701/// Gauge: membership epoch in force (ABI 0.10).
702pub const QPX_METRIC_EPOCH: u32 = 14;
703/// Gauge: this replica's position in the leader order in force, 0 when it leads (ABI 0.10).
704pub const QPX_METRIC_LEADER_POSITION: u32 = 15;
705
706/// Reads counter or gauge `metric` (`QPX_METRIC_*`, see the Rust `Metrics`) into `out`; an
707/// unknown metric is `QPX_ERR_INVALID_ARGUMENT`.
708///
709/// # Safety
710/// `h` must be a live handle; `out` writable.
711#[unsafe(no_mangle)]
712pub unsafe extern "C" fn qpx_metric(h: *mut qpx_replica, metric: u32, out: *mut u64) -> i32 {
713 if out.is_null() {
714 return invalid();
715 }
716 with(h, |h| {
717 let m = h.replica.metrics();
718 let v = match metric {
719 QPX_METRIC_MESSAGES_REJECTED => m.messages_rejected,
720 QPX_METRIC_RETRANSMITS => m.retransmits,
721 QPX_METRIC_CATCH_UP_RETRIES => m.catch_up_retries,
722 QPX_METRIC_SLOTS_DECIDED => m.slots_decided,
723 QPX_METRIC_FAST_PATH_DECISIONS => m.fast_path_decisions,
724 QPX_METRIC_CORRUPT_BATCHES => m.corrupt_batches,
725 QPX_METRIC_FORWARDED => m.forwarded,
726 QPX_METRIC_HEDGED => m.hedged,
727 QPX_METRIC_RETAINED_SLOTS => m.retained_slots,
728 QPX_METRIC_LIVE_REGISTERS => m.live_registers,
729 QPX_METRIC_STEPPED_ASIDE => m.stepped_aside,
730 QPX_METRIC_SUSPICIONS => m.suspicions,
731 QPX_METRIC_PLACEMENT_MOVES => m.placement_moves,
732 QPX_METRIC_EPOCH => m.epoch,
733 QPX_METRIC_LEADER_POSITION => m.leader_position,
734 _ => {
735 set_last_error(&format!("unknown metric {metric}"));
736 return QPX_ERR_INVALID_ARGUMENT;
737 }
738 };
739 // SAFETY: checked non-null; the caller guarantees it is writable.
740 unsafe { out.write(v) };
741 QPX_OK
742 })
743}
744
745/// Copies the description of the calling thread's most recent failing call (empty if the
746/// last call succeeded) as a NUL-terminated string. Two-call pattern: with too small a
747/// `cap` it returns `QPX_BUFFER_TOO_SMALL` after writing the needed size (including the
748/// NUL) to `out_len`.
749///
750/// # Safety
751/// `buf` must be writable for `cap` bytes (or null with `cap` 0); `out_len` writable.
752#[unsafe(no_mangle)]
753pub unsafe extern "C" fn qpx_last_error(buf: *mut std::ffi::c_char, cap: usize, out_len: *mut usize) -> i32 {
754 if out_len.is_null() || (buf.is_null() && cap > 0) {
755 return QPX_ERR_INVALID_ARGUMENT;
756 }
757 let copy = |msg: &str| {
758 let need = msg.len() + 1;
759 // SAFETY: checked non-null; the caller guarantees it is writable.
760 unsafe { out_len.write(need) };
761 if cap < need {
762 return QPX_BUFFER_TOO_SMALL;
763 }
764 // SAFETY: `buf` has room for `cap >= need` bytes.
765 unsafe {
766 ptr::copy_nonoverlapping(msg.as_ptr(), buf.cast::<u8>(), msg.len());
767 buf.add(msg.len()).write(0);
768 }
769 QPX_OK
770 };
771 LAST_ERROR.try_with(|e| copy(&e.borrow())).unwrap_or_else(|_| copy(""))
772}
773
774#[cfg(test)]
775mod tests {
776 use super::*;
777 use quepaxa::Config;
778
779 #[test]
780 fn request_id_exhaustion_has_an_explicit_status() {
781 assert_eq!(code(Error::RequestIdExhausted), QPX_ERR_REQUEST_ID_EXHAUSTED);
782 // SAFETY: the returned status description is static and NUL-terminated.
783 let message = unsafe { std::ffi::CStr::from_ptr(qpx_status_str(QPX_ERR_REQUEST_ID_EXHAUSTED)) };
784 assert_eq!(message.to_str().unwrap(), Error::RequestIdExhausted.to_string());
785 }
786
787 #[test]
788 fn a_panic_poisons_the_handle() {
789 let cfg = Config::new([1; 16], NodeId(0), vec![NodeId(0)], [1; 32]);
790 let replica = Replica::new(cfg, [], Timestamp(0)).unwrap();
791 let h = Box::into_raw(Box::new(qpx_replica {
792 replica,
793 queue: VecDeque::new(),
794 current: None,
795 drained: false,
796 poisoned: false,
797 }));
798 assert_eq!(with(h, |_| panic!("boom")), QPX_ERR_PANIC);
799 assert_eq!(with(h, |_| QPX_OK), QPX_ERR_POISONED);
800 // SAFETY: `h` came from `Box::into_raw` above.
801 unsafe { qpx_replica_free(h) };
802 }
803}