libmizu 0.2.0
Lock-free shared-memory IPC at thread speed in C11
Loading...
Searching...
No Matches
mizu.h
Go to the documentation of this file.
1
69
70#ifndef MIZU_MIZU_H
71#define MIZU_MIZU_H
72
73#include <stddef.h>
74#include <stdint.h>
75
79#ifdef __cplusplus
80# include <atomic>
81# define MIZU_ATOMIC(T) std::atomic<T>
82# define MIZU_STATIC_ASSERT static_assert
83extern "C" {
84#else
85# include <stdatomic.h>
86# define MIZU_ATOMIC(T) _Atomic T
87# define MIZU_STATIC_ASSERT _Static_assert
88#endif
89
94#if defined(MIZU_SHARED)
95# if defined(_WIN32)
96# if defined(MIZU_BUILDING)
97# define MIZU_API __declspec(dllexport)
98# else
99# define MIZU_API __declspec(dllimport)
100# endif
101# else
102# define MIZU_API __attribute__((visibility("default")))
103# endif
104#else
105# define MIZU_API
106#endif
107
108#define MIZU_VERSION_MAJOR 0
109#define MIZU_VERSION_MINOR 2
110#define MIZU_VERSION_PATCH 0
111
113MIZU_API const char *mizu_version(void);
114
115// Status and errors ------------------------------------------------------------
116
121typedef enum mizu_status_e {
122 MIZU_OK = 0,
123 MIZU_FULL,
124 MIZU_TIMEOUT,
125 MIZU_CLOSED,
126 MIZU_PEER_GONE,
127 MIZU_ERR
129
143
157MIZU_API const char *mizu_last_error_message(void);
158
159// Opaque handles ---------------------------------------------------------------
160
161typedef struct mizu_channel_s mizu_channel;
162typedef struct mizu_pool_s mizu_pool;
163typedef struct mizu_shm_s mizu_shm;
168
169// Wire format: channel region ----------------------------------------------------
170
174#define MIZU_MAGIC 0x4D495A43u
175#define MIZU_ABI_VERSION 1u
176
177typedef struct mizu_preamble_s {
178 uint32_t magic;
179 uint32_t version;
180 uint32_t cap;
181 uint32_t slot;
182 uint64_t host_pid;
183 uint64_t arena_size;
184 uint64_t drop_offset;
186 uint64_t drop_size;
187 uint64_t livedir_offset;
188 uint64_t livedir_size;
189} mizu_preamble;
190
191MIZU_STATIC_ASSERT(sizeof(mizu_preamble) == 64, "mizu_preamble is the wire format");
192
198#define MIZU_DROP_R 0x52u
199#define MIZU_DROP_SOURCE 0x53u
202#define MIZU_DROP_MAX (UINT64_C(1) << 30)
203
209#define MIZU_ENTITY_HOST 0
210#define MIZU_ENTITY_PEER 1
211#define MIZU_ENTITY_OFFSET(i) ((size_t) 128 + 64 * (size_t) (i))
212#define MIZU_FIXED_LAYOUT_SIZE ((size_t) 512)
213
214#define MIZU_OFF_READY ((size_t) 64)
215#define MIZU_OFF_CLOSED ((size_t) 68)
216#define MIZU_OFF_PEER_PID ((size_t) 72)
217#define MIZU_OFF_FLAGS ((size_t) 80)
218#define MIZU_FLAG_SPIN 1u
219
220#define MIZU_ENTITY_EPOCH 0
221#define MIZU_ENTITY_PARKED 4
222#define MIZU_ENTITY_REG 8
234#define MIZU_WAIT_PARKED 1u
235#define MIZU_WAIT_NOTIFY 2u
241#define MIZU_ENTITY_IDENT 16
242
243#define MIZU_OFF_HP_TAIL ((size_t) 256)
244#define MIZU_OFF_PH_HEAD ((size_t) 320)
245#define MIZU_OFF_PH_TAIL ((size_t) 384)
246#define MIZU_OFF_HP_HEAD ((size_t) 448)
247
248MIZU_STATIC_ASSERT(MIZU_OFF_HP_TAIL / 128 == MIZU_OFF_PH_HEAD / 128 &&
249 MIZU_OFF_PH_TAIL / 128 == MIZU_OFF_HP_HEAD / 128 &&
250 MIZU_OFF_HP_TAIL / 128 != MIZU_OFF_PH_TAIL / 128,
251 "ring indices pair by writer on a 128-byte span");
252
253// Wire format: payload framing -------------------------------------------------
254
279typedef enum mizu_kind_e {
280 MIZU_KIND_INLINE = 0,
281 MIZU_KIND_ARENA,
282 MIZU_KIND_SHM_RAW,
283 MIZU_KIND_RAWVEC,
284 MIZU_KIND_SHM_VEC,
285 MIZU_KIND_REF,
286 MIZU_KIND_NIL,
287 MIZU_KIND_STR1,
288 MIZU_KIND_RAWSPILL
290
297#define MIZU_AUX_F_KEEPERLESS UINT64_C(1)
298
299#define MIZU_STR1_NA UINT64_MAX
300
306#define MIZU_CE_NATIVE 0u
307#define MIZU_CE_UTF8 1u
308#define MIZU_CE_LATIN1 2u
309#define MIZU_CE_BYTES 3u
310
311typedef struct mizu_slot_hdr_s {
312 uint32_t kind;
313 uint32_t len;
314 uint64_t aux;
315} mizu_slot_hdr;
316
317MIZU_STATIC_ASSERT(sizeof(mizu_slot_hdr) == 16, "mizu_slot_hdr is the wire format");
318
334
338#define MIZU_NA_INT32 INT32_MIN
339#define MIZU_NA_INT64 INT64_MIN
340#define MIZU_NA_REAL_BITS 0x7FF80000000007A2ULL
341
344
351#define MIZU_ZC_REFCOUNT_OFF ((size_t) 24)
352#define MIZU_ZC_FLAGS_OFF ((size_t) 28)
353#define MIZU_ZC_FLAG_REFHELD 1u
354
355// Wire format: MIZH / MIZS / MIZL region layouts ---------------------------------
356
367#define MIZU_HDR_FLAGS_OFF ((size_t) 32)
368#define MIZU_HDR_FLAG_S4 1u
369
386#define MIZU_HDR_VALID_OFF ((size_t) 40)
387#define MIZU_HDR_VALID_COUNT ((size_t) 48)
388
412#define MIZU_MIZL_S4 0x40000000
413
414#define MIZU_MAGIC_VEC 0x4D495A48u
415#define MIZU_MAGIC_STR 0x4D495A53u
416#define MIZU_MAGIC_LIST 0x4D495A4Cu
417#define MIZU_HEADER_SIZE 64
418
419#define MIZU_NAME_MAX 30
420
421// Wire format: pool region -------------------------------------------------------
422
423#define MIZU_POOL_MAGIC 0x4D495A50u
425#define MIZU_MAX_WORKERS 64
426
427typedef struct mizu_pool_hdr_s {
428 uint32_t magic;
429 uint32_t version;
430 uint32_t max_workers;
431 uint32_t max_submitters;
432 uint32_t inj_cap;
433 uint32_t deque_cap;
434 uint32_t result_slots;
435 uint32_t slot;
436 uint64_t owner_pid;
437 uint64_t livedir_offset;
438 uint64_t livedir_size;
446} mizu_pool_hdr;
447
448MIZU_STATIC_ASSERT(sizeof(mizu_pool_hdr) == 64, "mizu_pool_hdr is the wire format");
449
455typedef struct mizu_wk_slot_s {
457 int32_t id;
458 int64_t pid;
460 MIZU_ATOMIC(uint32_t) park_epoch;
461 int64_t deque_buf_off;
462 int32_t deque_cap;
463 MIZU_ATOMIC(int32_t) in_flight_rs;
464 MIZU_ATOMIC(uint64_t) in_flight_seq;
465 MIZU_ATOMIC(int64_t) deque_bottom;
466 MIZU_ATOMIC(int32_t) retire;
467 uint8_t pad0[4];
468 uint8_t pad1[64];
469 MIZU_ATOMIC(int64_t) deque_top;
472 uint64_t live_dev;
473 uint64_t live_ino;
474 MIZU_ATOMIC(uint64_t) stat_tasks;
475 MIZU_ATOMIC(uint64_t) stat_steals;
476 MIZU_ATOMIC(uint64_t) stat_inj;
477 MIZU_ATOMIC(uint64_t) stat_parks;
478 MIZU_ATOMIC(uint64_t) stat_helps;
479 uint8_t pad2[64];
481
482MIZU_STATIC_ASSERT(sizeof(mizu_wk_slot) == 256, "mizu_wk_slot is the wire format");
483
487typedef struct mizu_sub_slot_s {
489 MIZU_ATOMIC(uint32_t) park_epoch;
490 int64_t pid;
495 uint32_t rs_start;
496 uint32_t rs_count;
497 uint64_t live_dev;
498 uint64_t live_ino;
499 MIZU_ATOMIC(uint64_t) stat_spills;
500 MIZU_ATOMIC(uint64_t) stat_spill_reuse;
501 MIZU_ATOMIC(uint32_t) notify;
504 uint8_t pad[68];
506
507MIZU_STATIC_ASSERT(sizeof(mizu_sub_slot) == 128, "mizu_sub_slot is the wire format");
508
514#define MIZU_WS_NOTIFY (INT32_C(1) << 30)
515
536#define MIZU_RS_STATE_MASK UINT64_C(0xF)
537#define MIZU_RS_WK_SHIFT 4
538#define MIZU_RS_WK_MASK UINT64_C(0x7F)
539#define MIZU_RS_SEQ_SHIFT 11
540
541typedef struct mizu_rs_hdr_s {
542 MIZU_ATOMIC(uint64_t) state;
546 uint32_t pad0;
549 mizu_slot_hdr ph;
550} mizu_rs_hdr;
551
552MIZU_STATIC_ASSERT(sizeof(mizu_rs_hdr) == 40, "mizu_rs_hdr is the wire format");
553
560typedef struct mizu_entry_hdr_s {
561 uint64_t task_id;
562 uint64_t rs_seq;
563 uint32_t rs_index;
564 uint16_t submitter_slot;
565 uint16_t flags;
566 mizu_slot_hdr ph;
568
569MIZU_STATIC_ASSERT(sizeof(mizu_entry_hdr) == 40, "mizu_entry_hdr is the wire format");
570
571#define MIZU_ENTRY_RUNNER 1u
572
573typedef enum mizu_wk_status_e { MIZU_WK_FREE = 0, MIZU_WK_CLAIMING, MIZU_WK_LIVE,
574 MIZU_WK_LEAVING, MIZU_WK_REAPING } mizu_wk_status;
575typedef enum mizu_sub_status_e { MIZU_SUB_FREE = 0, MIZU_SUB_LIVE,
576 MIZU_SUB_REAPING } mizu_sub_status;
587typedef enum mizu_rs_status_e { MIZU_RS_FREE = 0, MIZU_RS_PENDING,
588 MIZU_RS_RUNNING, MIZU_RS_OK,
589 MIZU_RS_ERR, MIZU_RS_CANCEL,
590 MIZU_RS_DIED, MIZU_RS_LOST } mizu_rs_status;
591typedef enum mizu_park_state_e { MIZU_WPK_RUNNING = 0, MIZU_WPK_IDLE,
592 MIZU_WPK_PARKED, MIZU_WPK_WAKING } mizu_park_state;
593
598#define MIZU_INJ_META_SIZE ((size_t) 256)
599#define MIZU_INJ_TAIL_OFF ((size_t) 0)
600#define MIZU_INJ_HEAD_OFF ((size_t) 128)
601#define MIZU_TIER_SIZE ((size_t) 256)
602#define MIZU_TIER_READY_OFF ((size_t) 0)
603#define MIZU_TIER_FULL_OFF ((size_t) 128)
604#define MIZU_CTRL_SIZE ((size_t) 384)
605#define MIZU_CTRL_SHUTDOWN_OFF ((size_t) 0)
606#define MIZU_CTRL_PARKED_OFF ((size_t) 128)
607#define MIZU_CTRL_HELP_OFF ((size_t) 256)
608
609MIZU_STATIC_ASSERT(MIZU_INJ_HEAD_OFF % 128 == 0 &&
610 MIZU_TIER_FULL_OFF % 128 == 0 &&
611 MIZU_CTRL_PARKED_OFF % 128 == 0 &&
612 MIZU_CTRL_HELP_OFF % 128 == 0,
613 "cross-writer words sit on distinct 128-byte spans");
614
615// Regions (mizu_shm) ----------------------------------------------------------------
616
632#define MIZU_OPEN_VIEW_NOCOUNT 1u
633MIZU_API mizu_status mizu_shm_create(mizu_shm **out, size_t size);
634MIZU_API mizu_status mizu_shm_open(mizu_shm **out, const char *name);
635MIZU_API mizu_status mizu_shm_open_rw(mizu_shm **out, const char *name,
636 int populate);
637MIZU_API mizu_status mizu_shm_open_view(mizu_shm **out, const char *name);
638MIZU_API mizu_status mizu_shm_open_view_flags(mizu_shm **out, const char *name,
639 uint32_t flags);
640MIZU_API void mizu_shm_close(mizu_shm *, int unlink);
641MIZU_API void *mizu_shm_addr(mizu_shm *);
642MIZU_API size_t mizu_shm_size(const mizu_shm *);
643MIZU_API const char *mizu_shm_name(const mizu_shm *);
644
653MIZU_API char **mizu_shm_reap(int *n);
654
660MIZU_API void mizu_zc_ref(mizu_shm *);
661MIZU_API void mizu_zc_unref(mizu_shm *);
662MIZU_API uint32_t mizu_zc_refcount(const mizu_shm *);
663MIZU_API uint32_t mizu_zc_flags(const mizu_shm *);
664MIZU_API void mizu_zc_flag_refheld(mizu_shm *);
665
666// Channel verbs --------------------------------------------------------------------
667
676typedef struct mizu_channel_opts_s {
677 uint32_t size;
678 uint32_t capacity;
679 uint32_t slot_size;
680 uint64_t arena_size;
681 uint32_t flags;
682 const uint8_t *drop;
683 uint64_t drop_size;
685
686#define MIZU_CHANNEL_SPIN MIZU_FLAG_SPIN
687
688MIZU_API void mizu_channel_opts_init(mizu_channel_opts *);
689
697 const mizu_channel_opts *,
698 const mizu_binding *);
699MIZU_API mizu_status mizu_channel_token(const mizu_channel *,
700 char *buf, size_t cap);
701MIZU_API mizu_status mizu_channel_attach(mizu_channel **out, const char *token,
702 const mizu_binding *);
707MIZU_API void mizu_channel_drop(const mizu_channel *, const uint8_t **bytes,
708 uint64_t *n);
709MIZU_API mizu_status mizu_channel_ready_set(mizu_channel *);
710MIZU_API mizu_status mizu_channel_ready_wait(mizu_channel *, double timeout_ms);
711
731MIZU_API mizu_status mizu_channel_send(mizu_channel *, void *obj);
732MIZU_API mizu_status mizu_channel_send_batch(mizu_channel *, void **objs,
733 size_t n, size_t *accepted_out);
734MIZU_API mizu_status mizu_channel_recv(mizu_channel *, void **obj_out,
735 double timeout_ms);
736MIZU_API mizu_status mizu_channel_recv_batch(mizu_channel *, void **objs,
737 size_t cap, size_t *n_out,
738 double timeout_ms);
739
745typedef void (*mizu_obj_sink)(void *ctx, size_t i, void *obj);
746MIZU_API mizu_status mizu_channel_recv_batch_fn(mizu_channel *, size_t cap,
747 size_t *n_out, mizu_obj_sink,
748 void *ctx, double timeout_ms);
749
770MIZU_API mizu_status mizu_channel_close(mizu_channel *, double timeout_ms);
771MIZU_API mizu_status mizu_channel_close_signal(mizu_channel *);
773MIZU_API int mizu_channel_alive(const mizu_channel *);
781MIZU_API void mizu_channel_destroy(mizu_channel *);
789MIZU_API void mizu_channel_abandon(mizu_channel *);
790
795typedef struct mizu_channel_info_s {
796 uint32_t size;
797 const char *name;
798 int32_t side;
799 uint32_t capacity, slot_size;
800 uint64_t arena_size, inline_max;
801 int32_t spin, ready, closed;
802 int64_t peer_pid;
803 uint64_t tx_sent, tx_published, tx_consumed, rx_consumed, rx_published;
804 uint64_t fl_entries, fl_hits;
805 uint64_t open_hits, open_misses;
806 uint64_t ledger_entries;
807 uint64_t zc_open_hits, zc_open_misses;
809 uint64_t notify_sends;
812
813MIZU_API mizu_status mizu_channel_info_get(const mizu_channel *,
814 mizu_channel_info *out);
815
819MIZU_API const char *mizu_channel_error(const mizu_channel *);
820
821// Pool verbs ---------------------------------------------------------------------
822
825typedef struct mizu_pool_opts_s {
826 uint32_t size;
827 uint32_t max_workers;
828 uint32_t max_submitters;
829 uint32_t injection_cap;
830 uint32_t per_worker_cap;
831 uint32_t result_slots;
832 uint32_t slot_size;
834
835MIZU_API void mizu_pool_opts_init(mizu_pool_opts *);
836
843typedef struct mizu_task_s {
844 uint64_t word;
846
847#define MIZU_TASK_SEQ_BITS 40
848#define MIZU_TASK_SEQ_MAX ((UINT64_C(1) << MIZU_TASK_SEQ_BITS) - 1)
849
850static inline uint64_t mizu_task_seq(const mizu_task *t) {
851 return t->word & MIZU_TASK_SEQ_MAX;
852}
853static inline uint32_t mizu_task_rs_index(const mizu_task *t) {
854 return (uint32_t) (t->word >> MIZU_TASK_SEQ_BITS);
855}
856static inline mizu_task mizu_task_make(uint64_t seq, uint32_t rs_index) {
857 mizu_task t;
858 t.word = (seq & MIZU_TASK_SEQ_MAX) |
859 ((uint64_t) rs_index << MIZU_TASK_SEQ_BITS);
860 return t;
861}
862
866 const mizu_binding *);
867MIZU_API mizu_status mizu_pool_token(const mizu_pool *, char *buf, size_t cap);
868MIZU_API mizu_status mizu_pool_ready_wait(mizu_pool *, const uint32_t *slots,
869 size_t n, double timeout_ms);
870MIZU_API void mizu_pool_destroy(mizu_pool *);
875MIZU_API void mizu_pool_abandon(mizu_pool *);
876
880MIZU_API mizu_status mizu_pool_attach(mizu_pool **out, const char *token,
881 const mizu_binding *);
882
898typedef enum mizu_worker_exit_e { MIZU_EXIT_SHUTDOWN = 0,
899 MIZU_EXIT_OWNER_GONE,
900 MIZU_EXIT_RETIRED,
901 MIZU_EXIT_ERROR } mizu_worker_exit;
902
903MIZU_API mizu_status mizu_pool_worker_join(mizu_pool **out, const char *token,
904 uint32_t slot, const mizu_binding *);
905MIZU_API mizu_worker_exit mizu_pool_worker_run(mizu_pool *);
906MIZU_API int mizu_pool_lame_duck(mizu_pool *);
907MIZU_API mizu_status mizu_pool_leave(mizu_pool *);
908
912MIZU_API mizu_status mizu_pool_retire(mizu_pool *, uint32_t slot);
913
921typedef enum mizu_step_result_e { MIZU_STEP_IDLE = 0, MIZU_STEP_TASK = 1,
922 MIZU_STEP_SHUTDOWN = -1,
923 MIZU_STEP_RETIRED = -2 } mizu_step_result;
924MIZU_API int mizu_pool_step(mizu_pool *, double timeout_ms);
925
938MIZU_API mizu_status mizu_pool_submit(mizu_pool *, void *task_obj,
939 mizu_task *out, double timeout_ms);
940MIZU_API mizu_status mizu_pool_submit_batch(mizu_pool *, void **objs, size_t n,
941 mizu_task *out, size_t *n_out,
942 double timeout_ms);
943
948typedef void *(*mizu_obj_supply)(void *ctx, size_t i);
949MIZU_API mizu_status mizu_pool_submit_batch_fn(mizu_pool *, mizu_obj_supply,
950 void *ctx, size_t n,
951 mizu_task *out, size_t *n_out,
952 double timeout_ms);
953
984 void **value_out, double timeout_ms);
985MIZU_API mizu_status mizu_pool_collect_any(mizu_pool *, const mizu_task *,
986 size_t n, size_t *index_out,
987 void **value_out, double timeout_ms);
988MIZU_API mizu_status mizu_pool_collect_all(mizu_pool *, const mizu_task *,
989 size_t n, void **values_out,
990 size_t *err_index_out,
991 size_t *consumed_out,
992 double timeout_ms);
993
1000 size_t n, mizu_obj_sink,
1001 void *ctx,
1002 size_t *err_index_out,
1003 size_t *consumed_out,
1004 double timeout_ms);
1005
1011typedef enum mizu_trace_event_e { MIZU_TRACE_SUBMIT = 0, MIZU_TRACE_START,
1012 MIZU_TRACE_DONE, MIZU_TRACE_ERROR,
1013 MIZU_TRACE_DROP,
1014 MIZU_TRACE_REHOME } mizu_trace_event;
1015typedef void (*mizu_trace_fn)(mizu_trace_event event, uint64_t task_id,
1016 void *ctx);
1017MIZU_API mizu_status mizu_pool_set_trace(mizu_pool *, mizu_trace_fn, void *ctx);
1018
1030MIZU_API int mizu_pool_cancel(mizu_pool *, const mizu_task *);
1041MIZU_API int mizu_pool_task_state(mizu_pool *, const mizu_task *);
1049MIZU_API mizu_status mizu_pool_stop(mizu_pool *, double timeout_ms);
1050
1059typedef struct mizu_pool_info_s {
1060 uint32_t size;
1061 const char *name;
1062 int32_t role;
1063 uint32_t max_workers, max_submitters, injection_cap, result_slots,
1064 slot_size;
1065 uint32_t n_workers, n_submitters;
1067 uint8_t sub_state[64];
1069 uint64_t parked_mask;
1070 uint32_t tasks_by_state[8];
1071 uint32_t inj_queued[64];
1072 int32_t shutdown;
1074
1075typedef enum mizu_role_e { MIZU_ROLE_CONTROLLER = 0, MIZU_ROLE_WORKER,
1076 MIZU_ROLE_SUBMITTER } mizu_role;
1077
1078typedef struct mizu_worker_stat_s {
1079 int32_t status, park_state;
1080 int64_t pid;
1081 uint64_t tasks, steals, injections, parks, helps;
1082 int64_t deque_top, deque_bottom;
1083 int32_t in_flight_rs;
1084} mizu_worker_stat;
1085
1086typedef struct mizu_sub_stat_s {
1087 int32_t status;
1088 int64_t pid;
1089 uint32_t rs_start, rs_count;
1090 uint64_t injected, claimed;
1091 uint64_t spills, spill_reuse;
1092 int32_t ready;
1093 int32_t full_waiter;
1094} mizu_sub_stat;
1095
1096typedef struct mizu_pool_dump_s {
1097 uint32_t size;
1098 mizu_pool_info info;
1099 uint32_t n_workers;
1100 mizu_worker_stat workers[MIZU_MAX_WORKERS];
1101 uint32_t n_submitters;
1102 mizu_sub_stat submitters[64];
1103 uint64_t fl_entries, fl_bytes, fl_hits;
1104 uint64_t open_hits, open_misses;
1105 uint64_t collect_parks;
1107 int32_t help_wanted;
1108 uint64_t notify_sends;
1110} mizu_pool_dump;
1111
1113typedef struct mizu_rs_row_s {
1114 uint32_t slot;
1115 int32_t status;
1116 uint64_t sequence;
1117 int32_t worker_slot;
1118 int32_t waiter_slot;
1120
1121MIZU_API mizu_status mizu_pool_info_get(const mizu_pool *,
1122 mizu_pool_info *out);
1123MIZU_API mizu_status mizu_pool_dump_get(const mizu_pool *, mizu_pool_dump *out);
1129 uint32_t cap, uint32_t *n_out);
1130
1131MIZU_API mizu_errcat mizu_pool_errcat(const mizu_pool *);
1132MIZU_API const char *mizu_pool_error(const mizu_pool *);
1133
1134#ifdef __cplusplus
1135}
1136#endif
1137
1138#endif /* MIZU_MIZU_H */
struct mizu_entry_hdr_s mizu_entry_hdr
Injection ring / deque entry header; payload framing at offset 24, payload bytes at 40.
mizu_type_e
Wire type tags, fixed by the wire format (RAWVEC aux, MIZU* layout headers).
Definition mizu.h:324
@ MIZU_TYPE_CPLX
interleaved float64 re/im
Definition mizu.h:328
@ MIZU_TYPE_RAW
bytes
Definition mizu.h:331
@ MIZU_TYPE_REAL
float64; a specific NaN payload is the sentinel
Definition mizu.h:327
@ MIZU_TYPE_LGL
int32 logical; INT_MIN is the missing sentinel
Definition mizu.h:325
@ MIZU_TYPE_STR
string vector (MIZS layout)
Definition mizu.h:329
@ MIZU_TYPE_VEC
list tree (MIZL layout)
Definition mizu.h:330
@ MIZU_TYPE_INT64
int64; INT64_MIN is the missing sentinel
Definition mizu.h:332
@ MIZU_TYPE_INT
int32; INT_MIN is the missing sentinel
Definition mizu.h:326
void mizu_channel_abandon(mizu_channel *)
The forked-child teardown: releases only the process-local half of an inherited handle (the child's c...
mizu_status mizu_channel_create(mizu_channel **out, const mizu_channel_opts *, const mizu_binding *)
create: host side; writes the preamble, returns the handle.
enum mizu_worker_exit_e mizu_worker_exit
Worker side: join attaches to token as worker slot (liveness lock before the status CAS; the binding'...
void mizu_channel_drop(const mizu_channel *, const uint8_t **bytes, uint64_t *n)
The peer bootstrap payload staged at create (the preamble's drop): borrowed bytes,...
mizu_worker_exit_e
Worker side: join attaches to token as worker slot (liveness lock before the status CAS; the binding'...
Definition mizu.h:898
struct mizu_channel_info_s mizu_channel_info
Handle-local + wire-state snapshot.
mizu_status mizu_pool_collect(mizu_pool *, const mizu_task *, void **value_out, double timeout_ms)
collect waits for the task's terminal state and sets *value_out to the read_fn's product,...
mizu_status mizu_pool_create(mizu_pool **out, const mizu_pool_opts *, const mizu_binding *)
create: controller side.
struct mizu_channel_opts_s mizu_channel_opts
size-stamped options; mizu_channel_opts_init zeroes + stamps, and create refuses a struct whose stamp...
mizu_errcat_e
Portable failure categories for MIZU_ERR (the platform layer classifies errno / GetLastError).
Definition mizu.h:132
@ MIZU_ERRCAT_STOPPED
pool stopped, or its owner died (submit)
Definition mizu.h:138
@ MIZU_ERRCAT_STAGE
the binding's stage_fn returned nonzero
Definition mizu.h:139
@ MIZU_ERRCAT_EXHAUSTED
pool result slots exhausted (submit)
Definition mizu.h:137
@ MIZU_ERRCAT_INTERRUPTED
the binding's check hook returned nonzero
Definition mizu.h:140
@ MIZU_ERRCAT_EXISTS
region name already in use (orphan)
Definition mizu.h:136
@ MIZU_ERRCAT_NOMEMORY
ENOMEM / commit limit exceeded.
Definition mizu.h:135
@ MIZU_ERRCAT_NOSPACE
ENOSPC / ERROR_DISK_FULL.
Definition mizu.h:134
mizu_step_result_e
One claim at a time, for deterministic in-process harnesses (the pool_pair/pool_step discipline).
Definition mizu.h:921
struct mizu_binding_s mizu_binding
The binding callbacks struct, taken by pointer at create/attach/join.
Definition mizu.h:167
enum mizu_trace_event_e mizu_trace_event
Task lifecycle trace hook: per-handle, per-process; NULL removes.
enum mizu_type_e mizu_type
Wire type tags, fixed by the wire format (RAWVEC aux, MIZU* layout headers).
int mizu_channel_alive(const mizu_channel *)
Logically a read; the probe can run survivor cleanup internally.
enum mizu_errcat_e mizu_errcat
Portable failure categories for MIZU_ERR (the platform layer classifies errno / GetLastError).
mizu_errcat mizu_last_error_category(void)
Error access.
struct mizu_sub_slot_s mizu_sub_slot
Submitter registry slot: one 128-byte span per submitter.
#define MIZU_API
Export macro.
Definition mizu.h:105
struct mizu_wk_slot_s mizu_wk_slot
Worker registry slot: two 128-byte spans, with the admin and owner-written fields on the first and th...
void mizu_pool_abandon(mizu_pool *)
The forked-child teardown: as mizu_channel_abandon, it releases the child's copies of the mapping and...
enum mizu_rs_status_e mizu_rs_status
PENDING is a submitted, unclaimed task; RUNNING is the claimant's ownership — the claim CAS from PEND...
int mizu_pool_task_release(mizu_pool *, const mizu_task *)
The finalizer release for a task handle that was never collected: a still-pending task is cancelled (...
void(* mizu_obj_sink)(void *ctx, size_t i, void *obj)
The sink-callback form of recv_batch: each message is handed to sink as it is read,...
Definition mizu.h:745
size_t mizu_type_elt_size(int type)
Element size of an atomic wire type, 0 for non-atomic.
struct mizu_task_s mizu_task
A task handle: an 8-byte value identifying one result slot at one sequence, with a 40-bit sequence in...
mizu_status mizu_pool_tasks_get(const mizu_pool *, mizu_rs_row *out, uint32_t cap, uint32_t *n_out)
The dump's task table, paged by the caller: fills up to cap rows in slot order (non-FREE slots only) ...
enum mizu_status_e mizu_status
The verb result.
struct mizu_rs_row_s mizu_rs_row
One non-FREE result-slot row (a dump's task table).
mizu_status mizu_pool_stop(mizu_pool *, double timeout_ms)
Orderly shutdown, controller only: broadcasts shutdown, wakes every parked participant,...
#define MIZU_ATOMIC(T)
The wire-format structs carry atomic words.
Definition mizu.h:86
mizu_status mizu_pool_attach(mizu_pool **out, const char *token, const mizu_binding *)
Submitter side: attach joins a live pool from another process, claiming a free submitter slot with it...
void mizu_zc_ref(mizu_shm *)
The consumer side of the zc refcount protocol (header bytes [24-31] of a view-opened region): ref at ...
mizu_trace_event_e
Task lifecycle trace hook: per-handle, per-process; NULL removes.
Definition mizu.h:1011
void *(* mizu_obj_supply)(void *ctx, size_t i)
The supply-callback form of submit_batch: the binding produces task object i on demand,...
Definition mizu.h:948
mizu_kind_e
A 16-byte header then payload bytes, shared by channel slots and pool entries / result slots.
Definition mizu.h:279
char ** mizu_shm_reap(int *n)
Reap /mizu_ orphans of dead creators.
int mizu_pool_task_state(mizu_pool *, const mizu_task *)
MIZU_RS_* of a task (informational, racy against slot reuse): PENDING or RUNNING while outstanding,...
mizu_rs_status_e
PENDING is a submitted, unclaimed task; RUNNING is the claimant's ownership — the claim CAS from PEND...
Definition mizu.h:587
mizu_status mizu_channel_close(mizu_channel *, double timeout_ms)
close signals this side's close bit, then waits up to timeout_ms for the peer's close bit or its deat...
mizu_errcat mizu_channel_errcat(const mizu_channel *)
Handle error access (MIZU_ERR results).
int mizu_pool_cancel(mizu_pool *, const mizu_task *)
Advisory and discard-only, never preemptive: a still-queued (PENDING) task is skipped; an executing (...
enum mizu_kind_e mizu_kind
A 16-byte header then payload bytes, shared by channel slots and pool entries / result slots.
void mizu_channel_destroy(mizu_channel *)
Signal close and release the handle: the close bit is set and the peer woken, then,...
mizu_status mizu_pool_retire(mizu_pool *, uint32_t slot)
Controller only: ask one worker to exit cleanly.
const char * mizu_version(void)
Library version, "major.minor.patch".
mizu_status mizu_channel_send(mizu_channel *, void *obj)
send stages obj with the binding's stage_fn: MIZU_OK, MIZU_FULL (ring full; sends never block for rin...
mizu_status mizu_pool_collect_all_fn(mizu_pool *, const mizu_task *, size_t n, mizu_obj_sink, void *ctx, size_t *err_index_out, size_t *consumed_out, double timeout_ms)
The sink-callback form of collect_all: each value is handed to sink as it is claimed (input order whe...
#define MIZU_MAX_WORKERS
Parked-worker bitmask width; also the map CLAIM array bound.
Definition mizu.h:425
struct mizu_pool_info_s mizu_pool_info
Snapshots.
struct mizu_pool_opts_s mizu_pool_opts
size-stamped options, as the channel's: mizu_pool_opts_init zeroes + stamps, and create refuses a mis...
mizu_status mizu_pool_submit(mizu_pool *, void *task_obj, mizu_task *out, double timeout_ms)
submit stages task_obj with the binding's stage_fn and fills *out.
enum mizu_step_result_e mizu_step_result
One claim at a time, for deterministic in-process harnesses (the pool_pair/pool_step discipline).
mizu_status_e
The verb result.
Definition mizu.h:121
Definition mizu_ext.h:339
Handle-local + wire-state snapshot.
Definition mizu.h:795
uint64_t ledger_entries
process-local
Definition mizu.h:806
uint64_t zc_open_misses
binding-owned view cache; the core fills 0
Definition mizu.h:807
uint64_t open_misses
process-local
Definition mizu.h:805
int32_t side
MIZU_ENTITY_HOST / MIZU_ENTITY_PEER.
Definition mizu.h:798
uint64_t fl_hits
process-local
Definition mizu.h:804
uint64_t notify_sends
process-local: notify endpoint signals sent (armed peers only)
Definition mizu.h:809
size-stamped options; mizu_channel_opts_init zeroes + stamps, and create refuses a struct whose stamp...
Definition mizu.h:676
const uint8_t * drop
peer bootstrap bytes (may be NULL)
Definition mizu.h:682
uint32_t slot_size
bytes per slot, power of two, 64..2^20
Definition mizu.h:679
uint32_t capacity
ring slots, power of two, 2..2^24
Definition mizu.h:678
uint64_t drop_size
their byte count, at most MIZU_DROP_MAX
Definition mizu.h:683
uint64_t arena_size
bytes per direction; 0 disables
Definition mizu.h:680
uint32_t flags
MIZU_FLAG_SPIN; other bits rejected.
Definition mizu.h:681
Injection ring / deque entry header; payload framing at offset 24, payload bytes at 40.
Definition mizu.h:560
uint64_t task_id
submitter slot << 48 | counter; debug only
Definition mizu.h:561
uint64_t rs_seq
result-slot incarnation at submit
Definition mizu.h:562
Definition mizu.h:1096
uint32_t n_submitters
<= 64
Definition mizu.h:1101
uint64_t open_misses
handle-local
Definition mizu.h:1104
uint64_t fl_hits
handle-local
Definition mizu.h:1103
uint64_t ledger_entries
handle-local
Definition mizu.h:1106
uint64_t collect_parks
handle-local
Definition mizu.h:1105
uint64_t notify_sends
handle-local: notify endpoint signals sent (armed submitters only)
Definition mizu.h:1108
uint32_t n_workers
<= MIZU_MAX_WORKERS
Definition mizu.h:1099
Definition mizu.h:427
uint32_t slot
bytes per entry / result slot, power of two
Definition mizu.h:435
uint32_t deque_cap
entries per worker deque, power of two
Definition mizu.h:433
uint32_t result_slots
total; a multiple of max_submitters
Definition mizu.h:434
uint32_t max_workers
<= MIZU_MAX_WORKERS
Definition mizu.h:430
uint64_t owner_pid
the workers' death-listener watch target
Definition mizu.h:436
uint32_t max_submitters
<= 64: inj_ready_sub / full_waiters bits
Definition mizu.h:431
uint32_t inj_cap
entries per submitter ring, power of two
Definition mizu.h:432
uint64_t worker_ident
The workers' identity word (MIZU_IDENT in mizu_ext.h): 0 until the first worker join CASes its bindin...
Definition mizu.h:445
Snapshots.
Definition mizu.h:1059
int32_t role
MIZU_ROLE_*.
Definition mizu.h:1062
uint8_t sub_state[64]
MIZU_SUB_*.
Definition mizu.h:1067
uint8_t worker_state[MIZU_MAX_WORKERS]
MIZU_WK_*.
Definition mizu.h:1066
uint64_t parked_mask
one bit per worker slot
Definition mizu.h:1069
uint32_t tasks_by_state[8]
occupancy indexed by MIZU_RS_*
Definition mizu.h:1070
uint32_t inj_queued[64]
unclaimed injection entries
Definition mizu.h:1071
int64_t deque_depth[MIZU_MAX_WORKERS]
bottom - top
Definition mizu.h:1068
size-stamped options, as the channel's: mizu_pool_opts_init zeroes + stamps, and create refuses a mis...
Definition mizu.h:825
uint32_t max_submitters
<= 64
Definition mizu.h:828
uint32_t max_workers
<= MIZU_MAX_WORKERS
Definition mizu.h:827
uint32_t slot_size
bytes per entry / result slot, pow2, 128..2^20
Definition mizu.h:832
uint32_t injection_cap
entries per submitter ring, power of two
Definition mizu.h:829
uint32_t per_worker_cap
deque entries per worker, power of two
Definition mizu.h:830
uint32_t result_slots
rounded up to a multiple of max_submitters
Definition mizu.h:831
Definition mizu.h:177
uint64_t drop_size
their exact byte count (at most MIZU_DROP_MAX)
Definition mizu.h:186
uint64_t arena_size
bytes per direction, multiple of 128, 0 disables
Definition mizu.h:183
uint64_t livedir_offset
directory holding the two liveness files
Definition mizu.h:187
uint32_t version
MIZU_ABI_VERSION.
Definition mizu.h:179
uint32_t cap
slots per ring, power of two
Definition mizu.h:180
uint32_t slot
slot size in bytes, power of two
Definition mizu.h:181
uint64_t host_pid
the peer death listener's watch target
Definition mizu.h:182
uint64_t drop_offset
the peer bootstrap bytes: opaque to the core, tagged by binding convention (MIZU_DROP_*)
Definition mizu.h:184
Definition mizu.h:541
int32_t waiter_slot
submitter slot parked on this (-1; MIZU_WS_NOTIFY OR'd when the wake is a notify signal)
Definition mizu.h:544
uint64_t state
sequence << 11 | (claimant + 1) << 4 | MIZU_RS_*
Definition mizu.h:542
int64_t claimant_pid
the claimant's pid; a reaper stores the dead worker's ahead of DIED (0 = never claimed)
Definition mizu.h:547
One non-FREE result-slot row (a dump's task table).
Definition mizu.h:1113
int32_t status
MIZU_RS_*.
Definition mizu.h:1115
The public opaque type in mizu.h; defined here for bindings (the core's control-region mappings embed...
Definition mizu_ext.h:515
Definition mizu.h:311
uint32_t kind
mizu_kind
Definition mizu.h:312
Submitter registry slot: one 128-byte span per submitter.
Definition mizu.h:487
int32_t status
MIZU_SUB_*.
Definition mizu.h:488
uint64_t live_ino
liveness-file inode
Definition mizu.h:498
uint32_t notify
the submitter's notify-arm bitmask (MIZU_WAIT_*; the coalescing word the first publisher per burst cl...
Definition mizu.h:501
uint32_t rs_start
The static result-slot partition: result_slots / max_submitters slots per submitter,...
Definition mizu.h:495
uint64_t live_dev
liveness-file device (as the worker's)
Definition mizu.h:497
uint32_t rs_count
slots in the partition
Definition mizu.h:496
Definition mizu.h:1086
int32_t ready
its inj_ready bit
Definition mizu.h:1092
int32_t full_waiter
its full_waiters bit
Definition mizu.h:1093
int32_t status
MIZU_SUB_*.
Definition mizu.h:1087
uint64_t claimed
ring tail / head, monotonic from 0
Definition mizu.h:1090
uint32_t rs_count
the static result-slot partition
Definition mizu.h:1089
uint64_t spill_reuse
SHM_RAW-class staging counters.
Definition mizu.h:1091
A task handle: an 8-byte value identifying one result slot at one sequence, with a 40-bit sequence in...
Definition mizu.h:843
Worker registry slot: two 128-byte spans, with the admin and owner-written fields on the first and th...
Definition mizu.h:455
int32_t status
MIZU_WK_*.
Definition mizu.h:456
int64_t pid
informational; never a liveness signal
Definition mizu.h:458
uint8_t pad1[64]
deque_top off the owner's span
Definition mizu.h:468
uint64_t live_ino
liveness-file inode
Definition mizu.h:473
uint64_t live_dev
The liveness-file identity (device, inode), written once at join before LIVE; a by-path prober identi...
Definition mizu.h:472
int32_t park_state
MIZU_WPK_*.
Definition mizu.h:459
Definition mizu.h:1078