Future/handle for one in-flight request: holds the request message, the eventual reply, status, timing and routing references. More...

#include <RequestClient.h>

Collaboration diagram for cmlabs::RequestReply:

[legend]

Public Member Functions
	RequestReply ()
virtual	~RequestReply ()
bool	isComplete ()
bool	setStatus (RequestStatus status)
	Set the current lifecycle status (wakes waiters when terminal).
RequestStatus	getStatus ()
std::string	getStatusText ()
bool	setCallback (RequestCallbackFunction callback)
	Register a completion callback (alternative to blocking waits).
RequestCallbackFunction	getCallback ()
bool	replyToRequest (DataMessage *msg, RequestStatus status)
	Complete this request with a reply (called by the network layer).
bool	giveRequestMessage (DataMessage *msg)
	Attach the outgoing request message, transferring ownership.
bool	setRequestMessageCopy (DataMessage *msg)
	Attach a copy of the outgoing request message (caller keeps `msg`).
DataMessage *	getRequestMessageCopy ()
DataMessage *	peekRequestMessage ()
bool	giveReplyMessage (DataMessage *msg)
	Attach the reply message, transferring ownership.
bool	setReplyMessageCopy (DataMessage *msg)
	Attach a copy of the reply message (caller keeps `msg`).
DataMessage *	getReplyMessageCopy ()
DataMessage *	peekReplyMessage ()
RequestStatus	waitForResult (uint32 timeoutMS)
	Block until the request reaches a terminal status or the timeout expires.
DataMessage *	waitForMessage (uint32 timeoutMS, bool takeMessage=false)
	Block for the reply message itself.
uint64	getRequestDuration ()
uint32	getRequestDurationMS ()

Public Attributes
uint64	startTime
	When the request was created (ms epoch).
uint64	finishTime
	When a terminal status was set (ms epoch; 0 while pending).
uint64	origin
	Originating endpoint/connection (packed uint64), for reply routing.
uint64	processor
	Executor id that processed (or is processing) the request.
uint64	clientRef
	Client-side reference id correlating request and reply.
uint64	execRef
	Executor-side reference id.
uint64	gatewayRef
	Gateway-side reference id.
uint64	customRef
	Free-form reference for application use.
uint32	systemID
	Id of the system/gateway this request belongs to.
bool	isLongReq
	True when classified as a long-running request (separate queue/limits).
bool	isInUse
	Pooling flag: false once finishRequest() releases the object for reuse.

Protected Attributes
RequestCallbackFunction	callback
RequestStatus	status
DataMessage *	replyMsg
DataMessage *	requestMsg
utils::Mutex	mutex
utils::Semaphore	semaphore

Detailed Description

Future/handle for one in-flight request: holds the request message, the eventual reply, status, timing and routing references.

Created by RequestClient::postRequest() (or internally by the gateway). The caller waits with waitForResult()/waitForMessage() or registers a RequestCallbackFunction, then returns the object to the client with RequestClient::finishRequest() — do not delete it directly when it came from a client, as objects are pooled/reused (::isInUse).

Thread-safety: Internally synchronised (mutex + semaphore); the completing network thread calls replyToRequest() while the application thread blocks in waitForResult().

Definition at line 134 of file RequestClient.h.

Constructor & Destructor Documentation

◆ RequestReply()

cmlabs::RequestReply::RequestReply ( )

inline

Definition at line 145 of file RequestClient.h.

References callback, clientRef, customRef, execRef, finishTime, gatewayRef, cmlabs::GetTimeNow(), cmlabs::IDLE, isInUse, isLongReq, origin, processor, replyMsg, requestMsg, startTime, status, and systemID.

◆ ~RequestReply()

virtual cmlabs::RequestReply::~RequestReply ( )

inlinevirtual

Definition at line 146 of file RequestClient.h.

References callback, cmlabs::IDLE, replyMsg, requestMsg, and status.

Member Function Documentation

◆ getCallback()

