The distributed request/response fabric: RequestClient posts requests, RequestGateway routes and load-balances them, RequestExecutor processes them and replies. More...

Detailed Description

The distributed request/response fabric: RequestClient posts requests, RequestGateway routes and load-balances them, RequestExecutor processes them and replies.

Why a request fabric: Plain Messaging is fire-and-forget publish/subscribe; many interactions instead need an answer: "run this query", "fetch this status", "execute this command and tell me the result". The request system adds exactly that on top of the CMSDK network layer: correlation of each reply with its request, per-request timeouts, load balancing across multiple workers, and automatic reconnection/re-queuing when a gateway briefly disappears — all things you would otherwise hand-roll per application with raw sockets or an external RPC stack. Because payloads are ordinary DataMessage objects, the same request fabric also serves HTTP and WebSocket clients through the gateway without a separate web stack.

The three roles

RequestClient (this header) — application-facing sender. Wraps each outgoing DataMessage in a RequestReply "future"; the caller blocks on RequestReply::waitForResult() or registers a RequestCallbackFunction.
RequestGateway (RequestGateway.h) — router/load balancer. Accepts requests from many clients (binary, HTTP or WebSocket), queues them, picks the best executor (short vs long requests, queue sizes, heartbeats) and routes replies back to the originating client.
RequestExecutor (RequestExecutor.h) — the worker. Pulls requests from its gateway connection, processes them and replies.

A complete round-trip: // Client side

RequestClient client;

client.addGateway(1, "gateway.host", 9000); // register a gateway

client.waitForConnection(5000); // wait up to 5 s

DataMessage* msg = RequestClient::CreateRequestMessage(

HTTP_GET, "status", "detail", "full"); // build the request payload

RequestReply* reply = client.postRequest(msg); // async send, returns a future

if (reply->waitForResult(3000) == SUCCESS) { // block up to 3 s

DataMessage* answer = reply->peekReplyMessage(); // still owned by reply

// ... read fields from answer ...

}

client.finishRequest(reply); // release slot + reply message

HTTP_GET
#define HTTP_GET
GET.
Definition NetworkProtocols.h:92

On the worker side a RequestExecutor connects to the same gateway, receives the DataMessage, and answers with a reply message that the gateway routes back to this client, completing the RequestReply.

Note: Ownership: the reply DataMessage returned by peekReplyMessage() is owned by the RequestReply — do not delete it; it is released by finishRequest(). Take a copy if you need the data afterwards.

Warning: Always pair postRequest() with finishRequest(), even on timeout or failure, or the client's request slots leak. Choose timeouts that cover gateway queuing plus executor processing time, not just network latency.

See also: RequestClient, RequestReply, RequestGateway, RequestExecutor, Messaging, Networking

Files
file	RequestExecutor.h
	Request-system worker side: RequestExecutor pulls requests from a RequestGateway, processes them and replies.
file	RequestGateway.h
	Request-system router: RequestGateway accepts client requests (binary/HTTP/WebSocket), load-balances them across RequestExecutors and routes replies back; includes a call log and an embedded web server.
file	RequestClient.cpp
	Implementation of the request-system client side: RequestReply completion/waiting, RequestClient's gateway connection upkeep, request dispatch and reply matching, plus the load-test clients used by the gateway unit test.
file	RequestExecutor.cpp
	Implementation of the request-system worker side: gateway link upkeep with heartbeats, short/long request queueing and the reply path, plus the delay-simulating TestRequestExecutor.
file	RequestGateway.cpp
	Implementation of the request-system router: ingress over binary/ HTTP/WebSocket, executor load balancing and liveness (heartbeat timeout, dead-executor redistribution), reply routing, the RequestQueue, call logging, the built-in web server/APIs, and the end-to-end unit test.

Classes
class	cmlabs::RequestReply
	Future/handle for one in-flight request: holds the request message, the eventual reply, status, timing and routing references. More...
class	cmlabs::RequestQueue
	Priority-ordered queue of pending RequestReply objects (per executor connection). More...
struct	cmlabs::RequestConnection
	Gateway-side record of one connected client or executor. More...
struct	cmlabs::RequestGatewayConnection
	Client/executor-side record of one gateway it connects to. More...
class	cmlabs::RequestClient
	Application-facing client of the request system: posts DataMessage requests to one or more RequestGateways and delivers replies. More...
