Circular Buffer

• Download source - 109 Kb
• Download demo project - 14 Kb
• Download demo source - 25 Kb

Circular Buffers are use for data transfer between two processes. The Producer process places items into the Circular Buffer and the Consumer process removes them. The variable capacity of the Circular Buffer accommodates timing differences between the Producer and Consumer processes.

The Circular Buffer can execute faster than than other queues that hold a variable amount of data since a fixed size block of memory is allocated just once from memory management and then reused (the Circular Buffer can be visualized as such but is actually a linear buffer with indices that wrap, modulo the buffer size, when the end of the buffer is reached).

Often, the Circular Buffer is used to decouple two processes that operate at different speeds. For example, a faster Producer process can "burst" data into the buffer and continue with its processing. A slower Consumer of that data can then read it at its own rate without synchronizing and slowing the Producer. In this type of application, the average rate, over time, of both processes must be the same to avoid an over or under flow condition of the Circular Buffer (this is the "Synchronous Mode" of operation). Also, sequencing is critical. Unless one of the synchronizing methods described below is used, the Producer process must always execute first.

In other types of applications, overflow of the Circular Buffer and attendant data loss is acceptable. For example--Error Logging. Here process state data is continuously written into the Circular Buffer at a high rate but only the last few logged items are useful in troubleshooting a problem that might take hours or days to repeat. A buffer of size N is saturated with the last N-1 items written by the Producer and read when the error condition is detected. This is the "Asynchronous Mode" of the Circular Buffer.

In the Synchronous Mode, two methods are available to ensure that no data is lost. The Blocking method and the WaterMark method.

Calling Blocking methods will cause a calling thread to block until the Circular Buffer has the requested number of items. Note that blocking pairs must be used. That is, if the DequeueBlocking or CopyToBlocking methods are used, the EnqueueBlocking method must also be used. The WaterMark method will fire an event when the number of items in the Circular buffer reaches a preset level - eliminating wasted processing time due to process blocks. Example usage:

theCB.SetWaterMark(8); // notify everytime cb has 8 items 
theCB.WaterMarkNotify += new QueueCB.CBEventHandler(WaterMarkEvent);

The Winform application I provide isn't terribly useful for architecting a system using the Circular Buffer. I used it to test the class and then added the GUI for fun. But it might be a useful learning device if you are unfamiliar with the concepts. It simulates a N=36 size Circular Buffer with Producer and Consumer threads. It operates a little like a clock doesn't it.

The IEnumerator interface is supported and the items can be read from the Circular Buffer with foreach().

The DLL is signed for installation in the GAC.

Using the Circular Buffer in multi-threaded applications is very complex and subject to possible timing hazards. This is version 1.0.0.0 so beware!

Watch out for the blocking methods, at the last minute I decided to use an AutoResetEvent for synchronization because I wanted to learn how to use one. But to the degree tested, everything seems to work. Please report bugs (and fixes?) to me.

Thanks to the .NET team for giving us such amazing technology and for making this stuff so much fun.

This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

A list of licenses authors might use can be found here