RequestCallbackFunction cmlabs::RequestReply::getCallback ( )

Returns: The registered callback, or NULL.

Definition at line 94 of file RequestClient.cpp.

References callback, and mutex.

◆ getReplyMessageCopy()

DataMessage * cmlabs::RequestReply::getReplyMessageCopy ( )

Returns: A new copy of the reply message (caller owns it), or NULL.

Definition at line 172 of file RequestClient.cpp.

References mutex, and replyMsg.

◆ getRequestDuration()

uint64 cmlabs::RequestReply::getRequestDuration ( )

Returns: Total request duration in microseconds (finish - start).

Definition at line 209 of file RequestClient.cpp.

References finishTime, and startTime.

Referenced by cmlabs::TestRequestClient::run(), and cmlabs::RequestGateway::UnitTest().

◆ getRequestDurationMS()

uint32 cmlabs::RequestReply::getRequestDurationMS ( )

Returns: Total request duration in milliseconds.

Definition at line 216 of file RequestClient.cpp.

References finishTime, and startTime.

◆ getRequestMessageCopy()

DataMessage * cmlabs::RequestReply::getRequestMessageCopy ( )

Returns: A new copy of the request message (caller owns it), or NULL.

Definition at line 136 of file RequestClient.cpp.

References mutex, and requestMsg.

◆ getStatus()

RequestStatus cmlabs::RequestReply::getStatus ( )

Returns: The current lifecycle status.

Definition at line 52 of file RequestClient.cpp.

References cmlabs::LOCALERROR, mutex, and status.

Referenced by cmlabs::RequestQueue::getNextRequest(), cmlabs::RequestQueue::getNextTimedoutRequest(), cmlabs::RequestQueue::removeStaleRequests(), cmlabs::RequestGateway::replyToClient(), cmlabs::TestRequestClient::run(), and cmlabs::RequestQueue::UnitTest().

◆ getStatusText()

std::string cmlabs::RequestReply::getStatusText ( )

Returns: Human-readable name of the current status (e.g. "Success").

Definition at line 62 of file RequestClient.cpp.

References cmlabs::FAILED, cmlabs::IDLE, cmlabs::LOCALERROR, mutex, cmlabs::NETWORKERROR, cmlabs::QUEUED, cmlabs::SENT, cmlabs::SERVERERROR, status, cmlabs::SUCCESS, cmlabs::TIMEOUT, and cmlabs::TOOBUSY.

◆ giveReplyMessage()

bool cmlabs::RequestReply::giveReplyMessage ( DataMessage * msg )

Attach the reply message, transferring ownership.

Parameters

msg Reply.

Returns: true.

Definition at line 149 of file RequestClient.cpp.

References mutex, and replyMsg.

◆ giveRequestMessage()

bool cmlabs::RequestReply::giveRequestMessage ( DataMessage * msg )

Attach the outgoing request message, transferring ownership.

Parameters

msg	Request message (owned by this object afterwards).

Returns: true.

Definition at line 111 of file RequestClient.cpp.

References cmlabs::DataMessage::getSystemID(), mutex, requestMsg, and systemID.

Referenced by cmlabs::RequestGateway::addToRequestQueue(), cmlabs::RequestClient::postRequest(), cmlabs::RequestExecutor::receiveMessage(), and cmlabs::RequestQueue::UnitTest().

◆ isComplete()

bool cmlabs::RequestReply::isComplete ( )

Returns: true once a terminal status (SUCCESS or any failure) has been set.

Definition at line 28 of file RequestClient.cpp.

References cmlabs::FAILED, cmlabs::LOCALERROR, cmlabs::NETWORKERROR, cmlabs::SERVERERROR, status, cmlabs::SUCCESS, cmlabs::TIMEOUT, and cmlabs::TOOBUSY.

Referenced by cmlabs::TestRequestClient::run(), and waitForResult().

◆ peekReplyMessage()

DataMessage * cmlabs::RequestReply::peekReplyMessage ( )

Returns: The internal reply message without transferring ownership (may be NULL).

