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. Calls on one store run one at a time.

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.

AppendAsync(string)

Adds text to the end of the buffer: a reading or a line written out.

public Task AppendAsync(string text)

Parameters

text string

The text to hold, as UTF-8.

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. The drain waits for any call already running on the transport.

Exceptions

PamojaException

The link failed part-way through.

File(string, int)

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

public static Store File(string dir, int capacity = 0)

Parameters

dir string

The directory to hold records in; created if missing.

capacity int

The most records to hold, or 0 for no bound. A full store refuses the next append, which keeps a long outage from filling the disk.

Returns

Store

The buffer.

Remarks

A record a power cut interrupted mid-write is never seen, and one written before the cut is found again when the directory is reopened.

Exceptions

ArgumentOutOfRangeException

The capacity is negative.

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.

Exceptions

ArgumentOutOfRangeException

The capacity is negative.

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.

PeekTextAsync()

Reads the oldest record as text, without removing it.

public Task<string?> PeekTextAsync()

Returns

Task<string>

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.

PopTextAsync()

Removes and returns the oldest record as text.

public Task<string?> PopTextAsync()

Returns

Task<string>

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

The pointer the caller now owns.

Exceptions

PamojaException

This store was already given away, or a call on it is still running.