seqeron 0.18.0
Loading...
Searching...
No Matches
Org.Limitless.Seqeron.App.Gateway Class Referencesealed

One instance of an elected active/standby producer pair. Everything this tier defines about being a gateway is behind it: the list row that names the instance, the designation that makes it serve, the GatewayStarted that binds its session, the connection id space it resumes from its predecessor, the connection lifecycle frames, confirmed ingress across a failover, and the fences that stand it down. More...

Inheritance diagram for Org.Limitless.Seqeron.App.Gateway:
Collaboration diagram for Org.Limitless.Seqeron.App.Gateway:

Public Member Functions

 Gateway (GatewayOptions options)
 An instance configured by options ; nothing is connected until Start.
 
void Start (Aeron aeron)
 Opens the cluster session and starts following this node's queue; the gate stays shut until designated.
 
int DoWork ()
 One duty-cycle iteration: the cluster session and the queue, then whatever the connection lifecycle, the election and a snapshot round still owe. Nothing once fenced, so a designation dispatched in the cycle that fenced opens no gate.
 
void GateClosed ()
 The edge closed without being asked to — a dial that failed, a counterparty that hung up. The designation stands, so DoWork opens it again through IGatewayListener.OnActivated, and without a second GatewayStarted: this instance is still the one the cluster designated.
 
void KeepAlive ()
 Tells the cluster this instance is alive. DoWork already does it once a cycle; call this as well from inside an IGatewayListener callback that spins — writing to an edge that is back-pressured, say — since DoWork cannot run again until that callback returns, and the cluster drops a session that goes quiet for sequencer.sessionTimeoutMs. Self-throttling, so a call per spin costs nothing.
 
int OpenConnection (IDirectBuffer connectionData, int length)
 Takes one connection into the cluster's view of this gateway: allocates its id from the resume point and adds its ConnectionOpened to the backlog that DoWork places and retries.
 
int OpenConnection (ReadOnlySpan< byte > connectionData)
 The same from a span.
 
int OpenConnection ()
 The same for a connection whose only identity is its id.
 
void CloseConnection (int connectionId)
 The same for a connection that has gone. One the cluster never heard of is dropped rather than announced.
 
Publish Publish (int connectionId, int payloadId, IDirectBuffer payload, int length)
 Submits one application payload on a connection to this gateway's own group, stamped with its sourceId.
 
Publish Publish (int connectionId, int payloadId, ReadOnlySpan< byte > payload)
 The same from a span, copied once into a buffer this instance owns.
 
Publish Publish (int connectionId, ushort groupMask, int payloadId, IDirectBuffer payload, int length)
 The same to the groups groupMask names as well as its own.
 
Publish Publish (int connectionId, ushort groupMask, int payloadId, ReadOnlySpan< byte > payload)
 The same from a span, copied once into a buffer this instance owns.
 
void Dispose ()
 Closes the cluster session and the queue. The Aeron client is the caller's and is left open.
 

Static Public Attributes

const long DefaultQueueStallTimeoutMs = Session.DefaultQueueStallTimeoutMs
 How long the queue may be silent before this instance is fenced — 20 heartbeat periods. The deployment policy every gateway had been copying.
 
const long DefaultRecoveryStallTimeoutMs = Session.DefaultRecoveryStallTimeoutMs
 How long recovery may dispatch nothing, once caught up before; longer than the queue's, as a re-walk is slower.
 
const int DefaultPendingCapacity = Session.DefaultPendingCapacity
 Frames in flight between a publish and the queue; far above what one round trip holds.
 
const int NoConnection = -1
 A frame that belongs to the gateway rather than to one of its connections, and what OpenConnection() answers when there is none to give.
 
const int Unresolved = GatewayLifecycle.Unresolved
 What SourceId and GatewayId read until a GatewayRegistered row names this instance. Nothing may be published under an unresolved identity, so a consumer that stamps its own records with SourceId checks for this first.
 

Properties

bool CanAccept [get]
 Whether a connection may be taken right now: this instance is serving, and ingress is not held behind a failover's resend. Check it before accepting or dialling — a connection taken while ingress is held could not have its ConnectionOpened placed.
 
bool IsActivated [get]
 Whether the last GatewayActive for this pair named this instance.
 
bool IsServing [get]
 Whether the edge is open — IGatewayListener.OnActivated has returned true and nothing has stood it down.
 
int SourceId [get]
 This logical gateway's sourceId, shared with its standby; Unresolved until a GatewayRegistered row names it.
 