Warning: The pointer remains owned by this RequestReply; it becomes dangling as soon as RequestClient::finishRequest() is called on the reply. Copy any data you need first (or use getReplyMessageCopy()).

Definition at line 181 of file RequestClient.cpp.

References replyMsg.

◆ peekRequestMessage()

DataMessage * cmlabs::RequestReply::peekRequestMessage ( )

Returns: The internal request message without transferring ownership (may be NULL).

Definition at line 145 of file RequestClient.cpp.

References requestMsg.

Referenced by cmlabs::RequestGateway::addRequestReplyToRequestQueue(), cmlabs::RequestGateway::replyToClient(), cmlabs::RequestGateway::runExec(), and cmlabs::RequestClient::sendRequest().

◆ replyToRequest()

bool cmlabs::RequestReply::replyToRequest	(	DataMessage *	msg,
		RequestStatus	status )

Complete this request with a reply (called by the network layer).

Parameters

msg	Reply message (ownership transfers to this object; may be NULL on failure).
status	Terminal status to set.

Returns: true on success. Wakes any waiter and fires the callback.

Definition at line 185 of file RequestClient.cpp.

References finishTime, cmlabs::GetTimeNow(), mutex, replyMsg, semaphore, and status.

Referenced by cmlabs::RequestClient::receiveMessage(), and cmlabs::RequestClient::sendRequest().

◆ setCallback()

bool cmlabs::RequestReply::setCallback ( RequestCallbackFunction callback )

Register a completion callback (alternative to blocking waits).

Parameters

callback Invoked on an internal thread when the request completes.

Returns: true on success.

Definition at line 103 of file RequestClient.cpp.

References callback, and mutex.

◆ setReplyMessageCopy()

bool cmlabs::RequestReply::setReplyMessageCopy ( DataMessage * msg )

Attach a copy of the reply message (caller keeps msg).

Returns: true on success.

Definition at line 159 of file RequestClient.cpp.

References mutex, and replyMsg.

◆ setRequestMessageCopy()

bool cmlabs::RequestReply::setRequestMessageCopy ( DataMessage * msg )

Attach a copy of the outgoing request message (caller keeps msg).

Parameters

msg	Message to copy.

Returns: true on success.

Definition at line 122 of file RequestClient.cpp.

References cmlabs::DataMessage::getSystemID(), mutex, requestMsg, and systemID.

◆ setStatus()

bool cmlabs::RequestReply::setStatus ( RequestStatus status )

Set the current lifecycle status (wakes waiters when terminal).

Parameters

status New status.

Returns: true on success.

Definition at line 44 of file RequestClient.cpp.

References mutex, and status.

Referenced by cmlabs::RequestGateway::addRequestReplyToRequestQueue(), cmlabs::RequestGateway::addToRequestQueue(), cmlabs::RequestGateway::distributeDeadExecutorRequests(), cmlabs::RequestQueue::getNextRequest(), cmlabs::RequestClient::postRequest(), cmlabs::RequestExecutor::receiveMessage(), cmlabs::RequestQueue::removeStaleRequests(), cmlabs::RequestGateway::runExec(), cmlabs::RequestClient::sendRequest(), and cmlabs::RequestQueue::UnitTest().

◆ waitForMessage()

DataMessage * cmlabs::RequestReply::waitForMessage	(	uint32	timeoutMS,
		bool	takeMessage = false )

Block for the reply message itself.

Parameters

timeoutMS	Max wait in milliseconds.
takeMessage	Transfer ownership of the reply to the caller when true.

Returns: The reply message, or NULL on timeout/failure. Blocking.

Warning: Ownership is the classic footgun here. With the default takeMessage = false the returned pointer is still owned by this RequestReply and is deleted by RequestClient::finishRequest() (which deletes the whole reply object) — never delete it yourself and never use it after finishRequest(). With takeMessage = true ownership transfers to the caller, who must delete the message exactly once; the reply's internal pointer is cleared, so a second call returns NULL.

