AddAsync Method

AddAsync(TItem)

Adds an item to the tail of the Ringbuffer.

Declaration
Task<long> AddAsync(TItem item)
Parameters
TItem item

the item to Add.
Returns
Task<Int64>

the sequence of the added item.
Remarks

Adds an item to the tail of the Ringbuffer. If there is no space in the Ringbuffer, the Add will overwrite the oldest item in the ringbuffer no matter what the ttl is. For more control on this behavior, check the AddAsync(TItem) and the OverflowPolicy . The returned value is the sequence of the added item. Using this sequence you can read the added item.

Using the sequence as id

This sequence will always be unique for this Ringbuffer instance so it can be used as a unique id generator if you are publishing items on this Ringbuffer. However you need to take care of correctly determining an initial id when any node uses the ringbuffer for the first time. The most reliable way to do that is to write a dummy item into the ringbuffer and use the returned sequence as initial id. On the reading side, this dummy item should be discard. Please keep in mind that this id is not the sequence of the item you are about to publish but from a previously published item. So it can't be used to find that item.

Exceptions
ArgumentNullException

if item is null.
See Also

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);
}
Declaration
Task<long> AddAsync(TItem item, OverflowPolicy overflowPolicy)
Parameters
TItem item

the item to Add
OverflowPolicy overflowPolicy

the OverflowPolicy to use.
Returns
Task<Int64>

the sequenceId of the added item, or -1 if the Add failed.
Exceptions
ArgumentNullException

if item or overflowPolicy is null.