burkey.co /docs/ libflint/
index
~/docs/libflint/
docs

Libflint

36 modules·4 groups

libflint is a C library of containers and helpers for Linux, macOS, OpenBSD, and FreeBSD. Container handles are generally caller-owned; pointer containers store void * payloads. Each module page covers ownership, return codes, and examples.

Modules#

Data Structures#

  • linkedlist: Doubly-linked list of void *. Foundation for stack, queue, and set
  • vector: Growable array of void *
  • darray: Growable array of trivially copyable elements stored inline
  • stack: LIFO stack of void *
  • heap: Comparator-ordered pointer priority queue
  • queue: Unbounded FIFO queue
  • set: Small unique collection. Membership is linear
  • hashmap: Generic key/value map with independent key and value ownership
  • slotmap: Open-addressed integer map and generational slot ids
  • hashset: Unique collection with hashed membership
  • intern: Interned byte strings. Equal bytes share one stable pointer until destroy
  • binarytree: Binary tree of void * payloads, built by attaching children
  • bst: Unbalanced ordered binary search tree (insert, find, remove)
  • ringbuf: Fixed-capacity FIFO of void *. No allocation after init
  • bytering: Byte ring with caller-provided storage and atomic indices for one producer and one consumer. Lock-free operation depends on the target
  • statemachine: Table-driven finite state machine with guards and entry/exit callbacks

Allocators#

  • memory: Arena (bump allocation with save/restore) and pool (fixed-size chunks)

Utilities#

  • strbuf: Owned growable string builder
  • parse: Integer and token parsing from borrowed string views
  • string: lfstr_* helpers and LfStr views
  • math: Integer helpers, checked int32_t arithmetic, LfPoint, and Bresenham
  • rng: Seeded xoshiro256** stream of uint64_t
  • bytebuf: Bounded binary cursor with explicit byte order
  • codec: Hex and Base64 (encoding, not cryptography)
  • puzzle: Repeating-key XOR, Hamming distance, English scoring
  • crypto: Includes codec and puzzle
  • sha256: FIPS 180-4 SHA-256 of a byte span. Not declared from lfcrypto.h (that header is codecs and puzzle bytes)
  • input: Read a regular, seekable file into memory
  • dir: POSIX directory walk and single-separator path join
  • process: lf_capture_system (popen; the command is not sanitized)
  • bitset: Runtime-sized compact bit array
  • bitops: Macros to set, clear, toggle, test, extract, and insert bit fields

Platform#

  • network: IPv4 lf_listen_tcp, lf_bind_udp, and lf_close
  • macos: Process CPU and memory sampling (Apple only)
  • compat: Overflow-checked lf_reallocarray on every platform

Requirements#

CMake 3.17 or newer and a C11 compiler. The build requires C11, including <stdatomic.h> and atomic_size_t for bytering.

Linux needs the libbsd headers and library (strtonum in the input module). macOS, OpenBSD, and FreeBSD need no extra libraries.

Building and Testing#

From the repository root:

cmake -S . -B build
cmake --build build
ctest --test-dir build --output-on-failure

The root Makefile is a thin wrapper around CMake. Tests are built when libflint is the top-level project; the files under tests/ also provide usage examples. Use ctest --test-dir build --parallel to run tests in parallel, or add --label-exclude slow to skip the slow macOS sampling test.

TEST(name) in test names the following block in include/lftest.h; a failing assert prints that name, and a passing block prints nothing.

Compiler warnings are enabled by default for GCC and Clang (FLINT_ENABLE_WARNINGS=ON). To run with AddressSanitizer and UndefinedBehaviorSanitizer on a compiler that supports them:

cmake -S . -B build-sanitize -DCMAKE_BUILD_TYPE=Debug -DFLINT_SANITIZE=ON
cmake --build build-sanitize
ctest --test-dir build-sanitize --output-on-failure --label-exclude slow

Using libflint with CMake#

If the library is checked out at lib/libflint inside your project:

add_subdirectory(lib/libflint)
target_link_libraries(your_target PRIVATE flint)

Replace your_target with an existing CMake target. The flint target exports its include/ directory; include the headers for the modules you use, such as lfvector.h or lfhashmap.h. Its private compile definitions do not propagate to your project.

Memory Management#

The caller allocates the handle (List, Vector, and so on). The library allocates internal nodes and buffers. A destroy callback frees owned payloads on destroy or clear. Pop and remove transfer the payload to the caller and do not call that callback. Binary tree subtree removal does destroy payloads, and hash map replacement can destroy the old key and value. The module page states which operations do which.

Why the name 'libflint'?#

libflint is named after my dog Flint, who passed away in 2021. I miss you, buddy.

flint