Crate libsplinter_sys 

Native FFI bindings to libsplinter, the shared-memory splinter core (in-memory variant).

This is a -sys crate: it exposes the raw, auto-generated C ABI and nothing more. The vendored C sources are compiled from source by the build script, so no system installation of libsplinter is required. Bindings are generated with bindgen at build time and written to OUT_DIR.

Structs

__fsid_t

atomic_flag

max_align_t

splinter_event_bus

@brief Event bus for kernel-assisted epoch-change notifications via eventfd.

splinter_header

@struct splinter_header @brief Defines the header structure for the shared memory region.

splinter_header_snapshot

@struct splinter_header_snapshot @brief structure to hold splinter bus snapshots

splinter_shard_bid

@brief One cooperative-memory-scheduling bid. 32 of these live in the header. Packed to ~32 bytes so all 32 fit in ~1 KB (intentionally NOT individually cache-line aligned: claims/releases are rare and elections are read-only, so false sharing on this table is a non-issue, and the thesis budgets ~1 KB, not 2 KB).

splinter_shard_bid_snapshot

@struct splinter_shard_bid_snapshot @brief Non-atomic mirror of a single bid slot for inspection/audit.

splinter_signal_node

@brief Individual signal lane, aligned to prevent false sharing.

splinter_slot

@struct splinter_slot @brief Defines a single key-value slot in the hash table.

splinter_slot_snapshot

@structure splinter_slot_snapshot @brief A structure to hold a snapshot of a single slot

Constants

INT8_MAX

INT8_MIN

INT16_MAX

INT16_MIN

INT32_MAX

INT32_MIN

INTPTR_MAX

INTPTR_MIN

INT_FAST8_MAX

INT_FAST8_MIN

INT_FAST16_MAX

INT_FAST16_MIN

INT_FAST32_MAX

INT_FAST32_MIN

INT_LEAST8_MAX

INT_LEAST8_MIN

INT_LEAST16_MAX

INT_LEAST16_MIN

INT_LEAST32_MAX

INT_LEAST32_MIN

NS_PER_MS

PTRDIFF_MAX

PTRDIFF_MIN

SIG_ATOMIC_MAX

SIG_ATOMIC_MIN

SIZE_MAX

SPLINTER_EVENT_BUS_MASK_WORDS

SPLINTER_KEY_MAX

SPLINTER_MAGIC

SPLINTER_MAX_GROUPS

SPLINTER_MAX_SHARDS

SPLINTER_MAX_SLOTS

SPLINTER_VER

SPL_FUSR1

SPL_FUSR2

SPL_FUSR3

SPL_FUSR4

SPL_FUSR5

SPL_FUSR6

SPL_FUSR7

SPL_FUSR8

SPL_ORDER_ACCESSOR

SPL_SLOT_DEFAULT_TYPE

SPL_SLOT_TYPE_AUDIO

SPL_SLOT_TYPE_BIGINT

SPL_SLOT_TYPE_BIGUINT

SPL_SLOT_TYPE_BINARY

SPL_SLOT_TYPE_IMGDATA

SPL_SLOT_TYPE_JSON

SPL_SLOT_TYPE_VARTEXT

SPL_SLOT_TYPE_VOID

SPL_SUSR1

SPL_SUSR2

SPL_SUSR3

SPL_SUSR4

SPL_SYS_AUTO_SCRUB

SPL_SYS_HYBRID_SCRUB

SPL_SYS_RESERVED_2

SPL_SYS_RESERVED_3

SPL_TIME_ATIME

SPL_TIME_CTIME

UINT8_MAX

UINT16_MAX

UINT32_MAX

UINTPTR_MAX

UINT_FAST8_MAX

UINT_FAST16_MAX

UINT_FAST32_MAX

UINT_LEAST8_MAX

UINT_LEAST16_MAX

UINT_LEAST32_MAX

WINT_MAX

WINT_MIN

_ATFILE_SOURCE

_BITS_STDINT_INTN_H

_BITS_STDINT_LEAST_H

_BITS_STDINT_UINTN_H

_BITS_TIME64_H

_BITS_TYPESIZES_H

_BITS_TYPES_H

_BITS_WCHAR_H

_DEFAULT_SOURCE

_FEATURES_H

_POSIX_C_SOURCE

_POSIX_SOURCE

_STDC_PREDEF_H