Definition at line 250 of file RequestClient.cpp.

References finishTime, mutex, replyMsg, and semaphore.

Referenced by cmlabs::RequestClient::SendRequestAndWaitForReply(), and cmlabs::Test_RequestClient().

◆ waitForResult()

RequestStatus cmlabs::RequestReply::waitForResult ( uint32 timeoutMS )

Block until the request reaches a terminal status or the timeout expires.

Parameters

timeoutMS Max wait in milliseconds.

Returns: The status at return time (TIMEOUT if still pending). Blocking.

Definition at line 223 of file RequestClient.cpp.

References isComplete(), cmlabs::LOCALERROR, mutex, semaphore, status, and cmlabs::TIMEOUT.

Referenced by cmlabs::RequestClient::SendRequestAndWaitForReplyObject(), and cmlabs::RequestGateway::UnitTest().

Member Data Documentation

◆ callback

RequestCallbackFunction cmlabs::RequestReply::callback

protected

Definition at line 137 of file RequestClient.h.

Referenced by getCallback(), RequestReply(), setCallback(), and ~RequestReply().

◆ clientRef

uint64 cmlabs::RequestReply::clientRef

Client-side reference id correlating request and reply.

Definition at line 152 of file RequestClient.h.

Referenced by cmlabs::RequestGateway::addToRequestQueue(), cmlabs::RequestClient::finishRequest(), cmlabs::RequestClient::postRequest(), cmlabs::RequestGateway::replyToClient(), RequestReply(), and cmlabs::RequestQueue::UnitTest().

◆ customRef

uint64 cmlabs::RequestReply::customRef

Free-form reference for application use.

Definition at line 155 of file RequestClient.h.

Referenced by RequestReply().

◆ execRef

uint64 cmlabs::RequestReply::execRef

Executor-side reference id.

Definition at line 153 of file RequestClient.h.

Referenced by cmlabs::RequestExecutor::receiveMessage(), and RequestReply().

◆ finishTime

uint64 cmlabs::RequestReply::finishTime

When a terminal status was set (ms epoch; 0 while pending).

Definition at line 149 of file RequestClient.h.

Referenced by getRequestDuration(), getRequestDurationMS(), replyToRequest(), RequestReply(), and waitForMessage().

◆ gatewayRef

uint64 cmlabs::RequestReply::gatewayRef

Gateway-side reference id.

Definition at line 154 of file RequestClient.h.

Referenced by cmlabs::RequestQueue::addRequest(), cmlabs::RequestGateway::addRequestReplyToRequestQueue(), cmlabs::RequestGateway::addToRequestQueue(), cmlabs::RequestExecutor::receiveMessage(), cmlabs::RequestGateway::replyToClient(), cmlabs::RequestExecutor::replyToGateway(), RequestReply(), cmlabs::RequestGateway::runExec(), and cmlabs::RequestQueue::UnitTest().

◆ isInUse

bool cmlabs::RequestReply::isInUse

Pooling flag: false once finishRequest() releases the object for reuse.

Definition at line 158 of file RequestClient.h.

Referenced by cmlabs::RequestClient::receiveMessage(), and RequestReply().

◆ isLongReq

bool cmlabs::RequestReply::isLongReq

True when classified as a long-running request (separate queue/limits).

Definition at line 157 of file RequestClient.h.

Referenced by cmlabs::RequestGateway::addRequestReplyToRequestQueue(), cmlabs::RequestGateway::replyToClient(), RequestReply(), and cmlabs::RequestGateway::runExec().

◆ mutex

utils::Mutex cmlabs::RequestReply::mutex

protected

Definition at line 141 of file RequestClient.h.

Referenced by getCallback(), getReplyMessageCopy(), getRequestMessageCopy(), getStatus(), getStatusText(), giveReplyMessage(), giveRequestMessage(), replyToRequest(), setCallback(), setReplyMessageCopy(), setRequestMessageCopy(), setStatus(), waitForMessage(), and waitForResult().

