{"id":28376876,"url":"https://github.com/ebwi11/mmap_ringbuffer","last_synced_at":"2025-08-20T09:05:11.729Z","repository":{"id":294858107,"uuid":"988172551","full_name":"EBWi11/mmap_ringbuffer","owner":"EBWi11","description":"A high-performance, memory-mapped ring buffer implementation in Go, designed for efficient inter-process or inter-thread communication. This library provides a lock-free (with minimal locking) ring buffer backed by memory-mapped files, making it suitable for high-throughput scenarios.","archived":false,"fork":false,"pushed_at":"2025-05-23T06:32:09.000Z","size":6,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-30T00:37:19.329Z","etag":null,"topics":["ringbuffer"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/EBWi11.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-22T06:53:50.000Z","updated_at":"2025-05-28T06:27:06.000Z","dependencies_parsed_at":"2025-05-22T12:41:52.866Z","dependency_job_id":"b53a2324-88fc-46a3-89cc-f11205fa704a","html_url":"https://github.com/EBWi11/mmap_ringbuffer","commit_stats":null,"previous_names":["ebwi11/mmap_ringbuffer"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/EBWi11/mmap_ringbuffer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EBWi11%2Fmmap_ringbuffer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EBWi11%2Fmmap_ringbuffer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EBWi11%2Fmmap_ringbuffer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EBWi11%2Fmmap_ringbuffer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/EBWi11","download_url":"https://codeload.github.com/EBWi11/mmap_ringbuffer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/EBWi11%2Fmmap_ringbuffer/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262084607,"owners_count":23256268,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ringbuffer"],"created_at":"2025-05-30T00:30:24.109Z","updated_at":"2025-06-26T14:31:09.794Z","avatar_url":"https://github.com/EBWi11.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mmap_ringbuffer\n\nA high-performance, memory-mapped ring buffer implementation in Go, designed for efficient inter-process or inter-thread communication. This library provides a lock-free (with minimal locking) ring buffer backed by memory-mapped files, making it suitable for high-throughput scenarios.\n\n## Features\n\n- Memory-mapped file as a shared ring buffer\n- Minimal locking for write operations\n- Efficient for high message throughput\n\n## Installation\n\n```bash\ngo get github.com/EBWi11/mmap_ringbuffer\n```\n\n## Usage\n\n### Basic Example\n\n```go\npackage main\n\nimport (\n    \"fmt\"\n    \"github.com/EBWi11/mmap_ringbuffer\"\n)\n\nfunc main() {\n    // Create a new ring buffer with 1MB size\n    rb, err := ringbuffer.NewRingBuffer(\"/tmp/rb.mmap\", 1024*1024, true)\n    if err != nil {\n        panic(err)\n    }\n    defer rb.Close()\n\n    // Write a message\n    msg := []byte(\"hello, mmap ringbuffer!\")\n    ok, err := rb.WriteMsg(msg)\n    if ok \u0026\u0026 err == nil {\n        fmt.Println(\"Message written successfully\")\n    }\n\n    // Read a message\n    readMsg, err := rb.ReadMsg()\n    if err == nil {\n        fmt.Printf(\"Read message: %s\\n\", string(readMsg))\n    }\n}\n```\n\n### Producer-Consumer Example\n\n```go\npackage main\n\nimport (\n    \"fmt\"\n    \"sync\"\n    \"github.com/EBWi11/mmap_ringbuffer\"\n)\n\nfunc producer(rb *ringbuffer.RingBuffer, wg *sync.WaitGroup) {\n    defer wg.Done()\n    \n    for i := 0; i \u003c 1000; i++ {\n        msg := []byte(fmt.Sprintf(\"message-%d\", i))\n        ok, err := rb.WriteMsg(msg)\n        if !ok || err != nil {\n            fmt.Printf(\"Failed to write: %v\\n\", err)\n            return\n        }\n    }\n}\n\nfunc consumer(rb *ringbuffer.RingBuffer, wg *sync.WaitGroup) {\n    defer wg.Done()\n    \n    for {\n        msg, err := rb.ReadMsg()\n        if err == ringbuffer.ErrBufferEmpty {\n            continue\n        }\n        if err != nil {\n            fmt.Printf(\"Failed to read: %v\\n\", err)\n            return\n        }\n        fmt.Printf(\"Received: %s\\n\", string(msg))\n    }\n}\n\nfunc main() {\n    rb, err := ringbuffer.NewRingBuffer(\"/tmp/rb.mmap\", 1024*1024, true)\n    if err != nil {\n        panic(err)\n    }\n    defer rb.Close()\n\n    var wg sync.WaitGroup\n    wg.Add(2)\n\n    go producer(rb, \u0026wg)\n    go consumer(rb, \u0026wg)\n\n    wg.Wait()\n}\n```\n\n## API Reference\n\n### NewRingBuffer\n\n```go\nfunc NewRingBuffer(filename string, size int, remove bool) (*RingBuffer, error)\n```\n\nCreates a new ring buffer backed by a memory-mapped file.\n- `filename`: Path to the memory-mapped file\n- `size`: Size of the buffer in bytes\n- `remove`: If true, removes any existing file before creating\n\n### OpenRingBuffer\n\n```go\nfunc OpenRingBuffer(filename string) (*RingBuffer, error)\n```\n\nOpens an existing ring buffer file.\n\n### WriteMsg\n\n```go\nfunc (r *RingBuffer) WriteMsg(msg []byte) (bool, error)\n```\n\nWrites a message to the buffer. Returns `true` and `nil` if successful.\n- Returns `ErrBufferFull` if the buffer is full\n- Returns `ErrInvalidSize` if the message is empty or too large\n- Returns `ErrClosed` if the buffer is closed\n\n### ReadMsg\n\n```go\nfunc (r *RingBuffer) ReadMsg() ([]byte, error)\n```\n\nReads a message from the buffer. Returns the message and `nil` if successful.\n- Returns `ErrBufferEmpty` if the buffer is empty\n- Returns `ErrClosed` if the buffer is closed\n\n### Close\n\n```go\nfunc (r *RingBuffer) Close() error\n```\n\nCloses the ring buffer and releases the memory-mapped file.\n\n## Error Types\n\n- `ErrBufferFull`: Returned when trying to write to a full buffer\n- `ErrInvalidSize`: Returned when trying to write an empty or too large message\n- `ErrBufferEmpty`: Returned when trying to read from an empty buffer\n- `ErrClosed`: Returned when trying to use a closed buffer\n\n## Performance Considerations\n\n- The buffer size should be chosen carefully based on your use case\n- For high-throughput scenarios, consider using a larger buffer size\n- The buffer uses a header of 8 bytes (4 bytes for head, 4 bytes for tail)\n- Maximum message size is limited to half of the buffer size\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Febwi11%2Fmmap_ringbuffer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Febwi11%2Fmmap_ringbuffer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Febwi11%2Fmmap_ringbuffer/lists"}