These notes describe the implementation decisions behind BufferQueue. They are intended for maintainers and users who need to understand the queue model, delivery behavior, storage boundaries, and persistence guarantees beyond the public API examples.
Start with the repository overview for package installation and runnable usage. The articles below describe the checked-in implementation and complement the package READMEs.
| Article | Focus |
|---|---|
| Architecture and registrations | Public model, project boundaries, shared queue abstractions, dependency injection, extension points, and test coverage. |
| Consumer model and delivery | Pull and push consumers, asynchronous wake-up, commits, scopes, and at-least-once behavior. |
| Partitioning and concurrency | Consumer groups, partition assignment, key routing, ordering, and in-process concurrency rules. |
| Memory storage | Segmented in-memory storage, append and read paths, recycling, and bounded capacity. |
| MemoryMappedFile storage | Durable segment layout, serialization, flush boundaries, recovery, checkpoints, and retention. |
Read architecture and registrations first to understand what is shared between storage implementations. Continue with the consumer model and partitioning and concurrency before changing shared queue behavior. Read the storage article that matches the implementation being changed: Memory or MemoryMappedFile.
BufferQueue supports concurrent production and consumption within one process. MemoryMappedFile is local durable storage for one active queue instance; it does not coordinate writers across processes. Persisted topics require compatible partition routing and serializer schemas across restarts.
The previous monolithic entry point remains available at docs/design.md as a backward-compatible index.