int GatewayId [get]
 This instance's list row, or Unresolved until a row names it.
 
bool IsCaughtUp [get]
 
long LastClusterSeqNo [get]
 

Detailed Description

One instance of an elected active/standby producer pair. Everything this tier defines about being a gateway is behind it: the list row that names the instance, the designation that makes it serve, the GatewayStarted that binds its session, the connection id space it resumes from its predecessor, the connection lifecycle frames, confirmed ingress across a failover, and the fences that stand it down.

What is left to the consumer is its edge — a socket, a dialler, a codec. It opens that edge in IGatewayListener.OnActivated, closes it in IGatewayListener.OnStandby, and otherwise exchanges payloads: nothing of the frame layer or of seqeron's system vocabulary appears in its code.

Snapshots (doc/snapshot.md §4): given an ISnapshotListener and topology rows with snapshot="true", every instance serializes its state at each round's cut into its own directory, under a header carrying the pair's election state, and the active one then submits the round's SnapshotEnd. An instance whose snapshot differs from the one sequenced is fenced with ClusterError.SnapshotDiverged. On start, an instance given a listener restores the newest snapshot of its own that the log confirms and resumes after its cut, or replays from clusterSeqNo 1 without one; one it cannot restore is fenced with ClusterError.SnapshotUnrestorable.

Single-threaded: every member belongs to the caller's one duty-cycle thread, which calls DoWork each iteration. Gateway.java and app/Gateway.hpp are its twins; keep the three in step.

Constructor & Destructor Documentation

◆ Gateway()

Org.Limitless.Seqeron.App.Gateway.Gateway ( GatewayOptions  options)
inline

An instance configured by options ; nothing is connected until Start.

Exceptions
ArgumentExceptionif a required option is missing

Member Function Documentation

◆ CloseConnection()

void Org.Limitless.Seqeron.App.Gateway.CloseConnection ( int  connectionId)
inline

The same for a connection that has gone. One the cluster never heard of is dropped rather than announced.

◆ Dispose()

void Org.Limitless.Seqeron.App.Gateway.Dispose ( )
inline

Closes the cluster session and the queue. The Aeron client is the caller's and is left open.

◆ DoWork()

int Org.Limitless.Seqeron.App.Gateway.DoWork ( )
inline

One duty-cycle iteration: the cluster session and the queue, then whatever the connection lifecycle, the election and a snapshot round still owe. Nothing once fenced, so a designation dispatched in the cycle that fenced opens no gate.

Returns
units of work done, for the caller's idle strategy

◆ GateClosed()

void Org.Limitless.Seqeron.App.Gateway.GateClosed ( )
inline

The edge closed without being asked to — a dial that failed, a counterparty that hung up. The designation stands, so DoWork opens it again through IGatewayListener.OnActivated, and without a second GatewayStarted: this instance is still the one the cluster designated.

An acceptor whose listen socket stays bound never calls this. An initiator does: its edge is one dial, and a dial that fails or a session that drops is the gate closing under it.

◆ KeepAlive()

void Org.Limitless.Seqeron.App.Gateway.KeepAlive ( )
inline

Tells the cluster this instance is alive. DoWork already does it once a cycle; call this as well from inside an IGatewayListener callback that spins — writing to an edge that is back-pressured, say — since DoWork cannot run again until that callback returns, and the cluster drops a session that goes quiet for sequencer.sessionTimeoutMs. Self-throttling, so a call per spin costs nothing.

◆ OpenConnection() [1/3]

int Org.Limitless.Seqeron.App.Gateway.OpenConnection ( )
inline

The same for a connection whose only identity is its id.

◆ OpenConnection() [2/3]

int Org.Limitless.Seqeron.App.Gateway.OpenConnection ( IDirectBuffer  connectionData,
int  length 
)
inline

Takes one connection into the cluster's view of this gateway: allocates its id from the resume point and adds its ConnectionOpened to the backlog that DoWork places and retries.

Parameters
connectionDataopaque bytes the frame carries, from offset 0
lengthbytes of connectionData
Returns
the connection's id, or NoConnection if this instance is not serving

◆ OpenConnection() [3/3]

int Org.Limitless.Seqeron.App.Gateway.OpenConnection ( ReadOnlySpan< byte >  connectionData)
inline

The same from a span.

◆ Publish() [1/4]

