Class Transport

Namespace

Pamoja.Core

Assembly

Pamoja.Core.dll

One transport, ready to compose into a ladder or a wrapper.

public sealed class Transport : ILink, IDisposable

Inheritance

object

Transport

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 rung, a fault injector, and a degraded link all take some transport, which a C ABI cannot express, so one handle carries whichever kind was built. Composing consumes it: the thing it is composed into owns it from then on, so a spent transport throws rather than aliasing a link it no longer holds. A link written in .NET enters through FromHandlers(ITransportHandlers) and is one of these from then on.

Calls on one transport run one at a time, so a send made while a receive is waiting runs once the receive returns. A task that listens should have a link of its own.

Constructors

Transport(nint, string)

Wraps a native transport handle.

public Transport(nint handle, string what)

Parameters

handle nint

The pointer a native call produced.

what string

What was being created, for the exception message.

Exceptions

PamojaException

The native call produced no transport.

Properties

IsAvailable

Whether this transport is still holdable, or has been handed on.

public bool IsAvailable { get; }

Property Value

bool

Methods

ConnectAsync()

Connects this transport.

public Task ConnectAsync()

Returns

Task

Exceptions

PamojaException

The link could not be established.

Degraded(Transport, uint, uint, uint)

Wraps a transport in a link that loses packets and goes down.

public static Transport Degraded(Transport inner, uint dropEvery = 0, uint up = 0, uint down = 0)

Parameters

inner Transport

The transport to wrap, consumed by this call.

dropEvery uint

Lose one send in every this many, or 0 to lose none.

up uint

How many sends the link stays up for, or 0 to never go down.

down uint

How many sends it then stays down for.

Returns

Transport

A transport owning the wrapped one.

Dispose()

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

public void Dispose()

Faulty(Transport, int)

Wraps a transport so a set number of its next sends fail.

public static Transport Faulty(Transport inner, int failures)

Parameters

inner Transport

The transport to wrap, consumed by this call.

failures int

How many upcoming sends to fail.

Returns

Transport

A transport owning the wrapped one.

Remarks

This is how a caller checks that a ladder falls through to its next rung, or that a buffer fills, without unplugging anything.

FromHandlers(ITransportHandlers)

Wraps a link written in .NET as a transport.

public static Transport FromHandlers(ITransportHandlers handlers)

Parameters

handlers ITransportHandlers

The link.

Returns

Transport

A transport whose every operation is one of the handlers.

Remarks

The handlers are held for the life of the transport and every transport composed from it, and released once nothing will call them again. A IReceivingTransportHandlers is listened on; plain ITransportHandlers only send, and a ladder never listens on them.

Exceptions

PamojaException

The native transport could not be created.

LendAsync<TResult>(Func<nint, Task<TResult>>)

Lends the native handle to asynchronous work, such as a store draining into this transport, which runs once any call on the transport has returned.

public Task<TResult> LendAsync<TResult>(Func<nint, Task<TResult>> work)

Parameters

work Func<nint, Task<TResult>>

The work to run with the pointer.

Returns

Task<TResult>

Whatever the work produced.

Type Parameters

TResult

The value the work produces.

Exceptions

PamojaException

This transport was already handed on.

ReceiveAsync()

Waits for the next message this transport delivers on a subscribed topic.

public Task<TransportMessage?> ReceiveAsync()

Returns

Task<TransportMessage>

The message, or null once the link has ended.

Exceptions

PamojaException

The transport is not connected.

ReceiveAsync(TimeSpan)

Waits a limited time for the next message on a subscribed topic.

public Task<TransportMessage?> ReceiveAsync(TimeSpan timeout)

Parameters

timeout TimeSpan

How long to wait.

Returns

Task<TransportMessage>

The message, or null once the link has ended.

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

The transport is not connected.

SendAsync(string, ReadOnlyMemory<byte>)

Sends a payload to a topic over this transport.

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

Parameters

topic string

The destination topic.

payload ReadOnlyMemory<byte>

The bytes to send.

Returns

Task

Exceptions

PamojaException

The transport would not take it.

SendAsync(string, string)

Sends text to a topic over this transport: words, or a number written out.

public Task SendAsync(string topic, string text)

Parameters

topic string

The destination topic.

text string

The text to send, as UTF-8.

Returns

Task

Exceptions

PamojaException

The transport would not take it.

SubscribeAsync(string)

Subscribes this transport to a topic.

public Task SubscribeAsync(string topic)

Parameters

topic string

The topic to subscribe to.

Returns

Task

Exceptions

PamojaException

The subscription was refused.

Take()

Hands the native handle on, leaving this one spent.

public nint Take()

Returns

nint

The pointer the caller now owns.

Exceptions

PamojaException

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