RingBuffer

OVERFLOW_POLICY_OVERWRITE = 0

Configuration property for DEFAULT overflow policy. When an item is tried to be added on full Ringbuffer, oldest item in the Ringbuffer is overwritten and item is added.

OVERFLOW_POLICY_FAIL = 1

Configuration property for overflow policy. When an item is tried to be added on full Ringbuffer, the call fails and item is not added.

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 an exponential backoff.

>>> sleepMS = 100;
>>> while true:
>>>     result = ringbuffer.add(item, -1)
>>>     if result != -1:
>>>         break
>>>     sleep(sleepMS / 1000)
>>>     sleepMS *= 2
MAX_BATCH_SIZE = 1000

The maximum number of items to be added to RingBuffer or read from RingBuffer at a time.

class Ringbuffer(client, service_name, name)

Bases: hazelcast.proxy.base.PartitionSpecificProxy

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:

#. tail_sequence: this is the side where the youngest item is found. So the tail is the side of the Ringbuffer where items are added to. #. head_sequence: 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.

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.

capacity()

Returns the capacity of this Ringbuffer.

Returns:(long), the capacity of Ringbuffer.
size()

Returns number of items in the Ringbuffer.

Returns:(long), the size of Ringbuffer.
tail_sequence()

Returns the sequence of the tail. The tail is the side of the Ringbuffer where the items are added to. The initial value of the tail is -1.

Returns:(long), the sequence of the tail.
head_sequence()

Returns the sequence of the head. The head is the side of the Ringbuffer where the oldest items in the Ringbuffer are found. If the Ringbuffer is empty, the head will be one more than the tail. The initial value of the head is 0 (1 more than tail).

Returns:(long), the sequence of the head.
remaining_capacity()

Returns the remaining capacity of the Ringbuffer.

Returns:(long), the remaining capacity of Ringbuffer.
add(item, overflow_policy=0)

Adds the specified item to the tail of the Ringbuffer. If there is no space in the Ringbuffer, the action is determined by overflow policy as OVERFLOW_POLICY_OVERWRITE or OVERFLOW_POLICY_FAIL.

Parameters:
  • item – (object), the specified item to be added.
  • overflow_policy – (int), the OverflowPolicy to be used when there is no space (optional).
Returns:

(long), the sequenceId of the added item, or -1 if the add failed.
add_all(items, overflow_policy=0)

Adds all of the item in the specified collection to the tail of the Ringbuffer. An add_all is likely to outperform multiple calls to add(object) due to better io utilization and a reduced number of executed operations. The items are added in the order of the Iterator of the collection.

If there is no space in the Ringbuffer, the action is determined by overflow policy as OVERFLOW_POLICY_OVERWRITE or OVERFLOW_POLICY_FAIL.

Parameters:
  • items – (Collection), the specified collection which contains the items to be added.
  • overflow_policy – (int), the OverflowPolicy to be used when there is no space (optional).
Returns:

(long), the sequenceId of the last written item, or -1 of the last write is failed.
read_one(sequence)

Reads one item from the Ringbuffer. If the sequence is one beyond the current tail, this call blocks until an item is added. Currently it isn’t possible to control how long this call is going to block.

Parameters:sequence – (long), the sequence of the item to read.
Returns:(object), the read item.
read_many(start_sequence, min_count, max_count)

Reads a batch of items from the Ringbuffer. If the number of available items after the first read item is smaller than the max_count, these items are returned. So it could be the number of items read is smaller than the max_count. If there are less items available than min_count, then this call blocks. Reading a batch of items is likely to perform better because less overhead is involved.

Parameters:
  • start_sequence – (long), the start_sequence of the first item to read.
  • min_count – (int), the minimum number of items to read.
  • max_count – (int), the maximum number of items to read.
Returns:

(Sequence), the list of read items.