{"id":20492058,"url":"https://github.com/zotonic/ringbuffer","last_synced_at":"2025-10-26T02:32:21.804Z","repository":{"id":43732773,"uuid":"327639344","full_name":"zotonic/ringbuffer","owner":"zotonic","description":"🔄 Ring buffer implementation for Erlang using ETS tables.","archived":false,"fork":false,"pushed_at":"2022-02-22T13:19:47.000Z","size":42,"stargazers_count":5,"open_issues_count":1,"forks_count":1,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-03-27T07:51:35.372Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Erlang","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zotonic.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}},"created_at":"2021-01-07T14:43:11.000Z","updated_at":"2023-01-29T20:02:45.000Z","dependencies_parsed_at":"2022-08-21T22:20:19.735Z","dependency_job_id":null,"html_url":"https://github.com/zotonic/ringbuffer","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zotonic%2Fringbuffer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zotonic%2Fringbuffer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zotonic%2Fringbuffer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zotonic%2Fringbuffer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zotonic","download_url":"https://codeload.github.com/zotonic/ringbuffer/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248750078,"owners_count":21155685,"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":[],"created_at":"2024-11-15T17:27:26.300Z","updated_at":"2025-10-26T02:32:16.779Z","avatar_url":"https://github.com/zotonic.png","language":"Erlang","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Test](https://github.com/zotonic/ringbuffer/workflows/Test/badge.svg)](https://github.com/zotonic/ringbuffer/actions?query=workflow%3ATest)\n[![Hex version](https://img.shields.io/hexpm/v/ringbuffer.svg \"Hex version\")](https://hex.pm/packages/ringbuffer)\n\nRingbuffer\n==========\n\nA ring buffer implementation using Erlang and ets tables.\n\nMain feature is lock free writing without message passing, making\nthis implementation ideal for log systems with many fast writers or\nbig bursts.\n\nRingbuffer implements a length limited queue. In systems this is\noften implemented as a ring, or cylic, buffer. Where the writer can\npush the reader ahead if the buffer is full.\n\nThis kind of buffers is useful in situations where you can have\nsurges of writers, with a limited amount of readers. And where it\nis allowed to drop entries from the queue if the readers can't keep\nup with the writers.\n\nAn example is a logging system for a http server, which can handle large\nbursts of requests. The logger is often limited in its throughput, and it\nis perfectly ok to drop log entries if that means that the server can\nhandle the peak load.\n\nThis ring buffer is technically not a ring. It is a size limited buffer,\nimplemented in ets. Its main characteristics are:\n\n * Optimized for writes: non locking and non blocking queue writes;\n * Size limited, define the maximum number of entries upon queue creation;\n * Readers are synchronized to prevent race conditions;\n * Readers return the number of entries that were lost due to too fast writers;\n * As many queues as needed.\n\nThe size of the ring is set upon creation. If the ring is full\nthen older entries are overwritten. Overwritten entries are skipped\nwhen reading the next entry. The number of skipped entries is\nreturned.\n\nThe ring's ets table is owned by a process managed by the ringbuffer_sup.\n\n## Installation\n\nRingBuffer is at Hex, in your `rebar.config` file use:\n\n```erlang\n{deps, [\n    ringbuffer\n]}.\n```\n\nYou can also use the direct Git url and use the development version:\n\n```erlang\n{deps, [\n    {ringbuffer, {git, \"https://github.com/zotonic/ringbuffer.git\", {branch, \"main\"}}}\n]}.\n```\n\n## Usage\n\nFirst create a ringbuffer. The buffer is named with an atom\nand needs a size of the maximum amount of items to buffer.\n\n```erlang\n    {ok, Pid} = ringbuffer:new(name, 1000)\n```\n\nThen an entry can be written:\n\n```erlang\n    ok = ringbuffer:write(name, Payload).\n```\n\nThe `Payload` can be any Erlang term.\n\n\nIt can be read afterwards:\n\n```erlang\n    {ok, {NSkipped, Payload}} = ringbuffer:read(name).\n```\n\nThe `NSkipped` is the number of entries skipped during reads. If the consumer\ncan keep up with the producers then it will be `0`. If entries are overwritten\nthen it will return the number of overwritten entries.\n\nIf the buffer is empty then an error is returned:\n\n```erlang\n    {error, empty} = ringbuffer:read(name).\n```\n\n## Use in your own supervisor\n\nYou can use ringbuffer in your own supervisor with the following child spec:\n\n```erlang\n    % Size and name of the ringbuffer\n    BufferSize = 1000,\n    NameOfMyBuffer = foobar,\n    % The child spec for your supervisor\n    #{\n        start =\u003e {ringbuffer_process, start_link, [NameOfMyBuffer, BufferSize]},\n        restart =\u003e permanent,\n        type =\u003e worker\n    }\n```\n\n\n## Test\n\nRun the tests:\n\n```\nmake test\n```\n\nAll tests should pass.\n\nFor additional checks, also run:\n\n```\nmake xref\nmake dialyzer\n```\n\n## License\n\nRingbuffer is licensed under the Apache 2.0 license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzotonic%2Fringbuffer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzotonic%2Fringbuffer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzotonic%2Fringbuffer/lists"}