◆ origin

uint64 cmlabs::RequestReply::origin

Originating endpoint/connection (packed uint64), for reply routing.

Definition at line 150 of file RequestClient.h.

Referenced by cmlabs::RequestQueue::addRequest(), cmlabs::RequestGateway::addRequestReplyToRequestQueue(), cmlabs::RequestGateway::addToRequestQueue(), cmlabs::RequestExecutor::receiveMessage(), cmlabs::RequestGateway::replyToClient(), cmlabs::RequestExecutor::replyToGateway(), RequestReply(), cmlabs::RequestGateway::runExec(), and cmlabs::RequestQueue::UnitTest().

◆ processor

uint64 cmlabs::RequestReply::processor

Executor id that processed (or is processing) the request.

Definition at line 151 of file RequestClient.h.

Referenced by cmlabs::RequestGateway::addRequestReplyToRequestQueue(), cmlabs::RequestGateway::replyToClient(), RequestReply(), and cmlabs::RequestGateway::runExec().

◆ replyMsg

DataMessage* cmlabs::RequestReply::replyMsg

protected

Definition at line 139 of file RequestClient.h.

Referenced by getReplyMessageCopy(), giveReplyMessage(), peekReplyMessage(), replyToRequest(), RequestReply(), setReplyMessageCopy(), waitForMessage(), and ~RequestReply().

◆ requestMsg

DataMessage* cmlabs::RequestReply::requestMsg

protected

Definition at line 140 of file RequestClient.h.

Referenced by getRequestMessageCopy(), giveRequestMessage(), peekRequestMessage(), RequestReply(), setRequestMessageCopy(), and ~RequestReply().

◆ semaphore

utils::Semaphore cmlabs::RequestReply::semaphore

protected

Definition at line 142 of file RequestClient.h.

Referenced by replyToRequest(), waitForMessage(), and waitForResult().

◆ startTime

uint64 cmlabs::RequestReply::startTime

When the request was created (ms epoch).

Definition at line 148 of file RequestClient.h.

Referenced by getRequestDuration(), getRequestDurationMS(), cmlabs::RequestQueue::removeStaleRequests(), cmlabs::RequestGateway::replyToClient(), and RequestReply().

◆ status

RequestStatus cmlabs::RequestReply::status

protected

Definition at line 138 of file RequestClient.h.

Referenced by getStatus(), getStatusText(), isComplete(), replyToRequest(), RequestReply(), setStatus(), waitForResult(), and ~RequestReply().

◆ systemID

uint32 cmlabs::RequestReply::systemID

Id of the system/gateway this request belongs to.

Definition at line 156 of file RequestClient.h.

Referenced by giveRequestMessage(), RequestReply(), and setRequestMessageCopy().

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

/home/ubuntu/c/partner/psyclone2/CMSDK/include/RequestClient.h
/home/ubuntu/c/partner/psyclone2/CMSDK/src/RequestClient.cpp

Public Member Functions

Public Attributes

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ RequestReply()

◆ ~RequestReply()

Member Function Documentation

◆ getCallback()

◆ getReplyMessageCopy()

◆ getRequestDuration()

◆ getRequestDurationMS()

◆ getRequestMessageCopy()

◆ getStatus()

◆ getStatusText()

◆ giveReplyMessage()

◆ giveRequestMessage()

◆ isComplete()

◆ peekReplyMessage()

◆ peekRequestMessage()

◆ replyToRequest()

◆ setCallback()

◆ setReplyMessageCopy()

◆ setRequestMessageCopy()

◆ setStatus()

◆ waitForMessage()

◆ waitForResult()

Member Data Documentation

◆ callback

◆ clientRef

◆ customRef

◆ execRef

◆ finishTime

◆ gatewayRef

◆ isInUse

◆ isLongReq

◆ mutex

◆ origin

◆ processor

◆ replyMsg

◆ requestMsg

◆ semaphore

◆ startTime

◆ status

◆ systemID