Class DistributedRingbuffer<V>

java.lang.Object
com.loomcache.server.datastructures.DistributedRingbuffer<V>
Type Parameters:
V - the type of items in this buffer
public class DistributedRingbuffer<V> extends Object
Distributed Ring Buffer — a fixed-capacity circular buffer.

A fixed-size circular buffer where adding to a full buffer overwrites the oldest entry. Backed by a fixed-size slot buffer with head/tail indices. Ideal for bounded collections of time-series data, event logs, or metrics.

Features:

  • add(item) — add an item (overwrites oldest if full)
  • get(index) — retrieve item by relative index (0 = oldest)
  • peek() — view newest item without removing
  • peekOldest() — view oldest item without removing
  • toList() — snapshot as ordered list (oldest to newest)
  • size() — current number of items
  • capacity() — max capacity
  • isFull() — check if at capacity
  • clear() — remove all items
  • drainTo(Collection) — drain all items in order into a List target

Thread safety: all operations are protected by ReentrantLock to ensure atomicity under concurrent access.

Since:
1.0

  • Field Details

  • Constructor Details

    • DistributedRingbuffer

      public DistributedRingbuffer(String name, int instanceNumber, int capacity)
      Create a ring buffer with the given capacity.
      Parameters:
      name - the name of the ring buffer
      instanceNumber - the node instance number
      capacity - the fixed capacity (must be > 0 and invalid input: '<'= MAX_CAPACITY)
      Throws:
      IllegalArgumentException - if capacity is outside the supported range

  • Method Details

    • add

      public long add(V item)

    • setRingbufferStore

      public void setRingbufferStore(RingbufferStore<V> store)
      Wire a persistent backing store for this ringbuffer.

      If the ringbuffer is empty and the store reports an existing largest sequence, the next append continues after that sequence so new writes do not reuse persisted sequence IDs.

      Parameters:
      store - the backing store
      Throws:
      IllegalStateException - if a store is already configured

    • getRingbufferStore

      public @Nullable RingbufferStore<V> getRingbufferStore()
      Get the configured backing store, or null when none is wired.
      Returns:
      configured ringbuffer store, or null

    • hasRingbufferStoreForPersistence

      public boolean hasRingbufferStoreForPersistence()

    • readOne

      public @Nullable V readOne(long sequence)

    • readMany

      public List<V> readMany(long startSequence, int maxCount)

    • readMany

      public List<V> readMany(long startSequence, int maxCount, @Nullable IFunction<? super V, Boolean> filter)

    • readManyResult

      public DistributedRingbuffer.ReadManyResult<V> readManyResult(long startSequence, int maxCount, @Nullable IFunction<? super V, Boolean> filter)

    • readManyAsync

      public CompletableFuture<List<V>> readManyAsync(long startSequence, int minCount, int maxCount)

    • readManyAsync

      public CompletableFuture<List<V>> readManyAsync(long startSequence, int minCount, int maxCount, @Nullable IFunction<? super V, Boolean> filter)

    • headSequence

      public long headSequence()

    • tailSequence

      public long tailSequence()

    • get

      public @Nullable V get(int index)

    • peek

      public @Nullable V peek()

    • peekOldest

      public @Nullable V peekOldest()

    • toList

      public List<V> toList()

    • size

      public int size()

    • capacity

      public int capacity()

    • isFull

      public boolean isFull()

    • isEmpty

      public boolean isEmpty()

    • clear

      public void clear()

    • drainTo

      public int drainTo(Collection<? super V> target)
      Drain all buffered items into target in order.

      The target must be a List so partial appends can be rolled back exactly if the transfer fails. The caller must not modify the target concurrently while this method is running.

    • restoreFromSnapshot

      public void restoreFromSnapshot(List<V> items, long restoredHeadSequence, long restoredTailSequence)

    • restoreFromSnapshot

      public void restoreFromSnapshot(List<V> items, long restoredHeadSequence, long restoredTailSequence, long restoredStoreReadFloor)

    • storeReadFloor

      public long storeReadFloor()

    • toString

      public String toString()
      Overrides:
      toString in class Object