{{Short description|Data structure in computer science}} thumb|200px|A ring showing, conceptually, a circular buffer. This visually shows that the buffer has no real end and it can loop around the buffer. However, since memory is never physically created as a ring, a linear representation is generally used as is done below.
In computer science, a '''circular buffer''', '''circular queue''', '''cyclic buffer''' or '''ring buffer''' is a data structure that uses a single, fixed-size buffer as if it were connected end-to-end. This structure lends itself easily to buffering data streams.<ref>{{citation|title=Operating Systems: Three Easy Pieces [Chapter: Condition Variables, figure 30.13]|url=http://pages.cs.wisc.edu/~remzi/OSTEP/threads-cv.pdf| publisher=Arpaci-Dusseau Books|date=2014|first1=Remzi H.|last1=Arpaci-Dusseau|first2=Andrea C.|last2=Arpaci-Dusseau}}</ref> There were early circular buffer implementations in hardware.<ref>{{cite web|last1=Hartl|first1=Johann|title=Impulswiederholer - Telephone Exchange (video)|date=17 October 2011 |url=https://www.youtube.com/watch?v=_xI9tXi-UNs|publisher=Youtube|access-date=15 December 2021}}</ref><ref>{{cite web|last1=Fraser|first1=Alexander Gibson|title=US patent 3979733 Digital data communications system packet switch|url=https://patents.google.com/patent/US3979733A/en|publisher=US States Patent|access-date=15 December 2021}}</ref>
== Overview == 400px|thumbnail|A 24-byte keyboard circular buffer. When the write pointer is about to reach the read pointer—because the microprocessor is not responding—the buffer stops recording keystrokes. On some computers a beep would be played. A circular buffer first starts out empty and has a set length. In the diagram below is a 7-element buffer:
:250px
Assume that 1 is written in the center of a circular buffer (the exact starting location is not important in a circular buffer):
:250px
Then assume that two more elements are added to the circular buffer — 2 & 3 — which get put after 1:
:250px
If two elements are removed, the two oldest values inside of the circular buffer would be removed. Circular buffers use FIFO (''first in, first out'') logic. In the example, 1 & 2 were the first to enter the circular buffer, they are the first to be removed, leaving 3 inside of the buffer. When elements get removed, only the read-pointer moves to the next element. Removed elements are still in the buffer, waiting to get overwritten by new elements.
:250px
If the buffer has 7 elements, then it is completely full:
:250px
A property of the circular buffer is that when it is full and a subsequent write is performed, then it starts overwriting the oldest data. In the current example, two more elements — A & B — are added and they ''overwrite'' the 3 & 4:
:250px
Alternatively, the routines that manage the buffer could prevent overwriting the data and return an error or raise an exception. Whether or not data is overwritten is up to the semantics of the buffer routines or the application using the circular buffer.
Finally, if two elements are now removed then what would be removed is '''not''' A & B, but 5 & 6 because 5 & 6 are now the oldest elements, yielding the buffer with:
:250px
== Uses == The useful property of a circular buffer is that it does not need to have its elements shuffled around when one is consumed. (If a non-circular buffer were used then it would be necessary to shift all elements when one is consumed.) In other words, the circular buffer is well-suited as a FIFO (''first in, first out'') buffer while a standard, non-circular buffer is well suited as a LIFO (''last in, first out'') buffer.
Circular buffering makes a good implementation strategy for a queue that has fixed maximum size. Should a maximum size be adopted for a queue, then a circular buffer is a completely ideal implementation; all queue operations are constant time. However, expanding a circular buffer requires shifting memory, which is comparatively costly. For arbitrarily expanding queues, a linked list approach may be preferred instead.
In some situations, an overwriting circular buffer can be used, e.g. in multimedia. If the buffer is used as the bounded buffer in the producer–consumer problem then it is probably desired for the producer (e.g., an audio generator) to overwrite old data if the consumer (e.g., the sound card) is unable to momentarily keep up. Also, the LZ77 family of lossless data compression algorithms operates on the assumption that strings seen more recently in a data stream are more likely to occur soon in the stream. Implementations store the most recent data in a circular buffer.
== Circular buffer mechanics == :250px|thumb|Circular buffer implementation in hardware, US patent 3979733, fig4 A circular buffer can be implemented using a pointer and four integers:<ref name="Liu Wu Das 2021 p. 117">{{cite book |last1=Liu |first1=Z. |url=https://books.google.com/books?id=si1CEAAAQBAJ&pg=PA117 |title=Wireless Algorithms, Systems, and Applications: 16th International Conference, WASA 2021, Nanjing, China, June 25–27, 2021, Proceedings, Part II |last2=Wu |first2=F. |last3=Das |first3=S.K. |publisher=Springer International Publishing |year=2021 |isbn=978-3-030-86130-8 |series=Lecture Notes in Computer Science |page=117 |access-date=2023-09-04}}</ref> * buffer start in memory * buffer capacity (length) * write to buffer index (end) * read from buffer index (start)
This image shows a partially full buffer with Length = 7:
:250px
This image shows a full buffer with four elements (numbers 1 through 4) having been overwritten:
:250px
In the beginning the indexes end and start are set to 0. The circular buffer write operation writes an element to the end index position and the end index is incremented to the next buffer position. The circular buffer read operation reads an element from the start index position and the start index is incremented to the next buffer position.
The start and end indexes alone are not enough to distinguish between buffer full or empty state while also utilizing all buffer slots,<ref>{{cite web|last1=Chandrasekaran|first1=Siddharth|title=Implementing Circular/Ring Buffer in Embedded C|url=https://embedjournal.com/implementing-circular-buffer-embedded-c/|website=Embed Journal|publisher=EmbedJournal Team|access-date=14 August 2017|archive-url=https://web.archive.org/web/20170211031659/http://embedjournal.com/implementing-circular-buffer-embedded-c/|archive-date=11 February 2017|url-status=live|date=2014-05-16}}</ref> but can be if the buffer only has a maximum in-use size of Length − 1.<ref>[https://www.kernel.org/doc/Documentation/circular-buffers.txt#:~:text=A%20circular%20buffer%20is%20a,next%20item%20in%20the%20buffer Circular buffers] kernel.org</ref> In this case, the buffer is empty if the start and end indexes are equal and full when the in-use size is Length − 1. Another solution is to have another integer count that is incremented at a write operation and decremented at a read operation. Then checking for emptiness means testing count equals 0 and checking for fullness means testing count equals Length.<ref>{{cite web |title=ArrayQueue: An Array-Based Queue |url=http://opendatastructures.org/ods-python/2_3_ArrayQueue_Array_Based_.html |website=Open Data Structures (in pseudocode) |first=Pat |last=Morin|author-link= Pat Morin |access-date=7 November 2015 |archive-url=https://web.archive.org/web/20150831023453/http://opendatastructures.org/ods-python/2_3_ArrayQueue_Array_Based_.html |archive-date=31 August 2015 |url-status=live }}</ref>
The following source code is a C implementation together with a minimal test. Function put() puts an item in the buffer, function get() gets an item from the buffer. Both functions take care about the capacity of the buffer :
<syntaxhighlight lang="c"> #include <stdio.h>
enum { N = 10 }; // size of circular buffer
int buffer [N]; // note: only (N - 1) elements can be stored at a given time int writeIndx = 0; int readIndx = 0;
int put (int item) { if ((writeIndx + 1) % N == readIndx) { // buffer is full, avoid overflow return 0; } buffer[writeIndx] = item; writeIndx = (writeIndx + 1) % N; return 1; }
int get (int * value) { if (readIndx == writeIndx) { // buffer is empty return 0; }
*value = buffer[readIndx]; readIndx = (readIndx + 1) % N; return 1; }
int main () { // test circular buffer int value = 1001; while (put (value ++)); while (get (& value)) printf ("read %d\n", value); return 0; } </syntaxhighlight>
== Optimization == A circular-buffer implementation may be optimized by mapping the underlying buffer to two contiguous regions of virtual memory.<ref>{{cite web |title=mikeash.com: Friday Q&A 2012-02-17: Ring Buffers and Mirrored Memory: Part II |author=Mike Ash |work=mikeash.com |date=2012-02-17 |access-date=2019-01-10 |url=https://www.mikeash.com/pyblog/friday-qa-2012-02-17-ring-buffers-and-mirrored-memory-part-ii.html |archive-url=https://web.archive.org/web/20190111054903/https://www.mikeash.com/pyblog/friday-qa-2012-02-17-ring-buffers-and-mirrored-memory-part-ii.html |archive-date=2019-01-11 |url-status=live }}</ref>{{Disputed inline|talk=Talk:Circular_buffer#Optimization|date=January 2022}} (Naturally, the underlying buffer‘s length must then equal some multiple of the system’s page size.) Reading from and writing to the circular buffer may then be carried out with greater efficiency by means of direct memory access; those accesses which fall beyond the end of the first virtual-memory region will automatically wrap around to the beginning of the underlying buffer. When the read offset is advanced into the second virtual-memory region, both offsets—read and write—are decremented by the length of the underlying buffer.
== Fixed-length-element and contiguous-block circular buffer == Perhaps the most common version of the circular buffer uses 8-bit bytes as elements.
Some implementations of the circular buffer use fixed-length elements that are bigger than 8-bit bytes—16-bit integers for audio buffers, 53-byte ATM cells for telecom buffers, etc. Each item is contiguous and has the correct data alignment, so software reading and writing these values can be faster than software that handles non-contiguous and non-aligned values.
Ping-pong buffering can be considered a very specialized circular buffer with exactly two large fixed-length elements.
The ''bip buffer'' (bipartite buffer) is very similar to a circular buffer, except it always returns contiguous blocks which can be variable length. This offers nearly all the efficiency advantages of a circular buffer while maintaining the ability for the buffer to be used in APIs that only accept contiguous blocks.<ref name="cooke">Simon Cooke (2003), [https://web.archive.org/web/20260204171614/http://www.codeproject.com/articles/The-Bip-Buffer-The-Circular-Buffer-with-a-Twist "The Bip Buffer - The Circular Buffer with a Twist"]</ref>
Fixed-sized compressed circular buffers use an alternative indexing strategy based on elementary number theory to maintain a fixed-sized compressed representation of the entire data sequence.<ref name="gunther">{{cite journal|last1=Gunther|first1=John C.|title=Algorithm 938: Compressing circular buffers|journal=ACM Transactions on Mathematical Software|date=March 2014|volume=40|issue=2|pages=1–12|doi=10.1145/2559995|s2cid=14682572 }}</ref>
== References == {{reflist}}
== External links == * CircularBuffer at the Portland Pattern Repository * Boost: *: [https://www.boost.org/doc/libs/release/doc/html/circular_buffer.html Templated Circular Buffer Container]: [https://github.com/boostorg/circular_buffer/blob/develop/include/boost/circular_buffer/base.hpp circular_buffer/base.hpp] *: [https://www.boost.org/doc/libs/release/doc/html/thread/sds.html#thread.sds.synchronized_queues.ref.sync_bounded_queue_ref Synchronized Bounded Queue]: [https://github.com/boostorg/thread/blob/develop/include/boost/thread/concurrent_queues/sync_bounded_queue.hpp sync_bounded_queue.hpp] * [https://www.kernel.org/doc/html/latest/core-api/circular-buffers.html CB in Linux kernel] * [http://www.dspguide.com/ch28/2.htm CB in DSP] * [http://www.martinbroadhurst.com/cirque-in-c.html Circular queue in C] {{Webarchive|url=https://web.archive.org/web/20181029235921/http://www.martinbroadhurst.com/cirque-in-c.html |date=2018-10-29 }}
{{Data structures}}
Category:Computer memory Category:Arrays