Class Ladder

Namespace

Pamoja.Ladder

Assembly

Pamoja.Ladder.dll

An ordered set of transports backed by an offline buffer.

public sealed class Ladder : ILink, IDisposable

Inheritance

object

Ladder

Implements

ILink

IDisposable

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

A ladder is the answer to a node that has more than one way to reach the network and no single one that always works: rungs are tried in the order they were added, cheapest first, and a message no rung accepts goes into a buffer rather than being lost.

Constructors

Ladder(Store)

Creates a ladder with no rungs, buffering into a store.

public Ladder(Store store)

Parameters

store Store

The buffer, consumed by this call.

Exceptions

PamojaException

The native ladder could not be created.

Methods

BufferedAsync()

Reports how many messages are waiting in the buffer.

public Task<int> BufferedAsync()

Returns

Task<int>

The count.

Exceptions

PamojaException

The native call failed.

ConnectAsync()

Connects every rung, so a send can be tried against each in turn.

public Task ConnectAsync()

Returns

Task

Remarks

A rung that will not connect is left in the ladder: it may come back, and a send simply falls through it until it does.

Dispose()

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

public void Dispose()

FlushAsync()

Replays the buffer over the rungs, oldest message first.

public Task<int> FlushAsync()

Returns

Task<int>

How many buffered messages went out.

Exceptions

PamojaException

The native call failed.

ReceiveAsync()

Waits for the next message from any rung that listens, whichever delivers first.

public Task<TransportMessage> ReceiveAsync()

Returns

Task<TransportMessage>

The message.

Remarks

Calls on a ladder run one at a time, so a send made while a receive is waiting runs once the receive returns. A node that listens and reports waits with ReceiveAsync(TimeSpan) and sends between waits.

Exceptions

PamojaException

No connected rung listens: none was added, the ladder is not connected, or every listening link has ended.

ReceiveAsync(TimeSpan)

Waits a limited time for the next message from any rung that listens.

public Task<TransportMessage> ReceiveAsync(TimeSpan timeout)

Parameters

timeout TimeSpan

How long to wait.

Returns

Task<TransportMessage>

The message.

Remarks

When the time runs out nothing is lost: a message arriving afterwards waits for the next receive.

Exceptions

TimeoutException

No message arrived in time.

PamojaException

No connected rung listens.

Rung(Transport)

Adds a rung, which is tried after the rungs already added.

public void Rung(Transport transport)

Parameters

transport Transport

The transport to add, consumed by this call.

Remarks

Add the cheapest, most-preferred link first and the costliest fallback last, because a send takes the first rung that accepts it.

Exceptions

PamojaException

The transport was already handed on, or a call on it is still running.

SendAsync(string, ReadOnlyMemory<byte>)

Sends a payload, buffering it if no rung takes it.

public Task<Delivery> SendAsync(string topic, ReadOnlyMemory<byte> payload)

Parameters

topic string

The destination topic.

payload ReadOnlyMemory<byte>

The bytes to send.

Returns

Task<Delivery>

Whether the message went out or was buffered.

Exceptions

PamojaException

The native call failed.

SendAsync(string, string)

Sends text, buffering it if no rung takes it: words, or a number written out.

public Task<Delivery> SendAsync(string topic, string text)

Parameters

topic string

The destination topic.

text string

The text to send, as UTF-8.

Returns

Task<Delivery>

Whether the message went out or was buffered.

Exceptions

PamojaException

The native call failed.

SubscribeAsync(string)

Subscribes every rung that listens to a topic.

public Task SubscribeAsync(string topic)

Parameters

topic string

The topic filter, in the syntax the rungs understand.

Returns

Task

Remarks

The filter is kept for the life of the ladder: a rung that is down when it is placed receives it when it next connects, so subscribing before ConnectAsync() is fine and never fails for want of a link.

Exceptions

PamojaException

Every connected rung refused the filter.

Uplink(Transport)

Adds a rung that only sends, tried after the rungs already added.

public void Uplink(Transport transport)

Parameters

transport Transport

The transport to add, consumed by this call.

Remarks

The ladder sends over it in its turn but never subscribes it or listens on it, whatever the transport could do: a satellite messenger, a LoRa uplink, or any link a node reports over but takes no commands from.

Exceptions

PamojaException

The transport was already handed on, or a call on it is still running.