Flow Control & Windowing

Relevant source files

The following files were used as context for generating this wiki page:

• doc/relp.html
• src/relp.h
• src/relpsess.h
• src/librelp.h
• src/relp.c
• src/scrsp.c
• tests/send.c

The Reliable Event Logging Protocol (RELP) utilizes a windowing mechanism to manage flow control and ensure reliable delivery of messages. This system limits the number of outstanding (unacknowledged) commands that a client can issue at any given time, preventing the sender from overwhelming the receiver or the network.

Flow control in RELP is achieved through application-level acknowledgments. Each command is assigned a unique Transaction Number (TXNR). The server must respond to each command using a "rsp" frame that references the original TXNR. The transmission window defines the maximum number of these unacknowledged transactions permitted simultaneously.

Sources: doc/relp.html, src/relpsess.h:116-118

Transaction Window Mechanism

The RELP windowing mechanism is a credit-based system where the client tracks "in-flight" messages. When a client sends a command, the transaction is added to an unacknowledged list. If the number of entries in this list reaches the configured window size, the session state transitions to WINDOW_FULL, and further sending is suspended until acknowledgments arrive.

Window Components and Constraints

The following table summarizes the primary elements governing the windowing logic:

Component	Description	Default / Limit
TXNR	Transaction Number: a monotonically increasing ID for each command.	Starts at 1; Latched at 999,999,999.
Window Size	The maximum number of outstanding commands permitted.	Default: 128 unacked frames.
Unacked List	A linked list maintained by the client to track outstanding transactions.	Defined in relpSessUnacked_t.
DATALEN	The maximum size of the data portion of a single RELP frame.	Negotiated; Default 128K.

Sources: doc/relp.html, src/relp.h:184-186, src/relpsess.h:51-54

Transaction Lifecycle

The lifecycle of a RELP transaction involves the assignment of a TXNR, transmission, and the eventual clearing of the window upon reception of a response.

Implementation Details

Session States and Flow

The session object (relpSess_t) tracks the state of the window. When the unacknowledged count exceeds the window size, the session enters a state that inhibits further transmission.

Data Structures

The management of flow control relies on the relpSess_s structure, which tracks the window size and the list of unacknowledged frames.

struct relpSess_s {
    /* ... other members ... */
    int sizeWindow;             /**< size of our app-level communications window */
    relpSessUnacked_t *pUnackedLstRoot;
    relpSessUnacked_t *pUnackedLstLast;
    int lenUnackedLst;
    relpSessState_t sessState;  /**< e.g., eRelpSessState_WINDOW_FULL */
};

Sources: src/relpsess.h:116-121

Response Processing

When a rsp command is received by the client, the relpSCRsp handler is invoked. This function performs the following steps to manage the window:

1. Extracts the TXNR from the response frame.
2. Locates the corresponding entry in the session's unacknowledged list via relpSessGetUnacked.
3. Invokes the callback handler associated with that transaction.
4. Destructs the send buffer and removes the entry from the unacknowledged list, effectively "opening" a slot in the window.

Sources: src/scrsp.c:100-120

Oversize Management

Flow control is also affected by individual frame sizes. RELP allows for negotiation of the maximum data length (maxDataSize). If a sender attempts to exceed these limits, the receiver's behavior is governed by the oversizeMode.

Mode	Action
RELP_OVERSIZE_ABORT	Immediately closes the connection if a frame is too large.
RELP_OVERSIZE_TRUNCATE	Truncates the frame but keeps the session active.
RELP_OVERSIZE_ACCEPT	Accepts the frame despite the risk of resource exhaustion.

Sources: src/librelp.h:134-137, src/relp.h:188-190

Conclusion

Flow control and windowing in librelp provide a robust mechanism for ensuring reliable delivery without overloading peers. By combining strictly ordered transaction numbers with an application-level acknowledgment window, the protocol guarantees that data is not only delivered but confirmed by the remote server before the sender proceeds beyond its operational limits. This architecture is vital for high-latency environments (e.g., satellite links) where a large window can be configured to maintain high throughput while still ensuring no data is lost during session interruptions.

Sources: doc/relp.html