_STDINT_H

_SYS_CDEFS_H

__FD_SETSIZE

__GLIBC_MINOR__

__GLIBC_USE_C2X_STRTOL

__GLIBC_USE_DEPRECATED_GETS

__GLIBC_USE_DEPRECATED_SCANF

__GLIBC_USE_IEC_60559_BFP_EXT

__GLIBC_USE_IEC_60559_BFP_EXT_C2X

__GLIBC_USE_IEC_60559_EXT

__GLIBC_USE_IEC_60559_FUNCS_EXT

__GLIBC_USE_IEC_60559_FUNCS_EXT_C2X

__GLIBC_USE_IEC_60559_TYPES_EXT

__GLIBC_USE_ISOC2X

__GLIBC_USE_LIB_EXT2

__GLIBC__

__GNU_LIBRARY__

__HAVE_GENERIC_SELECTION

__INO_T_MATCHES_INO64_T

__KERNEL_OLD_TIMEVAL_MATCHES_TIMEVAL64

__LDOUBLE_REDIRECTS_TO_FLOAT128_ABI

__OFF_T_MATCHES_OFF64_T

__RLIM_T_MATCHES_RLIM64_T

__STATFS_MATCHES_STATFS64

__STDC_IEC_559_COMPLEX__

__STDC_IEC_559__

__STDC_IEC_60559_BFP__

__STDC_IEC_60559_COMPLEX__

__STDC_ISO_10646__

__SYSCALL_WORDSIZE

__TIMESIZE

__USE_ATFILE

__USE_FORTIFY_LEVEL

__USE_ISOC11

__USE_ISOC95

__USE_ISOC99

__USE_MISC

__USE_POSIX

__USE_POSIX2

__USE_POSIX199309

__USE_POSIX199506

__USE_POSIX_IMPLICITLY

__USE_XOPEN2K

__USE_XOPEN2K8

__WORDSIZE

__WORDSIZE_TIME64_COMPAT32

__alignas_is_defined

__alignof_is_defined

__glibc_c99_flexarr_available

memory_order_memory_order_acq_rel

memory_order_memory_order_acquire

memory_order_memory_order_consume

memory_order_memory_order_relaxed

memory_order_memory_order_release

memory_order_memory_order_seq_cst

splinter_integer_op_t_SPL_OP_AND

splinter_integer_op_t_SPL_OP_DEC

splinter_integer_op_t_SPL_OP_INC

splinter_integer_op_t_SPL_OP_NOT

splinter_integer_op_t_SPL_OP_OR

splinter_integer_op_t_SPL_OP_XOR

splinter_intent_t_SPL_INTENT_DONTNEED

splinter_intent_t_SPL_INTENT_NONE

splinter_intent_t_SPL_INTENT_RANDOM

splinter_intent_t_SPL_INTENT_SEQUENTIAL

splinter_intent_t_SPL_INTENT_WILLNEED

Functions

atomic_flag_clear^⚠

atomic_flag_clear_explicit^⚠

atomic_flag_test_and_set^⚠

atomic_flag_test_and_set_explicit^⚠

atomic_signal_fence^⚠

atomic_thread_fence^⚠

splinter_append^⚠

@brief Appends data to an existing key’s value in-place. @param key The null-terminated key string. @param data Pointer to the data to append. @param data_len Number of bytes to append. @param new_len Output: set to the new total value length on success. May be NULL. @return 0 on success, -1 if key not found or overflow, -2 if args invalid.

splinter_bump_slot^⚠

@brief Advance the epoch of a slot without otherwise doing work Useful in conjunction with labeling for automation to fire. @param key Current key name associated with the slot.

splinter_client_set_tandem^⚠

@brief Client-side helper to write multiple orders of a key. This helper manages the naming convention for the caller. It uses a temporary array to copy the “victim” keys. @param base_key The main key (e.g. car) @param vals An array of values from keys that will be merged in @param lens An array of lengths corresponding with vals @param orders How many tandems to create @return 0 on success, -1 on failure, -2 if underlying basic I/O calls fail

splinter_client_unset_tandem^⚠

@brief Client-side helper to delete a key and its known orders.

splinter_close^⚠

@brief Closes the splinter store and unmaps the shared memory region.

splinter_config_clear^⚠

@brief Clear a bus configuration value @param hdr: a splinter bus header structure @param mask: bitmask to clear

