# libmembus

C++17 POSIX shared memory IPC library.

Circular ring buffer with multi-reader broadcast. Bytes in, bytes out.
No routing, parsing, or protocol logic.

## Build

```bash
make              # Build libmembus.a
make test         # Build and run all 45 tests
make install      # Install to /usr/local (sudo required)
make clean        # Remove build artifacts
```

Requires: `g++` with C++17 support. Linux only (futex, POSIX SHM).

## API

Single public header: `#include <membus/membus.hpp>`

```cpp
membus::create("bus_name");                // Create bus (size defaults to DEFAULT_SIZE)
membus::create("bus_name", 65536);         // ...or state the size explicitly
membus::Bus bus("bus_name");               // Open + register reader
bus.set_reader_name("ingest");             // Label this reader slot (debug aid)
bus.write(data, len);                      // Write (lossy, never blocks)
bus.read(buf, len);                        // Non-blocking read
bus.read_wait(buf, len, timeout_ms);       // Blocking read (futex)
// ~Bus() cleans up reader slot (RAII)
membus::destroy("bus_name");               // Unlink SHM
```

All six public calls are shown. `set_reader_name` truncates to
`READER_NAME_LEN - 1` (31 characters) — see `docs/MEMBUS_SPEC.md` section 8.7.
`65536` above is `membus::DEFAULT_SIZE`; the parameter is defaulted, so the first
form is the one to reach for.

## Design

- **Lossy**: Writers never block. Slow readers are silently advanced.
- **Multi-reader**: Up to 32 concurrent readers per bus, each with independent cursor.
- **Crash-safe**: Robust mutexes recover from process death. Dead slots reclaimed.
- **Zero-poll**: Blocking reads use Linux futex (no polling).
- **SHM naming**: Bus `"foo"` maps to `/dev/shm/foo_shm`
- **Buffer**: Circular, wraps at boundaries. Usable capacity = `size - 1` bytes.

See `docs/MEMBUS_SPEC.md` for the full specification.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for coding standards and how to contribute.

## License

MIT License — see [LICENSE](LICENSE).