The runtime container (one OS process/node context) hosting Psyclone components. More...

#include <PsySpace.h>

Inheritance diagram for cmlabs::PsySpace:

Collaboration diagram for cmlabs::PsySpace:

Public Member Functions
	PsySpace (const char *name=NULL, bool isAdHoc=true, uint16 procID=0, bool isLocal=false)
	Create a space (does not yet join a system; call connect()).
	~PsySpace ()
	Destructor.
bool	connect (uint16 systemID, bool isMaster=false, const char *cmdline=NULL)
	Join a Psyclone system (attach to the node's shared memory).
bool	isConnected (uint32 timeoutMS=5000)
	Wait until the space is fully connected to the system.
bool	reset ()
	Reset the space's runtime state (counters, queues) without disconnecting.
bool	start (uint16 threadCount=5)
	Start processing: spin up the thread pool and begin dispatching triggers.
bool	shutdown ()
	Request an orderly shutdown of the space and all its components.
bool	hasShutdown ()
uint16	getID ()
bool	postMessage (DataMessage *msg)
	Post a raw message into the system for distribution to subscribers.
bool	emitSignal (const PsyType &type, DataMessage *msg)
	Emit a system-wide signal of the given type.
DataMessage *	waitForSignal (const PsyType &type, uint32 timeout, uint64 lastReceivedTime=0)
	Block until a signal of the given type arrives (or has already arrived).
uint8	query (DataMessage msg, DataMessage *result, uint32 timeout)
	Send a query message and wait for its reply.
bool	queryReply (uint32 id, uint8 status, DataMessage *result)
	Reply to a previously received query.
uint32	getComponentID (const char *name)
	Look up the numeric component id for a component name.
PsyAPI *	getCrankAPI (const char *name)
	Get (or create) the PsyAPI handle for a crank hosted in this space.
bool	registerCrankCallback (const char *name, CrankFunction func)
	Register a C/C++ entry function for a crank, to be invoked by the thread pool when the component triggers.
bool	addPsyProbeCustomView (uint32 compID, const char name, const char templateURL)
	Add a custom PsyProbe view tab for a component (space-level variant of PsyAPI::addPsyProbeCustomView()).
bool	logEntry (LogEntry *entry)
	LogReceiver interface: accept a log entry produced within this space.
Public Member Functions inherited from cmlabs::Runnable
	Runnable ()
	Initialise flags: not running, allowed to continue.
virtual	~Runnable ()
	Destructor requests a stop (with the default timeout) before destruction proceeds.
virtual bool	stop (uint32 timeout=200)
	Ask the worker loop to finish and wait for it to do so.
Public Member Functions inherited from cmlabs::LogReceiver
	LogReceiver ()

Public Attributes
MemoryManager *	manager
	The process-local memory manager: entry point to the node's shared-memory fabric. Owned by the space.

Friends
class	PsyAPI
THREAD_RET THREAD_FUNCTION_CALL	PsySpaceRun (THREAD_ARG arg)
	Thread entry for the space's main service thread.
THREAD_RET THREAD_FUNCTION_CALL	PsySpacePoolRun (THREAD_ARG arg)
	Thread entry for pool worker threads.
THREAD_RET THREAD_FUNCTION_CALL	PsySpaceContinuousRun (THREAD_ARG arg)
	Thread entry for continuously running components.

Additional Inherited Members
Protected Attributes inherited from cmlabs::Runnable
uint32	threadID
	ThreadManager slot ID of the worker thread (0 until known).
bool	shouldContinue
	Loop-continuation flag; cleared by stop().
bool	isRunning
	Set by the worker while its loop is active.

Detailed Description

The runtime container (one OS process/node context) hosting Psyclone components.

PsySpace is the flagship embedding object of the CMSDK. Creating a PsySpace and calling connect() joins the calling process to a Psyclone system: it attaches to (or creates) the node's shared memory via MemoryManager, registers the process, and starts the service threads. After start(), the space's thread pool waits for trigger messages and dispatches them to the registered crank callbacks through each component's PsyAPI handle.

Ownership/lifetime: the PsySpace owns its MemoryManager, TimeQueue, loaded crank libraries and all PsyAPI objects it creates. Destroy the space only after shutdown() has completed (see hasShutdown()).

Thread-safety: the public control methods (connect/start/shutdown/post/emit/ query) are safe to call from application threads; internal state is protected by dedicated mutexes.

See also: PsyAPI for the component-facing API surface.

Definition at line 164 of file PsySpace.h.

Constructor & Destructor Documentation

◆ PsySpace()

cmlabs::PsySpace::PsySpace	(	const char *	name = NULL,
		bool	isAdHoc = true,
		uint16	procID = 0,
		bool	isLocal = false )

Create a space (does not yet join a system; call connect()).

Parameters

name	Human-readable process name shown in logs and PsyProbe; NULL for a generated name.
isAdHoc	true (default) if this process was started manually rather than launched by a Psyclone node supervisor.
procID	Pre-assigned process id, or 0 to be assigned one at connect time.
isLocal	true to run in purely local (single-process) mode without joining a networked system.

Definition at line 88 of file PsySpace.cpp.

References cmlabs::GetTimeNow(), cmlabs::Internal_BitmapPoster(), cmlabs::Internal_MessageScript(), cmlabs::Internal_MessageToggler(), cmlabs::Internal_MessageTypeConverter(), cmlabs::Internal_Ping(), cmlabs::Internal_Pong(), cmlabs::Internal_Print(), cmlabs::Internal_QueryTest(), cmlabs::Internal_RetrieveTest(), cmlabs::Internal_Shutdown(), cmlabs::Internal_SignalPing(), cmlabs::Internal_SignalPong(), cmlabs::Internal_Simple(), cmlabs::Internal_StatsLog(), cmlabs::Internal_Time(), manager, MAXVALUINT32, cmlabs::utils::RandomValue(), cmlabs::utils::StringFormat(), and cmlabs::utils::TextTrimQuotes().

Referenced by PsySpaceContinuousRun, PsySpacePoolRun, and PsySpaceRun.

◆ ~PsySpace()

cmlabs::PsySpace::~PsySpace ( )

Destructor.

Releases the MemoryManager, PsyAPIs, libraries and queues.

Warning: Call shutdown() and wait for hasShutdown() before destroying a started space.

Definition at line 128 of file PsySpace.cpp.

References reset().

Member Function Documentation

◆ addPsyProbeCustomView()

bool cmlabs::PsySpace::addPsyProbeCustomView	(	uint32	compID,
		const char *	name,
		const char *	templateURL )

Add a custom PsyProbe view tab for a component (space-level variant of PsyAPI::addPsyProbeCustomView()).

Parameters

compID	Component id.
name	Name of the view tab.
templateURL	Path/URL of the HTML template; pass "" to remove the view.

Returns: true if the view was registered.

Definition at line 336 of file PsySpace.cpp.

References cmlabs::PsyAPI::CTRL_CREATECUSTOMPAGE, manager, and cmlabs::DataMessage::setString().

Referenced by Java_com_cmlabs_cmsdk_cmsdkJNI_PsySpace_1addPsyProbeCustomView().

◆ connect()

bool cmlabs::PsySpace::connect	(	uint16	systemID,
		bool	isMaster = false,
		const char *	cmdline = NULL )

Join a Psyclone system (attach to the node's shared memory).

Parameters

systemID	Numeric id of the Psyclone system to join; used to locate the shared-memory segment on this node.
isMaster	true if this process should act as the system master (creates the shared memory and system structures).
cmdline	Optional command line / basedir string forwarded to components (see PsyAPI::getCommandlineBasedir()).

Returns: true on success; false if the system could not be created/attached.

Note: Non-master processes may need to wait for the master; see isConnected().

Definition at line 134 of file PsySpace.cpp.

References cmlabs::ThreadManager::CreateThread(), cmlabs::PsyAPI::CTRL_PROCESS_GREETING, cmlabs::PsyAPI::CTRL_PROCESS_INITIALISE, LOG_SPACE, LogPrint, manager, PSYPROC_INIT, PSYPROC_READY, PsySpaceRun, and cmlabs::Runnable::threadID.

Referenced by Java_com_cmlabs_cmsdk_cmsdkJNI_PsySpace_1connect_1_1SWIG_10(), Java_com_cmlabs_cmsdk_cmsdkJNI_PsySpace_1connect_1_1SWIG_11(), and Java_com_cmlabs_cmsdk_cmsdkJNI_PsySpace_1connect_1_1SWIG_12().

◆ emitSignal()

bool cmlabs::PsySpace::emitSignal	(	const PsyType &	type,
		DataMessage *	msg )

Emit a system-wide signal of the given type.

Signals are latest-value broadcasts: waiters receive the most recent message rather than a queued history.

Parameters

type	Signal type to emit.
msg	Payload message; ownership transfers to the space.

Returns: true if the signal was emitted.

Definition at line 489 of file PsySpace.cpp.

References cmlabs::utils::Mutex::enter(), cmlabs::SignalStruct::event, cmlabs::SignalStruct::lastSignalMsg, cmlabs::utils::Mutex::leave(), LOG_SPACE, LogPrint, manager, cmlabs::SignalStruct::mutex, and cmlabs::utils::Event::signal().

◆ getComponentID()

uint32 cmlabs::PsySpace::getComponentID ( const char * name )

Look up the numeric component id for a component name.

Parameters

name	Fully qualified component name.

Returns: Component id, or 0 if unknown.

Definition at line 424 of file PsySpace.cpp.

References manager.

Referenced by Java_com_cmlabs_cmsdk_cmsdkJNI_PsySpace_1getComponentID().

◆ getCrankAPI()

PsyAPI * cmlabs::PsySpace::getCrankAPI ( const char * name )

Get (or create) the PsyAPI handle for a crank hosted in this space.

This is how an embedding application drives a component manually: obtain the API handle and call PsyAPI::waitForNewMessage() / PsyAPI::postOutputMessage() from its own thread instead of registering a callback.

Parameters

name	Fully qualified crank/component name.

Returns: The PsyAPI handle (owned by the space; do not delete), or NULL if the name is unknown.

Definition at line 384 of file PsySpace.cpp.

References cmlabs::utils::GetCommandLinePath(), manager, PsyAPI, and cmlabs::PsyAPI::setCommandlineBasedir().

◆ getID()

uint16 cmlabs::PsySpace::getID ( )

Returns: The process id of this space within the Psyclone system (assigned at connect()).

Definition at line 358 of file PsySpace.cpp.

Referenced by _wrap_PsySpace_getID(), _wrap_PsySpace_getID(), and Java_com_cmlabs_cmsdk_cmsdkJNI_PsySpace_1getID().

◆ hasShutdown()

bool cmlabs::PsySpace::hasShutdown ( )

Returns: true once shutdown() has fully completed and all threads exited.

Definition at line 331 of file PsySpace.cpp.

Referenced by _wrap_PsySpace_hasShutdown(), _wrap_PsySpace_hasShutdown(), and Java_com_cmlabs_cmsdk_cmsdkJNI_PsySpace_1hasShutdown().

◆ isConnected()

bool cmlabs::PsySpace::isConnected ( uint32 timeoutMS = 5000 )

Wait until the space is fully connected to the system.

Parameters

timeoutMS Maximum wait in milliseconds (default 5000).

Returns: true if connected within the timeout. Blocking call.

Definition at line 226 of file PsySpace.cpp.

References cmlabs::GetTimeAgeMS(), LOG_SPACE, LogPrint, manager, PSYCLONE_STATUS_READY, and reset().

Referenced by _wrap_PsySpace_isConnected__SWIG_1(), _wrap_PsySpace_isConnected__SWIG_1(), Java_com_cmlabs_cmsdk_cmsdkJNI_PsySpace_1isConnected_1_1SWIG_10(), and Java_com_cmlabs_cmsdk_cmsdkJNI_PsySpace_1isConnected_1_1SWIG_11().

◆ logEntry()

bool cmlabs::PsySpace::logEntry ( LogEntry * entry )

virtual

LogReceiver interface: accept a log entry produced within this space.

Parameters

entry Log entry; ownership handled by the logging framework.

Returns: true if the entry was written/forwarded.

Implements cmlabs::LogReceiver.

Definition at line 346 of file PsySpace.cpp.

References cmlabs::CTRL_LOGPRINT, manager, cmlabs::DataMessage::setData(), and cmlabs::LogEntry::size.

◆ postMessage()

bool cmlabs::PsySpace::postMessage ( DataMessage * msg )

Post a raw message into the system for distribution to subscribers.

Parameters

msg	Message to post; ownership transfers to the system (do not delete or reuse).

Returns: true if the message was accepted for delivery.

Note: Components should normally use PsyAPI::postOutputMessage() instead, which applies the component's spec.

Definition at line 465 of file PsySpace.cpp.

References cmlabs::DataMessage::data, cmlabs::DataMessage::getEOL(), cmlabs::DataMessage::getFrom(), LOG_SPACE, LogPrint, manager, and cmlabs::DataMessageHeader::memid.

◆ query()

uint8 cmlabs::PsySpace::query	(	DataMessage *	msg,
		DataMessage **	result,
		uint32	timeout )

Send a query message and wait for its reply.

This is the synchronous request/reply primitive underlying PsyAPI::queryCatalog() and the retrieve() family: the message is delivered to the component addressed in its header, and the calling thread blocks until that component answers via queryReply() or the timeout expires.

DataMessage* q = new DataMessage(PsyAPI::CTRL_QUERY, myCompID, targetCompID, 3000);
q->setString("Query", "status");
DataMessage* reply = NULL;
uint8 status = space.query(q, &reply, 3000);
delete q;                                      // caller keeps ownership of q
if (status == QUERY_SUCCESS && reply) {
    // use reply ...
    delete reply;                              // caller owns the reply
}

Parameters

msg	Query message (addressing determined by its header). The message is copied into the request queue; the caller keeps ownership and should delete it after the call returns.
result	Receives the reply message on success (caller takes ownership); may be NULL-filled on failure.
timeout	Maximum wait in milliseconds.

Returns: One of the QUERY_* status codes defined in PsyAPI.h (e.g. QUERY_SUCCESS, QUERY_TIMEOUT). Blocking call.

Definition at line 584 of file PsySpace.cpp.

References cmlabs::DataMessage::getFrom(), cmlabs::DataMessage::getTo(), LOG_SPACE, LogPrint, manager, QUERY_FAILED, QUERY_NOT_REACHABLE, QUERY_SUCCESS, QUERY_TIMEOUT, REQ_FAILED, REQ_FAILED_TO_SEND, REQ_PROCESSING_LOCAL, REQ_PROCESSING_REMOTE, REQ_SUCCESS, and cmlabs::DataMessage::setReference().

◆ queryReply()

bool cmlabs::PsySpace::queryReply	(	uint32	id,
		uint8	status,
		DataMessage *	result )

Reply to a previously received query.

Parameters

id	Id of the query being answered.
status	One of the QUERY_* status codes.
result	Reply payload; ownership transfers. May be NULL.

Returns: true if the reply was dispatched.

Definition at line 665 of file PsySpace.cpp.

References cmlabs::PsyAPI::CTRL_INTERSYSTEM_QUERY_REPLY, cmlabs::PsyAPI::CTRL_QUERY_REPLY, cmlabs::DataMessage::getEOL(), LOG_SPACE, LogPrint, manager, QUERY_SUCCESS, REQ_FAILED, REQ_FAILED_DATA_EOL, REQ_SUCCESS, REQ_SUCCESS_DATA_EOL, cmlabs::DataMessage::setAttachedMessage(), cmlabs::DataMessage::setReference(), cmlabs::DataMessage::setStatus(), and cmlabs::DataMessage::setTTL().

◆ registerCrankCallback()

bool cmlabs::PsySpace::registerCrankCallback	(	const char *	name,
		CrankFunction	func )

Register a C/C++ entry function for a crank, to be invoked by the thread pool when the component triggers.

Parameters

name	Fully qualified crank/component name from the PsySpec.
func	Crank entry function (see CrankFunction).

Returns: true if the callback was registered.

Definition at line 413 of file PsySpace.cpp.

References manager.

Referenced by Java_com_cmlabs_cmsdk_cmsdkJNI_PsySpace_1registerCrankCallback().

◆ reset()

bool cmlabs::PsySpace::reset ( )

Reset the space's runtime state (counters, queues) without disconnecting.

Returns: true on success.

Definition at line 249 of file PsySpace.cpp.

References manager, cmlabs::LogSystem::SetLogReceiver(), and shutdown().

Referenced by _wrap_PsySpace_reset(), _wrap_PsySpace_reset(), isConnected(), Java_com_cmlabs_cmsdk_cmsdkJNI_PsySpace_1reset(), and ~PsySpace().

◆ shutdown()

bool cmlabs::PsySpace::shutdown ( )

Request an orderly shutdown of the space and all its components.

Returns: true if the shutdown was initiated.

Note: Asynchronous; poll hasShutdown() to know when it has finished. Cranks observe the shutdown through PsyAPI::shouldContinue() turning false, so they must poll it regularly for shutdown to complete.
space.shutdown();

while (!space.hasShutdown())

utils::Sleep(50); // wait for pool threads and cranks to exit

// now safe to destroy the space

cmlabs::utils::Sleep
bool Sleep(uint32 ms)
Suspend the calling thread.
Definition Utils.cpp:2830

Definition at line 282 of file PsySpace.cpp.

References cmlabs::PsyAPI::CTRL_PROCESS_SHUTDOWN, cmlabs::Runnable::isRunning, LOG_SPACE, LogPrint, manager, PSYPROC_TERMINATED, cmlabs::utils::Sleep(), cmlabs::Runnable::stop(), and cmlabs::ThreadManager::TerminateThread().

Referenced by _wrap_PsySpace_shutdown(), _wrap_PsySpace_shutdown(), Java_com_cmlabs_cmsdk_cmsdkJNI_PsySpace_1shutdown(), and reset().

◆ start()

bool cmlabs::PsySpace::start ( uint16 threadCount = 5 )

Start processing: spin up the thread pool and begin dispatching triggers.

Parameters

threadCount Initial number of pool worker threads (default 5); the pool auto-grows/shrinks between internal thresholds.

Returns: true if the threads were started.

Definition at line 276 of file PsySpace.cpp.

References LOG_SPACE, and LogPrint.

Referenced by _wrap_PsySpace_start__SWIG_1(), _wrap_PsySpace_start__SWIG_1(), Java_com_cmlabs_cmsdk_cmsdkJNI_PsySpace_1start_1_1SWIG_10(), and Java_com_cmlabs_cmsdk_cmsdkJNI_PsySpace_1start_1_1SWIG_11().

◆ waitForSignal()

DataMessage * cmlabs::PsySpace::waitForSignal	(	const PsyType &	type,
		uint32	timeout,
		uint64	lastReceivedTime = 0 )

Block until a signal of the given type arrives (or has already arrived).

Parameters

type	Signal type to wait for.
timeout	Maximum wait in milliseconds.
lastReceivedTime	Skip signals emitted at or before this PsyTime timestamp; 0 accepts the latest unread signal.

Returns: A copy of the signal message (caller takes ownership), or NULL on timeout. Blocking call.

Definition at line 521 of file PsySpace.cpp.

References cmlabs::DataMessage::data, cmlabs::utils::Mutex::enter(), cmlabs::SignalStruct::event, cmlabs::DataMessage::getCreatedTime(), cmlabs::SignalStruct::lastSignalMsg, cmlabs::utils::Mutex::leave(), manager, cmlabs::SignalStruct::mutex, and cmlabs::utils::Event::waitNext().

◆ PsyAPI

friend class PsyAPI

friend

Definition at line 165 of file PsySpace.h.

References PsyAPI, THREAD_ARG, THREAD_FUNCTION_CALL, and THREAD_RET.

Referenced by getCrankAPI(), and PsyAPI.

◆ PsySpaceContinuousRun

THREAD_RET THREAD_FUNCTION_CALL PsySpaceContinuousRun ( THREAD_ARG arg )

friend

Thread entry for continuously running components.

See also: PsySpaceContinuousRun()

Definition at line 1173 of file PsySpace.cpp.

References PsySpace(), THREAD_ARG, THREAD_FUNCTION_CALL, THREAD_RET, and thread_ret_val.

◆ PsySpacePoolRun

THREAD_RET THREAD_FUNCTION_CALL PsySpacePoolRun ( THREAD_ARG arg )

friend

Thread entry for pool worker threads.

See also: PsySpacePoolRun()

Definition at line 1168 of file PsySpace.cpp.

References PsySpace(), THREAD_ARG, THREAD_FUNCTION_CALL, THREAD_RET, and thread_ret_val.

◆ PsySpaceRun

THREAD_RET THREAD_FUNCTION_CALL PsySpaceRun ( THREAD_ARG arg )

friend

Thread entry for the space's main service thread.

See also: PsySpaceRun()

Definition at line 1162 of file PsySpace.cpp.

References PsySpace(), THREAD_ARG, THREAD_FUNCTION_CALL, THREAD_RET, and thread_ret_val.

Referenced by connect().

Member Data Documentation

◆ manager

MemoryManager* cmlabs::PsySpace::manager

The process-local memory manager: entry point to the node's shared-memory fabric. Owned by the space.

Definition at line 330 of file PsySpace.h.

Referenced by addPsyProbeCustomView(), connect(), emitSignal(), getComponentID(), getCrankAPI(), isConnected(), logEntry(), postMessage(), PsySpace(), query(), queryReply(), registerCrankCallback(), reset(), shutdown(), and waitForSignal().

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

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

Public Member Functions

Public Attributes

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ PsySpace()

◆ ~PsySpace()

Member Function Documentation

◆ addPsyProbeCustomView()

◆ connect()

◆ emitSignal()

◆ getComponentID()

◆ getCrankAPI()

◆ getID()

◆ hasShutdown()

◆ isConnected()

◆ logEntry()

◆ postMessage()

◆ query()

◆ queryReply()

◆ registerCrankCallback()

◆ reset()

◆ shutdown()

◆ start()

◆ waitForSignal()

Friends And Related Symbol Documentation

◆ PsyAPI

◆ PsySpaceContinuousRun

◆ PsySpacePoolRun

◆ PsySpaceRun

Member Data Documentation

◆ manager