splinter_config_set^⚠

@brief Set a bus configuration value @param hdr: a splinter bus header structure @param mask: bitmask to apply

splinter_config_snapshot^⚠

@brief Snapshot a bus configuration @param hdr: a splinter bus header structure

splinter_config_test^⚠

@brief Test a bus configuration value @param hdr: a splinter bus header structure @param mask: bitmask to test

splinter_create^⚠

@brief Creates and initializes a new splinter store. @param name_or_path The name of the shared memory object or path to the file. @param slots The total number of key-value slots to allocate. @param max_value_sz The maximum size in bytes for any single value. @return 0 on success, -1 on failure (e.g., store already exists). @note Creation is exclusive (O_EXCL): if a store of the same name/path already exists this fails (errno EEXIST) rather than adopting or reinitializing it. In persistent mode the path is also opened O_NOFOLLOW, so a symlink planted at that path is refused. Use splinter_open() to attach to an existing store, or splinter_create_or_open() to do either. @note The store is created with mode 0666 masked by the process umask, so by default it inherits the shell’s umask (often world-readable on GNU systems). Set SPLINTER_DEFAULT_UMASK in the environment to an octal mask (e.g. “077” for a private 0600 store) to override this at creation time; adjust further with chmod afterward. Applies to persistent mode too.

splinter_create_or_open^⚠

@brief Creates a new splinter store, or opens it if it already exists. @param name_or_path The name of the shared memory object or path to the file. @param slots The total number of key-value slots if creating. @param max_value_sz The maximum value size in bytes if creating. @return 0 on success, -1 on failure.

splinter_enumerate_matches^⚠

@brief Iterates through all slots matching a bloom mask. @param mask The bloom mask to match against. @param callback Function to call for each match. @param user_data Opaque pointer for the callback.

splinter_event_bus_close^⚠

@brief Close a fd obtained from splinter_event_bus_open(). @param fd The fd to close.

splinter_event_bus_get_dirty^⚠

@brief Copy a snapshot of the dirty-slot bitmask into caller-supplied storage.

splinter_event_bus_init^⚠

@brief Initialize the event bus (owner process only).

splinter_event_bus_open^⚠

@brief Open a process-local read fd to the owner’s eventfd.

splinter_event_bus_wait^⚠

@brief Block until the global epoch changes or the timeout expires.

splinter_get^⚠

@brief Retrieves the value associated with a key. @param key The null-terminated key string. @param buf The buffer to copy the value data into. Can be NULL to query size. @param buf_sz The size of the provided buffer. @param out_sz Pointer to a size_t to store the value’s actual length. Can be NULL. @return 0 on success, -1 on failure. If buf_sz is too small, sets errno to EMSGSIZE.

splinter_get_epoch^⚠

@brief Get the current epoch of a specific slot. @return The 64-bit epoch, or 0 if key not found.

splinter_get_header_snapshot^⚠

@brief Copy the current atomic Splinter header structure into a corresponding non-atomic client version. @param snapshot A splinter_header_snaphshot_t structure to receive the values. @return -1 on failure, 0 on success.

splinter_get_mop^⚠

@brief Get the current “mop mode” @return 0 = off, 1 = hybrid, 2 = full boil. -2 = no store.

splinter_get_raw_ptr^⚠

@brief Get a direct pointer to a value in shared memory. @warning Unsafe: The data at this pointer can change or be zeroed if a writer modifies the slot. Use splinter_get_epoch to verify consistency. @param key The key to look up. @param out_sz Pointer to receive the actual length of the value. @param out_epoch Pointer to receive the epoch at the time of lookup. @return A const pointer to the data in SHM, or NULL if not found.

splinter_get_signal_count^⚠

@brief Safely retrieve the current pulse count for a signal group. Good for debugging. @param group_id The signal group (0-63). @return The 64-bit pulse count, or 0 if invalid.

splinter_get_slot_snapshot^⚠

@brief Copy the current atomic Splinter slot header to a corresponding client structure. @param snapshot A splinter_slot_snaphshot_t structure to receive the values. @return -1 on failure, 0 on success.

splinter_integer_op^⚠

@brief Bitwise & arithmetic ops on keys named as big unsigned @param key Name of the key to operate on @param op Operation you want to do @param mask What you want to do it with @return 0 on success, -1 / -2 on internal / caller errors respectively

splinter_list^⚠

@brief Lists all keys currently in the store. @param out_keys An array of char* to be filled with pointers to the keys. @param max_keys The maximum number of keys to write to out_keys. @param out_count Pointer to a size_t to store the number of keys found. @return 0 on success, -1 on failure.

splinter_madvise^⚠

@brief Cooperative posix_madvise(): the voluntary-yield entry point.

splinter_open^⚠

@brief Opens an existing splinter store. @param name_or_path The name of the shared memory object or path to the file. @return 0 on success, -1 on failure (e.g., store does not exist).

splinter_open_or_create^⚠

@brief Opens an existing splinter store, or creates it if it does not exist. @param name_or_path The name of the shared memory object or path to the file. @param slots The total number of key-value slots if creating. @param max_value_sz The maximum value size in bytes if creating. @return 0 on success, -1 on failure.

splinter_poll^⚠

@brief Waits for a key’s value to be changed. @param key The key to monitor for changes. @param timeout_ms The maximum time to wait in milliseconds. @return 0 if the value changed, -1 on timeout or if the key doesn’t exist.

splinter_pulse_keygroup^⚠

@brief Pulse a key group by one of its members (if known) @param key string key to find @return 0 on success, -2 on system failure, -1 if key is not found

splinter_pulse_watchers^⚠

@brief Internal helper to pulse the Signal Arena for a slot. @param slot pointer to a splinter_slot structure

splinter_purge^⚠

@brief Check each key, and zero out memory past the value length to the allocated slot length (essentially sweep out any old data). Designed to be used as part of backfill runs when I/O slamming has stopped.

splinter_retrain_slot^⚠

@brief Reset a slot for retraining: scrub its vectors and republish.

splinter_set^⚠

@brief Sets or updates a key-value pair in the store. @param key The null-terminated key string. @param val Pointer to the value data. @param len The length of the value data. Must not exceed max_val_sz. @return 0 on success, -1 on failure (e.g., store is full).

splinter_set_as_system^⚠

@brief Promotes a key to “system” usage @param key the key to scope

splinter_set_label^⚠

@brief Atomically apply a label mask to a slot’s Bloom filter. @return 0 on success, -1 if key not found.

splinter_set_mop^⚠

@brief Control Splinter’s mop mode. @param unsigned mode: 0 = off, 1 = hybrid, 2 = full boil. @return 0 on success, -1 on invalid mode, -2 if something is wrong with the store This will replace all _av() functions.

splinter_set_named_type^⚠

@brief Name (declare intent to) a type fo a slot @param key Name of the key to change @param mask Splinter type bitmask to apply (e.g SPL_SLOT_TYPE_BIGUINT) @return -1 or on error (sets errno), 0 on success

splinter_set_slot_time^⚠

@brief Update a slot’s ctime / atime @param key Name of the key to change @param mode (SPL_TIME_CTIME or SPL_TIME_ATIME) @param epoch client-supplied timestamp @param offset value to subtract from epoch due to update-after-write @return -1/-2 or on error (sets errno), 0 on success

splinter_shard_claim^⚠

@brief Claim a shard bid slot and declare memory intent.

splinter_shard_claim_ex^⚠

@brief Advanced/testing claim: explicit pid and claimed_at.

splinter_shard_election^⚠

@brief Run the read-only election scan and return the current sovereign.

splinter_shard_is_sovereign^⚠

@brief Convenience: is shard_id the current sovereign? @return 1 if sovereign, 0 if not (including unknown/expired), -2 on no store.

splinter_shard_rebid^⚠

@brief Refresh (re-bid) an existing claim’s window. Updates claimed_at to splinter_now() and optionally changes intent/priority/duration. This is the fairness re-bid: a shard that needs more time must re-bid rather than hold. @return 0 on success, -1 if shard_id holds no slot, -2 on bad args.

splinter_shard_release^⚠

@brief Voluntarily release (yield) the caller’s bid slot. Zeroes shard_id (marking the slot empty) last, after clearing the other fields. @return 0 on success, -1 if shard_id holds no slot, -2 on bad args/no store.

splinter_shard_table_snapshot^⚠

@brief Copy a non-atomic snapshot of every bid slot for inspection/audit. @param out Array of at least SPLINTER_MAX_SHARDS records. @param max Capacity of out (capped at SPLINTER_MAX_SHARDS). @return number of records copied, or -2 on bad args/no store.