class	cmlabs::TestRequestClient
	Load-test client driving a RequestGateway with binary-protocol requests at a configurable frequency/payload (used by RequestGateway::UnitTest()). More...
class	cmlabs::TestWebRequestClient
	Load-test client driving a RequestGateway over plain HTTP web requests. More...
class	cmlabs::TestWebSocketRequestClient
	Load-test client driving a RequestGateway over WebSocket connections. More...
class	cmlabs::RequestExecutor
	Worker node of the request system: receives requests from gateways, queues them by class (short/long) and sends back replies. More...
class	cmlabs::TestRequestExecutor
	Test executor that services requests with a configurable artificial processing delay; used by RequestGateway::UnitTest(). More...
class	cmlabs::CallLogEntry
	One entry of the gateway's call log: who called what, how it was routed, how long each stage took, and the outcome. More...
class	cmlabs::RequestGateway
	The request-fabric router/load-balancer (see the file header for the full role description). More...

Typedefs
typedef void(*	cmlabs::RequestCallbackFunction) (RequestReply &reply)
	Signature for asynchronous completion callbacks registered on a RequestReply.

Enumerations
enum	cmlabs::RequestStatus { cmlabs::NONE = 0 , cmlabs::IDLE = 1 , cmlabs::QUEUED = 2 , cmlabs::PROCESSING = 3 , cmlabs::SENT = 4 , cmlabs::SUCCESS = 5 , cmlabs::FAILED = 6 , cmlabs::TIMEOUT = 7 , cmlabs::TOOBUSY = 8 , cmlabs::LOCALERROR = 9 , cmlabs::NETWORKERROR = 10 , cmlabs::SERVERERROR = 11 }
	Lifecycle states of a request as it moves through client, gateway and executor. More...

Functions
THREAD_RET THREAD_FUNCTION_CALL	cmlabs::RequestClientRun (THREAD_ARG arg)
	Thread entry point for the RequestClient worker loop.
THREAD_RET THREAD_FUNCTION_CALL	cmlabs::RequestExecutorRun (THREAD_ARG arg)
	Thread entry point for the RequestExecutor worker loop.
THREAD_RET THREAD_FUNCTION_CALL	cmlabs::RequestGatewayExecRun (THREAD_ARG arg)
	Thread entry point for the gateway's executor-side loop.
THREAD_RET THREAD_FUNCTION_CALL	cmlabs::RequestGatewayClientRun (THREAD_ARG arg)
	Thread entry point for the gateway's client-side loop.

Typedef Documentation

◆ RequestCallbackFunction

typedef void(* cmlabs::RequestCallbackFunction) (RequestReply &reply)

Signature for asynchronous completion callbacks registered on a RequestReply.

Invoked on an internal client thread when the request completes (any status).

Definition at line 114 of file RequestClient.h.

Enumeration Type Documentation

◆ RequestStatus

enum cmlabs::RequestStatus

Lifecycle states of a request as it moves through client, gateway and executor.

Terminal states (SUCCESS and the failure states) make RequestReply::isComplete() true.

Enumerator
NONE
IDLE
QUEUED
PROCESSING
SENT
SUCCESS
FAILED
TIMEOUT
TOOBUSY
LOCALERROR
NETWORKERROR
SERVERERROR

Definition at line 119 of file RequestClient.h.

Function Documentation

◆ RequestClientRun()

THREAD_RET THREAD_FUNCTION_CALL cmlabs::RequestClientRun ( THREAD_ARG arg )

Thread entry point for the RequestClient worker loop.

Definition at line 704 of file RequestClient.cpp.

◆ RequestExecutorRun()

THREAD_RET THREAD_FUNCTION_CALL cmlabs::RequestExecutorRun ( THREAD_ARG arg )

Thread entry point for the RequestExecutor worker loop.

Definition at line 511 of file RequestExecutor.cpp.

◆ RequestGatewayClientRun()

THREAD_RET THREAD_FUNCTION_CALL cmlabs::RequestGatewayClientRun ( THREAD_ARG arg )

Thread entry point for the gateway's client-side loop.

Definition at line 2470 of file RequestGateway.cpp.

◆ RequestGatewayExecRun()

THREAD_RET THREAD_FUNCTION_CALL cmlabs::RequestGatewayExecRun ( THREAD_ARG arg )

Thread entry point for the gateway's executor-side loop.

Definition at line 2465 of file RequestGateway.cpp.

Detailed Description

Files

Classes

Typedefs

Enumerations

Functions