IHRingBuffer<TItem> Interface

Namespace: Hazelcast.DistributedObjects
Assembly: Hazelcast.Net.dll

A Ringbuffer is a data-structure where the content is stored in a ring like structure.

public interface IHRingBuffer<TItem> : IDistributedObject, IAsyncDisposable
Inherited Members
Type Parameters
TItem
Remarks

A Ringbuffer is a data-structure where the content is stored in a ring like structure. A ringbuffer has a capacity so it won't grow beyond that capacity and endanger the stability of the system. If that capacity is exceeded, than the oldest item in the ringbuffer is overwritten. The ringbuffer has 2 always incrementing sequences:

  1. tailSequence: this is the side where the youngest item is found. So the tail is the side of the ringbuffer where items are added to.
  2. headSequence: this is the side where the oldest items are found. So the head is the side where items gets discarded.

The items in the ringbuffer can be found by a sequence that is in between (inclusive) the head and tail sequence. If data is read from a ringbuffer with a sequence that is smaller than the headSequence, it means that the data is not available anymore and a StaleSequenceException is thrown. A Ringbuffer currently is not a distributed data-structure. So all data is stored in a single partition; comparable to the IQueue implementation. But we'll provide an option to partition the data in the near future. A Ringbuffer can be used in a similar way as a queue, but one of the key differences is that a queue.take is destructive, meaning that only 1 thread is able to take an item. A ringbuffer.read is not destructive, so you can have multiple threads reading the same item multiple times. The Ringbuffer is the backing data-structure for the reliable IHTopic<T> implementation.

Properties

Name Description
MaxBatchSize

Methods

Name Description
AddAllAsync(ICollection<TItem>, OverflowPolicy)

Adds all the items of a collection to the tail of the Ringbuffer.
AddAsync(TItem)

Adds an item to the tail of the Ringbuffer.
AddAsync(TItem, OverflowPolicy)

Asynchronously writes an item with a configurable OverflowPolicy . If there is space in the ringbuffer, the call will return the sequence of the written item. If there is no space, it depends on the overflow policy what happens:

  1. Overwrite : we just overwrite the oldest item in the ringbuffer and we violate the ttl
  2. Fail : we return -1

The reason that FAIL exist is to give the opportunity to obey the ttl. If blocking behavior is required, this can be implemented using retrying in combination with a exponential backoff. Example:

int sleepMs = 100;
for (; ; ) {
long result = ringbuffer.AddAsync(item, OverflowPolicy.Fail).Result;
if (result != -1) {
break;
}
Thread.Sleep(sleepMs);
sleepMs = Math.Min(5000, sleepMs * 2);
}
GetCapacityAsync()

Returns the capacity of this Ringbuffer.
GetHeadSequenceAsync()

Returns the sequence of the head.
GetRemainingCapacityAsync()

Returns the remaining capacity of the ringbuffer.
GetSizeAsync()

Returns number of items in the ringbuffer.
GetTailSequenceAsync()

Returns the sequence of the tail.
ReadManyAsync(long, int, int)

Reads a batch of items from the Ringbuffer.
ReadManyWithResultSetAsync(long, int, int, CancellationToken)

Reads a batch of items from the Ringbuffer with sequence information.
ReadOneAsync(long)

Reads one item from the Ringbuffer.