Class Store

Namespace

Pamoja.Sync

Assembly

Pamoja.Sync.dll

A store-and-forward buffer.

public sealed class Store : IDisposable

Inheritance

object

Store

Implements

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

The queue a node writes into while it has nowhere to send. An in-memory buffer suits a test or a process that will not outlive it; a file-backed one survives a reboot, which is what a node somewhere without reliable power actually needs.

Handing a store to a ladder consumes it, because the ladder owns it from then on, so a spent store throws rather than aliasing a buffer it no longer holds.

Properties

IsAvailable

Whether this store is still holdable, or has been given away.

public bool IsAvailable { get; }

Property Value

bool

Methods

AppendAsync(ReadOnlyMemory<byte>)

Adds a record to the end of the buffer.

public Task AppendAsync(ReadOnlyMemory<byte> record)

Parameters

record ReadOnlyMemory<byte>

The bytes to hold.

Returns

Task

Exceptions

PamojaException

The store is full, or otherwise refused it.

CountAsync()

Reports how many records the buffer holds.

public Task<int> CountAsync()

Returns

Task<int>

The count.

Exceptions

PamojaException

The native call failed.

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

public void Dispose()

DrainToAsync(Transport, string)

Sends every held record over a transport, oldest first.

public Task<int> DrainToAsync(Transport transport, string topic)

Parameters

transport Transport

The transport to send over, borrowed not consumed.

topic string

The topic to send to.

Returns

Task<int>

How many records went out.

Remarks

A record is removed only once the transport has taken it, so a link that fails part-way leaves the rest of the queue intact for the next attempt.

Exceptions

PamojaException

The link failed part-way through.

File(string)

Opens a buffer backed by a directory, so it survives a restart.

public static Store File(string dir)

Parameters

dir string

The directory to hold records in; created if missing.

Returns

Store

The buffer.

Exceptions

PamojaException

The directory could not be opened.

Memory(int)

Creates a buffer held in memory.

public static Store Memory(int capacity = 0)

Parameters

capacity int

The most records to hold, or 0 for no bound.

Returns

Store

The buffer.

Remarks

A full store refuses the next append rather than dropping anything, so a record is never lost without the caller being told.

PeekAsync()

Reads the oldest record without removing it.

public Task<byte[]?> PeekAsync()

Returns

Task<byte[]>

The record, or null when the buffer is empty.

Exceptions

PamojaException

The native call failed.

PopAsync()

Removes and returns the oldest record.

public Task<byte[]?> PopAsync()

Returns

Task<byte[]>

The record, or null when the buffer is empty.

Exceptions

PamojaException

The native call failed.

Take()

Hands the native handle on, leaving this one spent.

public nint Take()

Returns

nint