splinter_slot_usr_clear^⚠

@brief Clear a user slot flag @param slot Splinter slot structure @param mask bitmask to clear

splinter_slot_usr_set^⚠

@brief Set a user slot flag @param slot Splinter slot structure @param mask bitmask to set

splinter_slot_usr_snapshot^⚠

@brief Get a user slot flag snapshot @param slot Splinter slot structure

splinter_slot_usr_test^⚠

@brief Test a user slot flag @param slot Splinter slot structure @param mask bitmask to test

splinter_unset^⚠

@brief “unsets” a key. This function does one atomic operation to zero the slot hash, which marks the slot available for write. It then zeroes out the used key and value regions, and resets the slot.

splinter_unset_label^⚠

@brief Atomically remove a previously applied bloom label @return 0 on success, negative on failure

splinter_watch_label_register^⚠

@brief Maps a Bloom label (bitmask) to a signal group.

splinter_watch_register^⚠

@brief Registers interest in a key’s group signal.

splinter_watch_unregister^⚠

@brief Unregisters interest in a key’s group signal.

Type Aliases

__blkcnt64_t

__blkcnt_t

__blksize_t

__caddr_t

__clock_t

__clockid_t

__daddr_t

__dev_t

__fsblkcnt64_t

__fsblkcnt_t

__fsfilcnt64_t

__fsfilcnt_t

__fsword_t

__gid_t

__id_t

__ino64_t

__ino_t

__int8_t

__int16_t

__int32_t

__int64_t

__int_least8_t

__int_least16_t

__int_least32_t

__int_least64_t

__intmax_t

__intptr_t

__key_t

__loff_t

__mode_t

__nlink_t

__off64_t

__off_t

__pid_t

__quad_t

__rlim64_t

__rlim_t

__sig_atomic_t

__socklen_t

__ssize_t

__suseconds64_t

__suseconds_t

__syscall_slong_t

__syscall_ulong_t

__time_t

__timer_t

__u_char

__u_int

__u_long

__u_quad_t

__u_short

__uid_t

__uint8_t

__uint16_t

__uint32_t

__uint64_t

__uint_least8_t

__uint_least16_t

__uint_least32_t

__uint_least64_t

__uintmax_t

__useconds_t

atomic_bool

atomic_char

atomic_char16_t

atomic_char32_t

atomic_int

atomic_int_fast8_t

atomic_int_fast16_t

atomic_int_fast32_t

atomic_int_fast64_t

atomic_int_least8_t

atomic_int_least16_t

atomic_int_least32_t

atomic_int_least64_t

atomic_intmax_t

atomic_intptr_t

atomic_llong

atomic_long

atomic_ptrdiff_t

atomic_schar

atomic_short

atomic_size_t

atomic_uchar

atomic_uint

atomic_uint_fast8_t

atomic_uint_fast16_t

atomic_uint_fast32_t

atomic_uint_fast64_t

atomic_uint_least8_t

atomic_uint_least16_t

atomic_uint_least32_t

atomic_uint_least64_t

atomic_uintmax_t

atomic_uintptr_t

atomic_ullong

atomic_ulong

atomic_ushort

atomic_wchar_t

int_fast8_t

int_fast16_t

int_fast32_t

int_fast64_t

int_least8_t

int_least16_t

int_least32_t

int_least64_t

intmax_t

memory_order

splinter_header_snapshot_t

@struct splinter_header_snapshot @brief structure to hold splinter bus snapshots

splinter_integer_op_t

@brief for atomic integer operations

splinter_intent_t

@brief Memory-intent classes for a shard bid (the intent field). These mirror the POSIX_MADV_* advice classes. SPL_INTENT_NONE marks a record whose owner has not yet declared (or has cleared) its intent. DONTNEED is accepted as a bid but is governed by the soft bumper in splinter_shard_election(): it cannot win while live WILLNEED/SEQUENTIAL bids exist.

splinter_slot_snapshot_t

@structure splinter_slot_snapshot @brief A structure to hold a snapshot of a single slot

uint_fast8_t

uint_fast16_t

uint_fast32_t

uint_fast64_t

uint_least8_t

uint_least16_t

uint_least32_t

uint_least64_t

uintmax_t

wchar_t