Publish Org.Limitless.Seqeron.App.Gateway.Publish ( int  connectionId,
int  payloadId,
IDirectBuffer  payload,
int  length 
)
inline

Submits one application payload on a connection to this gateway's own group, stamped with its sourceId.

Parameters
connectionIdthe connection it belongs to
payloadIdwhich protocol the payload speaks
payloadthe payload's bytes from offset 0, its own MessageHeader included
lengthbytes of payload
Returns
Declined while ingress is held, back-pressured, or the connection's ConnectionOpened has not landed yet — retry it; Refused is permanent

◆ Publish() [2/4]

Publish Org.Limitless.Seqeron.App.Gateway.Publish ( int  connectionId,
int  payloadId,
ReadOnlySpan< byte >  payload 
)
inline

The same from a span, copied once into a buffer this instance owns.

◆ Publish() [3/4]

Publish Org.Limitless.Seqeron.App.Gateway.Publish ( int  connectionId,
ushort  groupMask,
int  payloadId,
IDirectBuffer  payload,
int  length 
)
inline

The same to the groups groupMask names as well as its own.

Parameters
connectionIdthe connection it belongs to
groupMaskbits from the GroupDirectory; one the table lacks is Refused
payloadIdwhich protocol the payload speaks
payloadthe payload's bytes from offset 0, its own MessageHeader included
lengthbytes of payload

◆ Publish() [4/4]

Publish Org.Limitless.Seqeron.App.Gateway.Publish ( int  connectionId,
ushort  groupMask,
int  payloadId,
ReadOnlySpan< byte >  payload 
)
inline

The same from a span, copied once into a buffer this instance owns.

◆ Start()

void Org.Limitless.Seqeron.App.Gateway.Start ( Aeron  aeron)
inline

Opens the cluster session and starts following this node's queue; the gate stays shut until designated.

Member Data Documentation

◆ DefaultPendingCapacity

const int Org.Limitless.Seqeron.App.Gateway.DefaultPendingCapacity = Session.DefaultPendingCapacity
static

Frames in flight between a publish and the queue; far above what one round trip holds.

◆ DefaultQueueStallTimeoutMs

const long Org.Limitless.Seqeron.App.Gateway.DefaultQueueStallTimeoutMs = Session.DefaultQueueStallTimeoutMs
static

How long the queue may be silent before this instance is fenced — 20 heartbeat periods. The deployment policy every gateway had been copying.

◆ DefaultRecoveryStallTimeoutMs

const long Org.Limitless.Seqeron.App.Gateway.DefaultRecoveryStallTimeoutMs = Session.DefaultRecoveryStallTimeoutMs
static

How long recovery may dispatch nothing, once caught up before; longer than the queue's, as a re-walk is slower.

◆ NoConnection

const int Org.Limitless.Seqeron.App.Gateway.NoConnection = -1
static

A frame that belongs to the gateway rather than to one of its connections, and what OpenConnection() answers when there is none to give.

◆ Unresolved

const int Org.Limitless.Seqeron.App.Gateway.Unresolved = GatewayLifecycle.Unresolved
static

What SourceId and GatewayId read until a GatewayRegistered row names this instance. Nothing may be published under an unresolved identity, so a consumer that stamps its own records with SourceId checks for this first.

Property Documentation

◆ CanAccept

bool Org.Limitless.Seqeron.App.Gateway.CanAccept
get

Whether a connection may be taken right now: this instance is serving, and ingress is not held behind a failover's resend. Check it before accepting or dialling — a connection taken while ingress is held could not have its ConnectionOpened placed.

◆ GatewayId

int Org.Limitless.Seqeron.App.Gateway.GatewayId
get

This instance's list row, or Unresolved until a row names it.

◆ IsActivated

bool Org.Limitless.Seqeron.App.Gateway.IsActivated
get

Whether the last GatewayActive for this pair named this instance.

◆ IsCaughtUp

bool Org.Limitless.Seqeron.App.Gateway.IsCaughtUp
get

◆ IsServing

bool Org.Limitless.Seqeron.App.Gateway.IsServing
get

Whether the edge is open — IGatewayListener.OnActivated has returned true and nothing has stood it down.

◆ LastClusterSeqNo

long Org.Limitless.Seqeron.App.Gateway.LastClusterSeqNo
get

◆ SourceId

int Org.Limitless.Seqeron.App.Gateway.SourceId
get

This logical gateway's sourceId, shared with its standby; Unresolved until a GatewayRegistered row names it.


The documentation for this class was generated from the following file: