cmlabs::PsyAPI Class Reference

The API handle a component (crank) uses to talk to the Psyclone system. More...

#include <PsyAPI.h>

Collaboration diagram for cmlabs::PsyAPI:

Public Member Functions
	PsyAPI (PsySpace *space)
	Constructor from a PsySpace.
	~PsyAPI ()
	Destructor for the PsyAPI.
bool	setAutoDelete (bool autodel)
	Internal use only.
bool	isRunning ()
	Internal use only.
bool	shouldContinue ()
	Check whether the crank should keep running, or exit its loop.
bool	getModuleName (char *name, uint32 maxSize)
	Get the name of the module written into the memory of name and return size.
std::string	getCommandlineBasedir ()
	Get the base dir that Psyclone is running from.
bool	setCommandlineBasedir (const char *cmdlineBasedir)
	Internal use only.
std::string	getModuleName ()
	Get the module name.
std::string	getOtherModuleName (uint32 id)
	Get the name of another module by id.
uint32	getInputQueueSize ()
	Get the size of the input queue, i.e.
std::string	typeToText (PsyType type)
	Get textual representation of the type.
std::string	contextToText (PsyContext context)
	Get textual representation of the context.
bool	getCurrentScriptLanguage (char *language, uint32 maxSize)
	Internal use only.
bool	getCurrentScript (char *script, uint32 maxSize)
	Internal use only.
bool	getCurrentScriptFilename (char *filename, uint32 maxSize)
	Internal use only.
std::string	getCurrentScriptLanguage ()
	Internal use only.
std::string	getCurrentScript ()
	Internal use only.
std::string	getCurrentScriptFilename ()
	Internal use only.
std::set< std::string >	getCurrentPostNames ()
	Get a list of post names currently active - i.e.
bool	hasCurrentSignalName (const char *name)
	Check to see if the signal name is currently active - i.e.
bool	hasCurrentQueryName (const char *name)
	Check to see if the query name is currently active - i.e.
bool	hasCurrentRetrieveName (const char *name)
	Check to see if the retrieve name is currently active - i.e.
bool	hasCurrentPostName (const char *name)
	Check to see if the post name is currently active - i.e.
DataMessage *	waitForNewMessage (uint32 ms)
	Wait for the next trigger message from the component's input queue.
std::map< std::string, DataMessage * >	waitForNewMessageGroup (uint32 ms, std::string &groupName)
	T1.6: Wait for the next <triggergroup> joined-set delivery from the input queue.
std::string	getCurrentTriggerName ()
	Get the name of the current trigger, i.e.
PsyContext	getCurrentTriggerContext ()
	Get the context of the current trigger, just retrieved using waitForNewMessage().
DataMessage *	waitForNewMessage (uint32 ms, const char *&triggerName)
	This function waits for the next trigger message to arrive and if it did within the timeout (ms) the message is returned and triggerName indicates the name of the trigger from the spec.
uint64	getCurrentMessageReceiveTime ()
	Get the time the current trigger (or, failing that, the current message) was received by the system, as a PsyTime timestamp (µs since year 0 — see PsyTime.h).
int32	postOutputMessage (const char *postName=NULL, DataMessage *msg=NULL)
	Post the crank's output according to the spec's post entries.
int32	postOutputMessage (PsyType msgType, DataMessage *msg=NULL)
	Post the crank's output, selecting the spec post entries by message type rather than by post name.
bool	emitSignal (const char *name, DataMessage *msg=NULL)
	Emit a signal by its spec name.
DataMessage *	waitForSignal (const char *name, uint32 timeout, uint64 lastReceivedTime=0)
	Wait for a signal (latest-value broadcast) by its spec name.
DataMessage *	retrieveAllSystemIDs ()
	This function retrieves all names for types, contexts and components.
bool	addSubscription (const char *xml)
	This function adds triggers and posts to an existing registration.
bool	addPsyProbeCustomView (const char *name, const char *templateURL)
	Add a custom module view tab for the PsyProbe web interface by providing a template file.
bool	removePsyProbeCustomView (const char *name)
	Remove a custom module view tab for the PsyProbe web interface.
bool	setPrivateData (const char *name, const char *data, uint64 size, const char *mimetype=NULL)
	Store a named chunk of data centrally, in the system's shared component memory.
uint64	getPrivateDataSize (const char *name)
	This returns the size of the private data chunk previously saved by the crank.
char *	getPrivateDataCopy (const char *name, uint64 &size)
	Returns a newly allocated copy of a private data entry, with the size written into size.
bool	getPrivateData (const char *name, char *data, uint64 maxSize)
	Reads a private chunk from the system into existing data space, maximum size is maxSize.
bool	deletePrivateData (const char *name)
	Deletes a private data chunk by name.
bool	createParameter (const char *name, const char *val, const char *defaultValue=NULL)
	Creates a new string parameter.
bool	createParameter (const char *name, const char *val, uint32 count, uint32 defaultIndex)
	Creates a new string list parameter with room for count entries.
bool	createParameter (const char *name, std::vector< std::string > values, const char *defaultValue=NULL)
	Creates a new string parameter with a list of values.
bool	createParameter (const char *name, int64 *val, uint32 count, uint32 defaultIndex)
	Creates a new integer list parameter with room for count entries.
bool	createParameter (const char *name, std::vector< std::string > values, int64 defaultValue)
	Creates a new String parameter with list of integer values (?).
bool	createParameter (const char *name, std::vector< int64 > values, int64 defaultValue=0)
	Creates a new integer parameter with list of values.
bool	createParameter (const char *name, float64 *val, uint32 count, uint32 defaultIndex)
	Creates a new float parameter.
bool	createParameter (const char *name, std::vector< std::string > values, float64 defaultValue)
	Creates a new string parameter with list of float values (?).
bool	createParameter (const char *name, std::vector< float64 > values, float64 defaultValue=0)
	Creates a new float parameter with list of float values (?).
bool	createParameter (const char *name, int64 val, int64 min=0, int64 max=0, int64 interval=0)
	Creates a new integer parameter.
bool	createParameter (const char *name, float64 val, float64 min=0, float64 max=0, float64 interval=0)
	Creates a new float parameter with min, max and interval limits for allowed values.
bool	hasParameter (const char *name)
	Checks if a named parameter exists.
bool	deleteParameter (const char *name)
	Deletes a named parameter.
uint8	getParameterDataType (const char *name)
	Gets the parameter type.
uint32	getParameterValueSize (const char *name)
	Return the amount of memory in bytes used by the parameter.
bool	getParameter (const char *name, char *val, uint32 maxSize)
	Read string parameter into existing data chunk val, maximum size maxSize.
std::string	getParameterString (const char *name)
	Read and return value of parameter by name.
bool	getParameterAsBool (const char *name)
	Read and interpret value of parameter by name as boolean True: String 'Yes', Integer and Float non-zero False: String not 'Yes', Integer and Float zero.
int64	getParameterInt (const char *name)
	Read and return value of parameter by name.
float64	getParameterFloat (const char *name)
	Read and return value of parameter by name.
bool	getParameter (const char *name, int64 &val)
	Read integer parameter value.
bool	getParameter (const char *name, float64 &val)
	Read float parameter value.
bool	setParameter (const char *name, const char *val)
	Set string parameter value.
bool	setParameter (const char *name, int64 val)
	Set integer parameter value.
bool	setParameter (const char *name, float64 val)
	Set float parameter value.
bool	resetParameter (const char *name)
	Reset parameter to its default (or initial) value.
bool	tweakParameter (const char *name, int32 tweak)
	Step up or down list or range parameter value.
uint8	retrieve (std::list< DataMessage * > &result, const char *name, uint32 maxcount=0, uint32 maxage=0, uint32 timeout=5000)
	Retrieve stored messages from a whiteboard, by named <retrieve> spec entry.
uint8	retrieveTimeParam (std::list< DataMessage * > &result, const char *name, uint64 startTime, uint64 endTime=0, uint32 maxcount=0, uint32 maxage=0, uint32 timeout=5000)
	Used by a module to retrieve messages from a whiteboard.
uint8	retrieveStringParam (std::list< DataMessage * > &result, const char *name, const char *startString, const char *endString=NULL, uint32 maxcount=0, uint32 maxage=0, uint32 timeout=5000)
	Used by a module to retrieve messages from a whiteboard.
uint8	retrieveIntegerParam (std::list< DataMessage * > &result, const char *name, int64 startInteger, int64 endInteger=INT64_NOVALUE, uint32 maxcount=0, uint32 maxage=0, uint32 timeout=5000)
	Used by a module to retrieve messages from a whiteboard.
uint8	retrieveFloatParam (std::list< DataMessage * > &result, const char *name, float64 startFloat, float64 endFloat=FLOAT64_NOVALUE, uint32 maxcount=0, uint32 maxage=0, uint32 timeout=5000)
	Used by a module to retrieve messages from a whiteboard.
uint8	retrieve (std::list< DataMessage * > &result, RetrieveSpec *spec, uint32 timeout=5000)
	Used by a module to retrieve messages from a whiteboard.
uint8	queryCatalog (char **result, uint32 &resultsize, const char *name, const char *query, const char *operation=NULL, const char *data=NULL, uint32 datasize=0, uint32 timeout=5000)
	Send a query to another module or catalog by named <query> spec entry, receiving raw bytes back.
uint8	queryCatalog (DataMessage **resultMsg, const char *name, DataMessage *msg, uint32 timeout=5000)
	Send a message-based query to another module or catalog by named spec entry.
uint8	queryRemoteCatalog (DataMessage **resultMsg, const char *componentName, const char *ipAddress, uint16 port, DataMessage *msg, uint32 timeout=5000)
	Send a query to a component in a different Psyclone system by hostname/IP.
uint8	queryRemoteCatalog (DataMessage **resultMsg, const char *componentName, uint32 ipAddress, uint16 port, DataMessage *msg, uint32 timeout=5000)
	Send a query to a component in a different Psyclone system by numeric IP.
uint8	queryRemoteCatalog (DataMessage **resultMsg, uint32 &chosenAddress, const char *componentName, uint32 *ipAddresses, uint32 numAddresses, uint16 port, DataMessage *msg, uint32 timeout=5000)
	Send a query to a multi-homed remote Psyclone system, trying a list of addresses.
bool	queryReply (uint32 id, uint8 status, char *data, uint32 size, uint32 count)
	Used by a module to reply to an incoming query by id.
bool	queryReply (uint32 id, uint8 status, DataMessage *msg=NULL)
	Used by a module to send a message as a reply to an incoming query.
bool	logPrint (int level, const char *formatstring,...)
	Write a printf-style entry to the component's log (and the console when level is below the logging threshold).

Static Public Member Functions
static PsyAPI *	fromPython (unsigned long long ptr)
	Internal use only.
static const char *	fromPythonAddressOf (unsigned long long ptr)
	Internal use only — debug helper returning a printable address string for a Python-held pointer.

Static Public Attributes
System control message types
Well-known PsyType values used internally for system lifecycle and control traffic. Cranks rarely use these directly, but may see them referenced in specs/logs.
static struct PsyType	CTRL_SYSTEM_READY = { { 1,10200,0,0,0,0,0,0,0,0,0,0,0,0,0,0 } }
	Broadcast when the system has fully started.
static struct PsyType	CTRL_PROCESS_INITIALISE = { { 1,10201,0,0,0,0,0,0,0,0,0,0,0,0,0,0 } }
	Sent to a process to initialise it.
static struct PsyType	CTRL_PROCESS_GREETING = { { 1,10202,0,0,0,0,0,0,0,0,0,0,0,0,0,0 } }
	Handshake from a newly joined process.
static struct PsyType	CTRL_PROCESS_SHUTDOWN = { { 1,10203,0,0,0,0,0,0,0,0,0,0,0,0,0,0 } }
	Orders a single process to shut down.
static struct PsyType	CTRL_CONTEXT_CHANGE = { { 1,10297,0,0,0,0,0,0,0,0,0,0,0,0,0,0 } }
	Announces a system context change.
static struct PsyType	CTRL_SYSTEM_SHUTDOWN = { { 1,10298,0,0,0,0,0,0,0,0,0,0,0,0,0,0 } }
	Orders a full system shutdown.
static struct PsyType	CTRL_SYSTEM_SHUTTINGDOWN = { { 1,10299,0,0,0,0,0,0,0,0,0,0,0,0,0,0 } }
	Broadcast while shutdown is in progress.
static struct PsyType	CTRL_TRIGGER = { { 1,10300,0,0,0,0,0,0,0,0,0,0,0,0,0,0 } }
	Wraps a trigger delivery to a component.
static struct PsyType	CTRL_TRIGGER_GROUP = { { 1,10307,0,0,0,0,0,0,0,0,0,0,0,0,0,0 } }
	T1.6: wraps a <triggergroup> joined-set delivery (member map) to a component.
static struct PsyType	CTRL_QUERY = { { 1,10301,0,0,0,0,0,0,0,0,0,0,0,0,0,0 } }
	Carries a query to a component/catalog.
static struct PsyType	CTRL_QUERY_REPLY = { { 1,10302,0,0,0,0,0,0,0,0,0,0,0,0,0,0 } }
	Carries a query reply back to the asker.
static struct PsyType	CTRL_PULLCOMPONENTDATA = { { 1,10303,0,0,0,0,0,0,0,0,0,0,0,0,0,0 } }
	Requests component data from another node.
static struct PsyType	CTRL_CREATECUSTOMPAGE = { { 1,10304,0,0,0,0,0,0,0,0,0,0,0,0,0,0 } }
	Registers a custom PsyProbe view.
static struct PsyType	CTRL_ADDSUBSCRIPTION = { { 1,10305,0,0,0,0,0,0,0,0,0,0,0,0,0,0 } }
	Adds triggers/posts to a registration at runtime.
static struct PsyType	CTRL_RETRIEVESYSTEMIDS = { { 1,10306,0,0,0,0,0,0,0,0,0,0,0,0,0,0 } }
	Requests the full id/name tables.
static struct PsyType	CTRL_INTERSYSTEM_QUERY = { { 1,10998,0,0,0,0,0,0,0,0,0,0,0,0,0,0 } }
	Query crossing to a different Psyclone system.
static struct PsyType	CTRL_INTERSYSTEM_QUERY_REPLY = { { 1,10999,0,0,0,0,0,0,0,0,0,0,0,0,0,0 } }
	Reply from a different Psyclone system.

Friends
class	PsySpace

Detailed Description

The API handle a component (crank) uses to talk to the Psyclone system.

See the file documentation for the PsySpace/PsyAPI relationship and a usage example. Instances are created and owned by the hosting PsySpace; cranks receive theirs as the argument to their CrankFunction, embedders obtain one via PsySpace::getCrankAPI(). Messages returned by waitForNewMessage() and waitForSignal() are owned by the system and must not be deleted by the crank. An instance should only be used from one crank thread at a time.

Definition at line 82 of file PsyAPI.h.

Constructor & Destructor Documentation

PsyAPI()

cmlabs::PsyAPI::PsyAPI

(

PsySpace *

space

)

Constructor from a PsySpace.

Normally called only by the hosting PsySpace itself (PsySpace::getCrankAPI() creates one per component); application code rarely constructs a PsyAPI directly. The handle keeps a plain pointer to space and uses it for every call, so the space must outlive the API object.

Parameters

space

The space in which the PsyAPI shall be created (not owned; must outlive this object).

Definition at line 30 of file PsyAPI.cpp.

References PsySpace.

Referenced by fromPython().

~PsyAPI()

cmlabs::PsyAPI::~PsyAPI

(

)

Destructor for the PsyAPI.

Deletes any internally held trigger/input/signal messages (the ones handed out by waitForNewMessage()/waitForSignal()), so pointers previously returned by those calls become invalid. Owned and destroyed by the hosting PsySpace — do not delete a handle obtained via PsySpace::getCrankAPI().

Definition at line 54 of file PsyAPI.cpp.

Member Function Documentation

addPsyProbeCustomView()

bool cmlabs::PsyAPI::addPsyProbeCustomView	(	const char *	name,
		const char *	templateURL )

Add a custom module view tab for the PsyProbe web interface by providing a template file.

• this file will need to use PsyProbe javascript to work - see the PsyProbe documentation for more info.

Parameters

name	name of the custom module view tab
templateURL	The path to the template file

Returns

true if successful

Definition at line 317 of file PsyAPI.cpp.

Referenced by Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1addPsyProbeCustomView(), and removePsyProbeCustomView().

addSubscription()

bool cmlabs::PsyAPI::addSubscription

(

const char *

xml

)

This function adds triggers and posts to an existing registration.

Parameters

xml	<registration name="modulename"><trigger.../>...<post.../></registration>

Returns

true if successful

Definition at line 970 of file PsyAPI.cpp.

References CTRL_ADDSUBSCRIPTION, QUERY_SUCCESS, and cmlabs::DataMessage::setString().

Referenced by Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1addSubscription().

contextToText()

std::string cmlabs::PsyAPI::contextToText

(

PsyContext

context

)

Get textual representation of the context.

Parameters

context

context as PsyContext object

Returns

context as string

Definition at line 258 of file PsyAPI.cpp.

Referenced by cmlabs::Internal_Print().

createParameter() [1/11]

bool cmlabs::PsyAPI::createParameter ( const char * name, const char * val, const char * defaultValue = NULL )

inline

Creates a new string parameter.

Parameters are the component's tunable settings: they live in shared component memory (like private data), persist across activations, and are visible and editable live in the PsyProbe web interface — which is the main reason to prefer a parameter over an ordinary variable. If a parameter with the same name already exists the call fails (returns false) and the existing value is left untouched, so calling createParameter() unconditionally at the top of a crank will not clobber a value tuned via PsyProbe.

if (!api->hasParameter("Threshold"))
    api->createParameter("Threshold", (float64)0.5, 0.0, 1.0, 0.05);
float64 threshold = api->getParameterFloat("Threshold");

Parameters

name	name of the parameter
val	value of the parameter
defaultValue	default value when resetting parameter, NULL if val should be used

Returns

true if creation was successful

Definition at line 642 of file PsyAPI.h.

Referenced by Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1createParameter_1_1SWIG_10(), Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1createParameter_1_1SWIG_11(), Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1createParameter_1_1SWIG_113(), Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1createParameter_1_1SWIG_114(), Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1createParameter_1_1SWIG_115(), Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1createParameter_1_1SWIG_116(), Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1createParameter_1_1SWIG_117(), Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1createParameter_1_1SWIG_118(), Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1createParameter_1_1SWIG_119(), Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1createParameter_1_1SWIG_12(), Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1createParameter_1_1SWIG_120(), Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1createParameter_1_1SWIG_15(), and Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1createParameter_1_1SWIG_19().

createParameter() [2/11]

bool cmlabs::PsyAPI::createParameter ( const char * name, const char * val, uint32 count, uint32 defaultIndex )

inline

Creates a new string list parameter with room for count entries.

Parameters

name	name of the parameter
val	value array of the parameter, separed by binary \0
count	number of entries in the array
defaultIndex	an int value that sets the default index in the list

Returns

true if creation was successful

Definition at line 656 of file PsyAPI.h.

createParameter() [3/11]

bool cmlabs::PsyAPI::createParameter ( const char * name, float64 * val, uint32 count, uint32 defaultIndex )

inline

Creates a new float parameter.

Parameters

name	name of the parameter
val	array of value of the parameter
count	number of values in the array
defaultIndex	an int value that sets the default index in the list

Returns

true if creation was successful

Definition at line 723 of file PsyAPI.h.

createParameter() [4/11]

bool cmlabs::PsyAPI::createParameter ( const char * name, float64 val, float64 min = 0, float64 max = 0, float64 interval = 0 )

inline

Creates a new float parameter with min, max and interval limits for allowed values.

Parameters

name	name of the parameter
val	value of the parameter
min	minimum value
max	maximum value
interval	interval limit, amount to jump on every tweak

Returns

true if creation was successful

Definition at line 779 of file PsyAPI.h.

createParameter() [5/11]

bool cmlabs::PsyAPI::createParameter ( const char * name, int64 * val, uint32 count, uint32 defaultIndex )

inline

Creates a new integer list parameter with room for count entries.

Parameters

name	name of the parameter
val	array of values of the parameter
count	number of entries in the array
defaultIndex	an int value that sets the default index in the list

Returns

true if creation was successful

Definition at line 683 of file PsyAPI.h.

createParameter() [6/11]

bool cmlabs::PsyAPI::createParameter ( const char * name, int64 val, int64 min = 0, int64 max = 0, int64 interval = 0 )

inline

Creates a new integer parameter.

Parameters

name	name of the parameter
val	value of the parameter
min	the minimum value
max	the maximum value
interval	interval limit, amount to jump on every tweak

Returns

true if creation was successful

Definition at line 764 of file PsyAPI.h.

createParameter() [7/11]

bool cmlabs::PsyAPI::createParameter ( const char * name, std::vector< float64 > values, float64 defaultValue = 0 )

inline

Creates a new float parameter with list of float values (?).

Parameters

name	name of the parameter
values	vector of values of the parameter
defaultValue	default is 0

Returns

true if creation was successful

Definition at line 749 of file PsyAPI.h.

createParameter() [8/11]

bool cmlabs::PsyAPI::createParameter ( const char * name, std::vector< int64 > values, int64 defaultValue = 0 )

inline

Creates a new integer parameter with list of values.

Parameters

name	name of the parameter
values	vector of values of the parameter
defaultValue	default is 0

Returns

true if creation was successful

Definition at line 709 of file PsyAPI.h.

createParameter() [9/11]

bool cmlabs::PsyAPI::createParameter ( const char * name, std::vector< std::string > values, const char * defaultValue = NULL )

inline

Creates a new string parameter with a list of values.

Parameters

name	name of the parameter
values	vector of values of the parameter
defaultValue	default value or NULL for the first entry

Returns

true if creation was successful

Definition at line 669 of file PsyAPI.h.

createParameter() [10/11]

bool cmlabs::PsyAPI::createParameter ( const char * name, std::vector< std::string > values, float64 defaultValue )

inline

Creates a new string parameter with list of float values (?).

Parameters

name	name of the parameter
values	vector of values of the parameter
defaultValue	float value as default

Returns

true if creation was successful

Definition at line 736 of file PsyAPI.h.

createParameter() [11/11]

bool cmlabs::PsyAPI::createParameter ( const char * name, std::vector< std::string > values, int64 defaultValue )

inline

Creates a new String parameter with list of integer values (?).

Parameters

name	name of the parameter
values	vector with values of the parameter
defaultValue	default as int

Returns

true if creation was successful

Definition at line 696 of file PsyAPI.h.

deleteParameter()

bool cmlabs::PsyAPI::deleteParameter ( const char * name )

inline

Deletes a named parameter.

Parameters

name	name of the parameter

Returns

true if deletion was successful

Definition at line 801 of file PsyAPI.h.

Referenced by Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1deleteParameter().

deletePrivateData()

bool cmlabs::PsyAPI::deletePrivateData ( const char * name )

inline

Deletes a private data chunk by name.

Parameters

name	the name of the chunk to be deleted

Returns

true if deletion was successful

Definition at line 614 of file PsyAPI.h.

Referenced by Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1deletePrivateData().

emitSignal()

bool cmlabs::PsyAPI::emitSignal	(	const char *	name,
		DataMessage *	msg = NULL )

Emit a signal by its spec name.

Signals are lightweight, latest-value broadcasts (in contrast to posted messages, which are queued per receiver): whoever waits on the signal type sees only the most recent emission. The name is resolved against the current trigger's <signal> entries in the PsySpec, so this — like postOutputMessage() — only works after a trigger has been received; check hasCurrentSignalName() to see whether a signal name is usable right now.

Parameters

name	name of the signal to be sent (as defined in the spec)
msg	message to be sent, empty message if NULL

Returns

true if successful; false if there is no active trigger context, the name is unknown in the spec, or emission failed.

Warning

Ownership: msg is consumed — the space takes it over on success and the call deletes it on spec/emission failure. Do not delete or reuse it after this call.

Definition at line 693 of file PsyAPI.cpp.

References cmlabs::DataMessage::setType(), and cmlabs::SignalSpec::type.

Referenced by cmlabs::Internal_MessageScript(), cmlabs::Internal_SignalPing(), cmlabs::Internal_SignalPong(), and Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1emitSignal_1_1SWIG_11().

fromPython()

PsyAPI * cmlabs::PsyAPI::fromPython ( unsigned long long ptr )

static

Internal use only.

Internal use only — recover a PsyAPI pointer passed to Python as an integer (SWIG bridge).

Parameters

ptr	Pointer value previously handed to Python.

Returns

The PsyAPI pointer, or NULL if invalid.

Definition at line 72 of file PsyAPI.cpp.

References PsyAPI().

Referenced by _wrap_PsyAPI_fromPython(), _wrap_PsyAPI_fromPython(), and Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1fromPython().

fromPythonAddressOf()

const char * cmlabs::PsyAPI::fromPythonAddressOf ( unsigned long long ptr )

static

Internal use only — debug helper returning a printable address string for a Python-held pointer.

Definition at line 76 of file PsyAPI.cpp.

Referenced by _wrap_PsyAPI_fromPythonAddressOf(), _wrap_PsyAPI_fromPythonAddressOf(), and Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1fromPythonAddressOf().

getCommandlineBasedir()

std::string cmlabs::PsyAPI::getCommandlineBasedir

(

)

Get the base dir that Psyclone is running from.

Returns

the base dir as a string

Definition at line 106 of file PsyAPI.cpp.

getCurrentMessageReceiveTime()

uint64 cmlabs::PsyAPI::getCurrentMessageReceiveTime

(

)

Get the time the current trigger (or, failing that, the current message) was received by the system, as a PsyTime timestamp (µs since year 0 — see PsyTime.h).

Handy for measuring end-to-end latency:

int64 latencyUs = GetTimeAge(api->getCurrentMessageReceiveTime());
api->logPrint(2, "Trigger latency: %lld us", latencyUs);

Returns

Receive time in µs, or 0 if no message has been received yet.

Definition at line 536 of file PsyAPI.cpp.

Referenced by _wrap_PsyAPI_getCurrentMessageReceiveTime(), _wrap_PsyAPI_getCurrentMessageReceiveTime(), and Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1getCurrentMessageReceiveTime().

getCurrentPostNames()

std::set< std::string > cmlabs::PsyAPI::getCurrentPostNames

(

)

Get a list of post names currently active - i.e.

the post names that can be used right now

Returns

the post names as a list of strings

Definition at line 226 of file PsyAPI.cpp.

Referenced by cmlabs::Internal_Print().

getCurrentScript() [1/2]

std::string cmlabs::PsyAPI::getCurrentScript

(

)

Internal use only.

Definition at line 147 of file PsyAPI.cpp.

References MAXSCRIPTLEN.

getCurrentScript() [2/2]

bool cmlabs::PsyAPI::getCurrentScript	(	char *	script,
		uint32	maxSize )

Internal use only.

Definition at line 143 of file PsyAPI.cpp.

Referenced by Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1getCurrentScript_1_1SWIG_10().

getCurrentScriptFilename() [1/2]

std::string cmlabs::PsyAPI::getCurrentScriptFilename

(

)

Internal use only.

Definition at line 162 of file PsyAPI.cpp.

getCurrentScriptFilename() [2/2]

bool cmlabs::PsyAPI::getCurrentScriptFilename	(	char *	filename,
		uint32	maxSize )

Internal use only.

Definition at line 158 of file PsyAPI.cpp.

Referenced by Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1getCurrentScriptFilename_1_1SWIG_10().

getCurrentScriptLanguage() [1/2]

std::string cmlabs::PsyAPI::getCurrentScriptLanguage

(

)

Internal use only.

Definition at line 132 of file PsyAPI.cpp.

getCurrentScriptLanguage() [2/2]

bool cmlabs::PsyAPI::getCurrentScriptLanguage	(	char *	language,
		uint32	maxSize )

Internal use only.

Definition at line 128 of file PsyAPI.cpp.

Referenced by Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1getCurrentScriptLanguage_1_1SWIG_10().

getCurrentTriggerContext()

PsyContext cmlabs::PsyAPI::getCurrentTriggerContext

(

)

Get the context of the current trigger, just retrieved using waitForNewMessage().

Returns

Context as PsyContext

Definition at line 380 of file PsyAPI.cpp.

References NOCONTEXT.

Referenced by cmlabs::Internal_Print().

getCurrentTriggerName()

std::string cmlabs::PsyAPI::getCurrentTriggerName

(

)

Get the name of the current trigger, i.e.

the spec trigger entry that matched the message most recently returned by waitForNewMessage(). Useful when a crank subscribes to several triggers and needs to branch on which one fired.

Returns

Trigger name as string (empty before the first trigger arrives).

Definition at line 376 of file PsyAPI.cpp.

getInputQueueSize()

uint32 cmlabs::PsyAPI::getInputQueueSize

(

)

Get the size of the input queue, i.e.

how many unprocessed trigger messages waiting to be processed

Returns

size of the input queue

Definition at line 245 of file PsyAPI.cpp.

Referenced by _wrap_PsyAPI_getInputQueueSize(), _wrap_PsyAPI_getInputQueueSize(), and Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1getInputQueueSize().

getModuleName() [1/2]

std::string cmlabs::PsyAPI::getModuleName

(

)

Get the module name.

Returns

module name as String

Definition at line 120 of file PsyAPI.cpp.

getModuleName() [2/2]

bool cmlabs::PsyAPI::getModuleName	(	char *	name,
		uint32	maxSize )

Get the name of the module written into the memory of name and return size.

Parameters

name	the chunk of memory that the name of the module will be written into
maxSize	the size of the memory chunk of tha name parameter

Returns

true if module with that name exists and the size of the name is smaller than maySize

Definition at line 116 of file PsyAPI.cpp.

Referenced by Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1getModuleName_1_1SWIG_10().

getOtherModuleName()

std::string cmlabs::PsyAPI::getOtherModuleName

(

uint32

id

)

Get the name of another module by id.

Parameters

id	the id of the other module

Returns

module name as String

Definition at line 124 of file PsyAPI.cpp.

Referenced by cmlabs::Internal_Print().

getParameter() [1/3]

bool cmlabs::PsyAPI::getParameter ( const char * name, char * val, uint32 maxSize )

inline

Read string parameter into existing data chunk val, maximum size maxSize.

Parameters

name	name of the parameter
val	value of the parameter
maxSize	maximal size of the parameter to be read

Returns

true if reading was successful

Definition at line 850 of file PsyAPI.h.

Referenced by cmlabs::Internal_Ping(), cmlabs::Internal_RetrieveTest(), cmlabs::Internal_SignalPing(), Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1getParameter_1_1SWIG_10(), Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1getParameter_1_1SWIG_11(), and Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1getParameter_1_1SWIG_12().

getParameter() [2/3]

bool cmlabs::PsyAPI::getParameter ( const char * name, float64 & val )

inline

Read float parameter value.

Parameters

name	name of the parameter
val	value of the parameter

Returns

true if reading was successful

Definition at line 920 of file PsyAPI.h.

getParameter() [3/3]

bool cmlabs::PsyAPI::getParameter ( const char * name, int64 & val )

inline

Read integer parameter value.

Parameters

name	name of the parameter
val	value of the parameter

Returns

true if reading was successful

Definition at line 908 of file PsyAPI.h.

getParameterAsBool()

bool cmlabs::PsyAPI::getParameterAsBool ( const char * name )

inline

Read and interpret value of parameter by name as boolean True: String 'Yes', Integer and Float non-zero False: String not 'Yes', Integer and Float zero.

Parameters

name	name of the parameter

Returns

boolean interpretation of value of the paramer

Definition at line 874 of file PsyAPI.h.

Referenced by cmlabs::Internal_BitmapPoster(), cmlabs::Internal_MessageScript(), cmlabs::Internal_StatsLog(), and Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1getParameterAsBool().

getParameterDataType()

uint8 cmlabs::PsyAPI::getParameterDataType ( const char * name )

inline

Gets the parameter type.

#define PARAM_STRING 1

#define PARAM_INTEGER 2

#define PARAM_FLOAT 3

#define PARAM_STRING_COLL 4

#define PARAM_INTEGER_COLL 5

#define PARAM_FLOAT_COLL 6

#define PARAM_TYPE_COLL 7

Parameters

name	name of the parameter

Returns

1 for String, 2 for int, 3 for float, 4 for String Collection, 5 for int collection, 6 for florat collection, 7 for type collection

Definition at line 826 of file PsyAPI.h.

Referenced by Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1getParameterDataType().

getParameterFloat()

float64 cmlabs::PsyAPI::getParameterFloat ( const char * name )

inline

Read and return value of parameter by name.

Parameters

name	name of the parameter

Returns

value of the paramer

Definition at line 896 of file PsyAPI.h.

Referenced by Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1getParameterFloat().

getParameterInt()

int64 cmlabs::PsyAPI::getParameterInt ( const char * name )

inline

Read and return value of parameter by name.

Parameters

name	name of the parameter

Returns

value of the paramer

Definition at line 885 of file PsyAPI.h.

Referenced by cmlabs::Internal_BitmapPoster(), and Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1getParameterInt().

getParameterString()

std::string cmlabs::PsyAPI::getParameterString ( const char * name )

inline

Read and return value of parameter by name.

Parameters

name	name of the parameter

Returns

value of the paramer

Definition at line 861 of file PsyAPI.h.

Referenced by cmlabs::Internal_BitmapPoster(), cmlabs::Internal_MessageScript(), cmlabs::Internal_MessageToggler(), cmlabs::Internal_Simple(), and cmlabs::Internal_StatsLog().

getParameterValueSize()

uint32 cmlabs::PsyAPI::getParameterValueSize ( const char * name )

inline

Return the amount of memory in bytes used by the parameter.

Parameters

name	name of the parameter

Returns

amount of memory in bytes

Definition at line 837 of file PsyAPI.h.

Referenced by Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1getParameterValueSize().

getPrivateData()

bool cmlabs::PsyAPI::getPrivateData ( const char * name, char * data, uint64 maxSize )

inline

Reads a private chunk from the system into existing data space, maximum size is maxSize.

Parameters

name	name of the data chunk
data	pointer to an already allocated memory chunk
maxSize	maximum size of the already allocated memory chunk

Returns

true if reading was successful

Definition at line 603 of file PsyAPI.h.

Referenced by Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1getPrivateData().

getPrivateDataCopy()

char * cmlabs::PsyAPI::getPrivateDataCopy ( const char * name, uint64 & size )

inline

Returns a newly allocated copy of a private data entry, with the size written into size.

Parameters

name	name of the data chunk
size	receives the size of the returned data

Returns

new copy of the entry — the CALLER owns it and must delete [] it — or NULL if the entry does not exist. See setPrivateData() for a round-trip example.

Definition at line 590 of file PsyAPI.h.

Referenced by Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1getPrivateDataCopy().

getPrivateDataSize()

uint64 cmlabs::PsyAPI::getPrivateDataSize ( const char * name )

inline

This returns the size of the private data chunk previously saved by the crank.

Parameters

name	name of the data chunk

Returns

size of the private data chunk

Definition at line 580 of file PsyAPI.h.

Referenced by Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1getPrivateDataSize().

hasCurrentPostName()

bool cmlabs::PsyAPI::hasCurrentPostName

(

const char *

name

)

Check to see if the post name is currently active - i.e.

can this post be used right now

Returns

true if the post name is active, otherwise false

Definition at line 213 of file PsyAPI.cpp.

Referenced by cmlabs::Internal_MessageToggler(), cmlabs::Internal_MessageTypeConverter(), and Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1hasCurrentPostName().

hasCurrentQueryName()

bool cmlabs::PsyAPI::hasCurrentQueryName

(

const char *

name

)

Check to see if the query name is currently active - i.e.

can this query be used right now

Returns

true if the query name is active, otherwise false

Definition at line 200 of file PsyAPI.cpp.

Referenced by Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1hasCurrentQueryName().

hasCurrentRetrieveName()

bool cmlabs::PsyAPI::hasCurrentRetrieveName

(

const char *

name

)

Check to see if the retrieve name is currently active - i.e.

can this retrieve be used right now

Returns

true if the retrieve name is active, otherwise false

Definition at line 173 of file PsyAPI.cpp.

Referenced by Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1hasCurrentRetrieveName().

hasCurrentSignalName()

bool cmlabs::PsyAPI::hasCurrentSignalName

(

const char *

name

)

Check to see if the signal name is currently active - i.e.

can this signal be used right now

Returns

true if the signal name is active, otherwise false

Definition at line 186 of file PsyAPI.cpp.

Referenced by Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1hasCurrentSignalName().

hasParameter()

bool cmlabs::PsyAPI::hasParameter ( const char * name )

inline

Checks if a named parameter exists.

Parameters

name	name of the parameter

Returns

true if it exists, false otherwise

Definition at line 790 of file PsyAPI.h.

Referenced by cmlabs::Internal_MessageScript(), cmlabs::Internal_Ping(), cmlabs::Internal_RetrieveTest(), cmlabs::Internal_SignalPing(), cmlabs::Internal_Simple(), and Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1hasParameter().

isRunning()

bool cmlabs::PsyAPI::isRunning

(

)

Internal use only.

Definition at line 80 of file PsyAPI.cpp.

Referenced by _wrap_PsyAPI_isRunning(), _wrap_PsyAPI_isRunning(), and Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1isRunning().

logPrint()

bool cmlabs::PsyAPI::logPrint	(	int	level,
		const char *	formatstring,
			... )

Write a printf-style entry to the component's log (and the console when level is below the logging threshold).

The entry is automatically prefixed with the component's name and routed through the space's logging framework, so it shows up attributed to this component in PsyProbe and the system log.

Parameters

level	Log severity/verbosity level; lower is more important (0 = error, higher = increasingly verbose).
formatstring	printf-style format followed by matching variadic arguments.

Returns

true if the entry was logged.

Definition at line 1210 of file PsyAPI.cpp.

References cmlabs::LogEntry::cid, cmlabs::GetTimeNow(), cmlabs::LogEntry::level, LOG_COMPONENT, LOGENTRYID, LOGPRINT, cmlabs::LogEntry::setText(), cmlabs::LogEntry::size, cmlabs::LogEntry::source, cmlabs::utils::StringFormat(), cmlabs::utils::StringFormatVA(), cmlabs::LogEntry::subject, cmlabs::LogEntry::time, and cmlabs::LogEntry::type.

Referenced by cmlabs::Internal_BitmapPoster(), cmlabs::Internal_MessageScript(), cmlabs::Internal_MessageToggler(), 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(), Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1logPrint(), postOutputMessage(), queryCatalog(), and retrieve().

postOutputMessage() [1/2]

int32 cmlabs::PsyAPI::postOutputMessage	(	const char *	postName = NULL,
		DataMessage *	msg = NULL )

Post the crank's output according to the spec's post entries.

This is the normal way a component produces output. What actually gets sent is determined by the <post> entries attached to the current trigger in the PsySpec: for every matching active post entry the message is stamped with that entry's type, destination, tag, TTL and policy (and any content the entry adds) and delivered — so one call can fan out to several receivers. Because of this, postOutputMessage() can only be used after a trigger has arrived via waitForNewMessage(); before that there is no active spec (POST_NOSPEC), and after a context change the entries may no longer apply (POST_OUTOFCONTEXT).

DataMessage* out = new DataMessage();
out->setString("result", answer.c_str());
int32 n = api->postOutputMessage("MyOutput", out);   // out now belongs to the API
if (n <= 0)
    api->logPrint(0, "post failed: %d", n);          // POST_FAILED/NOSPEC/OUTOFCONTEXT

Negative return values:

POST_FAILED -1 Error occurred while trying to post the message

POST_NOSPEC -2 The crank tried to post a message before a trigger arrived

POST_OUTOFCONTEXT -3 The crank is no longer active because the context has changed and is no longer active

Parameters

postName	name of the Post. If none is provided then all active post entries will be used and one copy of the message posted per post entry.
msg	message. If none is provided an empty message will be used instead.

Returns

number of messages sent (0 if no entries matched), or a negative POST_* code.

Warning

Ownership: msg is consumed by this call — the system copies it per post entry and deletes the original before returning. Never delete or reuse msg after posting; allocate a fresh message for each call.

Note

If msg has no tag of its own, the tag of the current input message is propagated onto it, keeping message chains correlated across components.

Definition at line 560 of file PsyAPI.cpp.

References cmlabs::PostSpec::addContentToMsg(), cmlabs::DataMessage::addTimeUsage(), COMPSTATUS_RUNNING, cmlabs::PostSpec::contextchange, CTRL_CONTEXT_CHANGE, cmlabs::utils::GetCPUTicks(), cmlabs::DataMessage::getTag(), cmlabs::GetTimeAge(), cmlabs::GetTimeNow(), cmlabs::DataMessage::getTo(), cmlabs::DataMessage::getTTL(), cmlabs::DataMessage::getType(), PsyContext::isValid(), PsyType::isValid(), logPrint(), cmlabs::PostSpec::policy, POST_FAILED, POST_NOSPEC, POST_OUTOFCONTEXT, cmlabs::DataMessage::setContextChange(), cmlabs::DataMessage::setMultiple(), cmlabs::DataMessage::setTag(), cmlabs::DataMessage::setType(), cmlabs::PostSpec::tag, cmlabs::PostSpec::to, cmlabs::PostSpec::ttl, and cmlabs::PostSpec::type.

Referenced by _wrap_PsyAPI_postOutputMessage__SWIG_2(), _wrap_PsyAPI_postOutputMessage__SWIG_2(), _wrap_PsyAPI_postOutputMessage__SWIG_4(), _wrap_PsyAPI_postOutputMessage__SWIG_4(), cmlabs::Internal_BitmapPoster(), cmlabs::Internal_MessageScript(), cmlabs::Internal_MessageToggler(), cmlabs::Internal_MessageTypeConverter(), cmlabs::Internal_Ping(), cmlabs::Internal_Pong(), cmlabs::Internal_Print(), cmlabs::Internal_RetrieveTest(), cmlabs::Internal_Shutdown(), cmlabs::Internal_SignalPing(), cmlabs::Internal_Simple(), cmlabs::Internal_Time(), Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1postOutputMessage_1_1SWIG_11(), Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1postOutputMessage_1_1SWIG_12(), and postOutputMessage().

postOutputMessage() [2/2]

int32 cmlabs::PsyAPI::postOutputMessage	(	PsyType	msgType,
		DataMessage *	msg = NULL )

Post the crank's output, selecting the spec post entries by message type rather than by post name.

Convenience overload of postOutputMessage(const char*, DataMessage*): sets msgType on msg (when given) and posts it; the active post entries whose type matches are used. See the by-name overload for the full semantics, the POST_* error codes and the ownership rules — in particular, msg is consumed by the call and must not be deleted or reused afterwards.

Parameters

msgType	msg type of the Post. If none is provided then all active post entries will be used and one copy of the message posted per post entry.
msg	message. If none is provided an empty message will be used instead.

Returns

number of messages sent, or a negative POST_* code.

Definition at line 546 of file PsyAPI.cpp.

References NOTYPE, postOutputMessage(), and cmlabs::DataMessage::setType().

queryCatalog() [1/2]

uint8 cmlabs::PsyAPI::queryCatalog	(	char **	result,
		uint32 &	resultsize,
		const char *	name,
		const char *	query,
		const char *	operation = NULL,
		const char *	data = NULL,
		uint32	datasize = 0,
		uint32	timeout = 5000 )

Send a query to another module or catalog by named <query> spec entry, receiving raw bytes back.

The spec entry name (looked up under the current trigger, so a trigger must have arrived first) defines the target component and default operation/keys; the call composes a CTRL_QUERY message, sends it and blocks up to timeout ms for the reply, whose "ReplyData" payload is copied into a new buffer for the caller. If the spec entry names a remote host, the query transparently becomes an inter-system query (CTRL_INTERSYSTEM_QUERY).

char* bytes = NULL;
uint32 size = 0;
uint8 status = api->queryCatalog(&bytes, size, "ReadConfig", "config.xml", "read");
if (status == QUERY_SUCCESS && bytes) {
    // use bytes[0..size-1] ...
    delete [] bytes;               // caller owns the reply buffer
}

Parameters

result	Receives a newly allocated copy of the reply data (NULL if none); the CALLER owns it and must delete [] it.
resultsize	Receives the size of the reply data in bytes.
name	name of the query defined in the PsySpec
query	the actual query sent to the catalog
operation	specify the custom operation by name (example could be 'read' or 'write' for the FileCatalog)
data	provide optional data to send to as part of the query (example could be the data to write to a file for the FileCatalog)
datasize	size of the optional data
timeout	maximum time to wait for the reply, in ms

Returns

One of the QUERY_* status codes (QUERY_SUCCESS on success).

Note

Blocking call (up to timeout ms).

Definition at line 1110 of file PsyAPI.cpp.

References cmlabs::QuerySpec::binary, CTRL_INTERSYSTEM_QUERY, CTRL_QUERY, cmlabs::QuerySpec::ext, cmlabs::DataMessage::getDataCopy(), cmlabs::QuerySpec::hostName, cmlabs::QuerySpec::ipHost, cmlabs::QuerySpec::ipPort, cmlabs::QuerySpec::key, cmlabs::utils::LookupIPAddress(), cmlabs::QuerySpec::name, cmlabs::QuerySpec::operation, QUERY_COMPONENT_UNKNOWN, QUERY_FAILED, QUERY_NAME_UNKNOWN, cmlabs::DataMessage::setData(), cmlabs::DataMessage::setFrom(), cmlabs::DataMessage::setInt(), cmlabs::DataMessage::setString(), cmlabs::DataMessage::setTo(), cmlabs::DataMessage::setType(), cmlabs::QuerySpec::source, cmlabs::QuerySpec::sourceName, cmlabs::QuerySpec::subdir, cmlabs::QuerySpec::type, and cmlabs::QuerySpec::value.

Referenced by cmlabs::Internal_QueryTest(), cmlabs::Internal_RetrieveTest(), Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1queryCatalog_1_1SWIG_10(), Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1queryCatalog_1_1SWIG_11(), Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1queryCatalog_1_1SWIG_12(), Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1queryCatalog_1_1SWIG_13(), and Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1queryCatalog_1_1SWIG_14().

queryCatalog() [2/2]

uint8 cmlabs::PsyAPI::queryCatalog	(	DataMessage **	resultMsg,
		const char *	name,
		DataMessage *	msg,
		uint32	timeout = 5000 )

Send a message-based query to another module or catalog by named spec entry.

Like the raw-bytes overload, but the caller supplies a full DataMessage as the query input and receives a full DataMessage reply, which is more convenient when the exchange carries structured key/value data.

DataMessage* q = new DataMessage();
q->setString("Query", "lookup");
DataMessage* reply = NULL;
uint8 status = api->queryCatalog(&reply, "MyQuery", q, 3000); // q is consumed
if (status == QUERY_SUCCESS && reply) {
    // use reply ...
    delete reply;                  // caller owns the reply
}

Parameters

resultMsg	Receives the reply message, or NULL. The CALLER owns and must delete it.
name	name of the query defined in the PsySpec
msg	the msg to be sent to the catalog as the query input
timeout	maximum time to wait for the reply, in ms

Returns

One of the QUERY_* status codes.

Warning

Ownership: msg is consumed (deleted) by the call — do not delete or reuse it. Blocking call (up to timeout ms).

Definition at line 988 of file PsyAPI.cpp.

References cmlabs::QuerySpec::binary, CTRL_INTERSYSTEM_QUERY, CTRL_QUERY, cmlabs::QuerySpec::ext, cmlabs::QuerySpec::hostName, cmlabs::QuerySpec::ipHost, cmlabs::QuerySpec::ipPort, cmlabs::QuerySpec::key, logPrint(), cmlabs::utils::LookupIPAddress(), cmlabs::QuerySpec::operation, QUERY_COMPONENT_UNKNOWN, QUERY_FAILED, QUERY_NAME_UNKNOWN, cmlabs::DataMessage::setFrom(), cmlabs::DataMessage::setInt(), cmlabs::DataMessage::setString(), cmlabs::DataMessage::setTo(), cmlabs::DataMessage::setType(), cmlabs::QuerySpec::source, cmlabs::QuerySpec::sourceName, cmlabs::QuerySpec::subdir, cmlabs::QuerySpec::type, and cmlabs::QuerySpec::value.

queryRemoteCatalog() [1/3]

uint8 cmlabs::PsyAPI::queryRemoteCatalog	(	DataMessage **	resultMsg,
		const char *	componentName,
		const char *	ipAddress,
		uint16	port,
		DataMessage *	msg,
		uint32	timeout = 5000 )

Send a query to a component in a different Psyclone system by hostname/IP.

The query is wrapped as CTRL_INTERSYSTEM_QUERY and routed via the local system's network layer to the remote system's main port; no PsySpec entry is needed. Useful for bridging independent Psyclone deployments.

Parameters

resultMsg	Receives the reply message, or NULL. The CALLER owns and must delete it.
componentName	name of the component to be queried in the remote system
ipAddress	IP address or hostname of the remote system in text (resolved via DNS)
port	main Psyclone port of the remote system
msg	the msg to be sent to the catalog as the query input; consumed (deleted) by the call
timeout	maximum time to wait for the reply, in ms

Returns

One of the QUERY_* status codes (QUERY_NOT_AVAILABLE if the name does not resolve).

Note

Blocking call (up to timeout ms, plus DNS resolution time).

Definition at line 1054 of file PsyAPI.cpp.

References cmlabs::utils::LookupIPAddress(), QUERY_NOT_AVAILABLE, and queryRemoteCatalog().

Referenced by queryRemoteCatalog(), and queryRemoteCatalog().

queryRemoteCatalog() [2/3]

uint8 cmlabs::PsyAPI::queryRemoteCatalog	(	DataMessage **	resultMsg,
		const char *	componentName,
		uint32	ipAddress,
		uint16	port,
		DataMessage *	msg,
		uint32	timeout = 5000 )

Send a query to a component in a different Psyclone system by numeric IP.

See the hostname overload for semantics; this variant skips DNS resolution.

Parameters

resultMsg	Receives the reply message, or NULL. The CALLER owns and must delete it.
componentName	name of the component to be queried in the remote system
ipAddress	IP address of the remote system in UINT32 format
port	main Psyclone port of the remote system
msg	the msg to be sent to the catalog as the query input; consumed (deleted) by the call
timeout	maximum time to wait for the reply, in ms

Returns

One of the QUERY_* status codes. Blocking call.

Definition at line 1087 of file PsyAPI.cpp.

References CTRL_INTERSYSTEM_QUERY, QUERY_FAILED, cmlabs::DataMessage::setFrom(), cmlabs::DataMessage::setInt(), cmlabs::DataMessage::setString(), cmlabs::DataMessage::setTo(), and cmlabs::DataMessage::setType().

queryRemoteCatalog() [3/3]

uint8 cmlabs::PsyAPI::queryRemoteCatalog	(	DataMessage **	resultMsg,
		uint32 &	chosenAddress,
		const char *	componentName,
		uint32 *	ipAddresses,
		uint32	numAddresses,
		uint16	port,
		DataMessage *	msg,
		uint32	timeout = 5000 )

Send a query to a multi-homed remote Psyclone system, trying a list of addresses.

Failover variant: if chosenAddress is >0 that (1-based) address is tried first; on QUERY_NOT_REACHABLE the remaining addresses are tried in order. On success chosenAddress is updated to the index of the address that worked, so a caller can remember it and skip the scan next time.

Parameters

resultMsg	Receives the reply message, or NULL. The CALLER owns and must delete it.
chosenAddress	In: 1-based index of the address to try first (0 = scan all). Out: index of the first working address.
componentName	name of the component to be queried in the remote system
ipAddresses	list of IP addresses of the remote system in UINT32 format
numAddresses	number of addresses presented
port	main Psyclone port of the remote system
msg	the msg to be sent to the catalog as the query input; consumed by the call
timeout	maximum time to wait per attempt, in ms

Returns

One of the QUERY_* status codes; QUERY_NOT_REACHABLE if no address connected.

Warning

Worst-case blocking time is roughly timeout × numAddresses when all addresses are unreachable.

Definition at line 1061 of file PsyAPI.cpp.

References QUERY_NOT_AVAILABLE, QUERY_NOT_REACHABLE, and queryRemoteCatalog().

queryReply() [1/2]

bool cmlabs::PsyAPI::queryReply	(	uint32	id,
		uint8	status,
		char *	data,
		uint32	size,
		uint32	count )

Used by a module to reply to an incoming query by id.

Status can be

#define QUERY_FAILED 1

#define QUERY_TIMEOUT 2

#define QUERY_NAME_UNKNOWN 3

#define QUERY_COMPONENT_UNKNOWN 4

#define QUERY_QUERYFAILED 5

#define QUERY_SUCCESS 6

#define QUERY_NOT_AVAILABLE 7

Binary reply data of size size can be added and a count can indicate the number of entries in the data chunk.

Parameters

id	id of the incoming query to reply to
status	see description
data	optional binary data to reply with (copied into the reply; caller keeps ownership of the buffer)
size	size of optional binary data
count	optional resulting count for operation, if appropriate

Returns

true if reply was successful

Definition at line 1189 of file PsyAPI.cpp.

References CTRL_QUERY_REPLY, queryReply(), cmlabs::DataMessage::setData(), and cmlabs::DataMessage::setInt().

Referenced by Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1queryReply_1_1SWIG_10(), Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1queryReply_1_1SWIG_12(), and queryReply().

queryReply() [2/2]

bool cmlabs::PsyAPI::queryReply	(	uint32	id,
		uint8	status,
		DataMessage *	msg = NULL )

Used by a module to send a message as a reply to an incoming query.

Parameters

id	id of the incoming query to reply to
status	see description of queryReply(uint32 id, uint8 status, char* data, uint32 size, uint32 count);
msg	reply payload; ownership transfers to the system (do not delete or reuse). May be NULL for a status-only reply.

Returns

true if reply was successful

Definition at line 1202 of file PsyAPI.cpp.

removePsyProbeCustomView()

bool cmlabs::PsyAPI::removePsyProbeCustomView ( const char * name )

inline

Remove a custom module view tab for the PsyProbe web interface.

Parameters

name	name of the custom view

Returns

true if removal was successful

Definition at line 535 of file PsyAPI.h.

References addPsyProbeCustomView().

Referenced by Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1removePsyProbeCustomView().

resetParameter()

bool cmlabs::PsyAPI::resetParameter ( const char * name )

inline

Reset parameter to its default (or initial) value.

Parameters

name	name of the parameter

Returns

true if successful

Definition at line 967 of file PsyAPI.h.

Referenced by Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1resetParameter().

retrieve() [1/2]

uint8 cmlabs::PsyAPI::retrieve	(	std::list< DataMessage * > &	result,
		const char *	name,
		uint32	maxcount = 0,
		uint32	maxage = 0,
		uint32	timeout = 5000 )

Retrieve stored messages from a whiteboard, by named <retrieve> spec entry.

The retrieve entry in the PsySpec (looked up by name under the current trigger, so a trigger must have arrived first) says which whiteboard to ask and how to filter; maxcount / maxage further narrow the result at call time. Under the hood this sends a CTRL_QUERY message to the whiteboard component and blocks up to timeout ms for the reply.

std::list<DataMessage*> hits;
uint8 status = api->retrieve(hits, "RecentUtterances", 10, 60000);
if (status == QUERY_SUCCESS) {
    for (DataMessage* m : hits) {
        // use m ...
        delete m;                      // caller owns each retrieved message
    }
}

Parameters

result	Output list the function fills with the retrieved messages.
name	Name of the retrieve entry in the PsySpec.
maxcount	Maximum number of messages to retrieve (0 = spec/unlimited).
maxage	Maximum age of the messages in ms (0 = spec/unlimited).
timeout	Maximum time to wait for the whiteboard's reply, in ms.

Returns

One of the QUERY_* status codes (QUERY_SUCCESS on success).

Note

Ownership: the messages placed in result are fresh copies — the CALLER owns them and must delete each one. Blocking call (up to timeout ms).

Definition at line 757 of file PsyAPI.cpp.

References cmlabs::RetrieveSpec::maxage, cmlabs::RetrieveSpec::maxcount, QUERY_FAILED, QUERY_NAME_UNKNOWN, and retrieve().

Referenced by cmlabs::Internal_RetrieveTest(), retrieve(), retrieveFloatParam(), retrieveIntegerParam(), retrieveStringParam(), and retrieveTimeParam().

retrieve() [2/2]

uint8 cmlabs::PsyAPI::retrieve	(	std::list< DataMessage * > &	result,
		RetrieveSpec *	spec,
		uint32	timeout = 5000 )

Used by a module to retrieve messages from a whiteboard.

The retrieve details are provided in the module spec by name.

Parameters

result	Output list the function fills with the retrieved messages (caller owns each; delete them).
spec	A fully populated RetrieveSpec describing the retrieval (advanced use; the named overloads build this from the PsySpec).
timeout	maximum time to wait for the whiteboard's reply, in ms

Returns

One of the QUERY_* status codes; see retrieve(std::list<DataMessage*>&, const char*, uint32, uint32, uint32).

Definition at line 923 of file PsyAPI.cpp.

References CTRL_QUERY, DATAMESSAGEID, cmlabs::DataMessage::getData(), cmlabs::DataMessage::getInt(), GetObjID, cmlabs::DataMessage::getSize(), logPrint(), cmlabs::RetrieveSpec::origin, QUERY_FAILED, QUERY_SUCCESS, cmlabs::DataMessage::setData(), and cmlabs::RetrieveSpec::source.

retrieveAllSystemIDs()

DataMessage * cmlabs::PsyAPI::retrieveAllSystemIDs ( )

inline

This function retrieves all names for types, contexts and components.

Returns

message containing all names for types, contexts and components

Definition at line 501 of file PsyAPI.h.

retrieveFloatParam()

uint8 cmlabs::PsyAPI::retrieveFloatParam	(	std::list< DataMessage * > &	result,
		const char *	name,
		float64	startFloat,
		float64	endFloat = FLOAT64_NOVALUE,
		uint32	maxcount = 0,
		uint32	maxage = 0,
		uint32	timeout = 5000 )

Used by a module to retrieve messages from a whiteboard.

The retrieve details are provided in the module spec by name. maxcount and maxage can be provided to add to the spec details.

Parameters

result	a bucket parameter filled by the function. A list of messages.
name	name of the whiteboard defined in the PsySpec
startFloat	this value marks the beginning of the selection of values that the functions shall return
endFloat	this value marks the end of the selection of values that the functions shall return
maxcount	the maximal number of messages to be retrieved (0 = spec/unlimited)
maxage	the maximal age of the messages in ms (0 = spec/unlimited)
timeout	maximum time to wait for the whiteboard's reply, in ms

Returns

One of the QUERY_* status codes. Retrieved messages in result are owned by the caller (delete each); see retrieve() for details and an example.

Definition at line 889 of file PsyAPI.cpp.

References cmlabs::RetrieveSpec::endFloat, FLOAT64_NOVALUE, cmlabs::RetrieveSpec::maxage, cmlabs::RetrieveSpec::maxcount, QUERY_FAILED, QUERY_NAME_UNKNOWN, retrieve(), and cmlabs::RetrieveSpec::startFloat.

retrieveIntegerParam()

uint8 cmlabs::PsyAPI::retrieveIntegerParam	(	std::list< DataMessage * > &	result,
		const char *	name,
		int64	startInteger,
		int64	endInteger = INT64_NOVALUE,
		uint32	maxcount = 0,
		uint32	maxage = 0,
		uint32	timeout = 5000 )

Used by a module to retrieve messages from a whiteboard.

The retrieve details are provided in the module spec by name. startInteger and endInteger can be provided to add to the spec details.

Parameters

result	a bucket parameter filled by the function. A list of messages.
name	name of the whiteboard defined in the PsySpec
startInteger	this value marks the beginning of the selection of values that the functions shall return
endInteger	this value marks the end of the selection of values that the functions shall return
maxcount	the maximal number of messages to be retrieved (0 = spec/unlimited)
maxage	the maximal age of the messages in ms (0 = spec/unlimited)
timeout	maximum time to wait for the whiteboard's reply, in ms

Returns

One of the QUERY_* status codes. Retrieved messages in result are owned by the caller (delete each); see retrieve() for details and an example.

Definition at line 854 of file PsyAPI.cpp.

References cmlabs::RetrieveSpec::endInt, INT64_NOVALUE, cmlabs::RetrieveSpec::maxage, cmlabs::RetrieveSpec::maxcount, QUERY_FAILED, QUERY_NAME_UNKNOWN, retrieve(), and cmlabs::RetrieveSpec::startInt.

Referenced by cmlabs::Internal_RetrieveTest().

retrieveStringParam()

uint8 cmlabs::PsyAPI::retrieveStringParam	(	std::list< DataMessage * > &	result,
		const char *	name,
		const char *	startString,
		const char *	endString = NULL,
		uint32	maxcount = 0,
		uint32	maxage = 0,
		uint32	timeout = 5000 )

Used by a module to retrieve messages from a whiteboard.

The retrieve details are provided in the module spec by name. startTime and endTime can be provided to add to the spec details.

Parameters

result	a bucket parameter filled by the function. A list of messages.
name	name of the whiteboard defined in the PsySpec
startString	this String marks the beginning of the selection of Strings that the functions shall return
endString	this String marks the end of the selection of Strings that the functions shall return
maxcount	the maximal number of messages to be retrieved (0 = spec/unlimited)
maxage	the maximal age of the messages in ms (0 = spec/unlimited)
timeout	maximum time to wait for the whiteboard's reply, in ms

Returns

One of the QUERY_* status codes. Retrieved messages in result are owned by the caller (delete each); see retrieve() for details and an example.

Definition at line 819 of file PsyAPI.cpp.

References cmlabs::RetrieveSpec::endString, cmlabs::RetrieveSpec::maxage, cmlabs::RetrieveSpec::maxcount, MAXVALUENAMELEN, QUERY_FAILED, QUERY_NAME_UNKNOWN, retrieve(), cmlabs::RetrieveSpec::startString, and cmlabs::utils::strcpyavail().

retrieveTimeParam()

uint8 cmlabs::PsyAPI::retrieveTimeParam	(	std::list< DataMessage * > &	result,
		const char *	name,
		uint64	startTime,
		uint64	endTime = 0,
		uint32	maxcount = 0,
		uint32	maxage = 0,
		uint32	timeout = 5000 )

Used by a module to retrieve messages from a whiteboard.

The retrieve details are provided in the module spec by name. maxcount and maxage can be provided to add to the spec details.

Parameters

result	a bucket parameter filled by the function. A list of messages.
name	name of the whiteboard defined in the PsySpec
startTime	only messages created at or after this time are retrieved
endTime	only messages created at or before this time are retrieved (0 = no limit)
maxcount	the maximal number of messages to be retrieved (0 = spec/unlimited)
maxage	the maximal age of the messages in ms (0 = spec/unlimited)
timeout	maximum time to wait for the whiteboard's reply, in ms

Returns

One of the QUERY_* status codes. Retrieved messages in result are owned by the caller (delete each); see retrieve() for details and an example.

Definition at line 785 of file PsyAPI.cpp.

References cmlabs::RetrieveSpec::endTime, cmlabs::RetrieveSpec::maxage, cmlabs::RetrieveSpec::maxcount, QUERY_FAILED, QUERY_NAME_UNKNOWN, retrieve(), and cmlabs::RetrieveSpec::startTime.

setAutoDelete()

bool cmlabs::PsyAPI::setAutoDelete

(

bool

autodel

)

Internal use only.

Definition at line 530 of file PsyAPI.cpp.

Referenced by Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1setAutoDelete().

setCommandlineBasedir()

bool cmlabs::PsyAPI::setCommandlineBasedir

(

const char *

cmdlineBasedir

)

Internal use only.

Definition at line 110 of file PsyAPI.cpp.

References MAXCOMMANDLINELEN, and cmlabs::utils::strcpyavail().

Referenced by cmlabs::PsySpace::getCrankAPI(), and Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1setCommandlineBasedir().

setParameter() [1/3]

bool cmlabs::PsyAPI::setParameter ( const char * name, const char * val )

inline

Set string parameter value.

Parameters

name	name of the parameter
val	value of the parameter

Returns

true if successful

Definition at line 932 of file PsyAPI.h.

Referenced by Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1setParameter_1_1SWIG_10(), Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1setParameter_1_1SWIG_11(), and Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1setParameter_1_1SWIG_12().

setParameter() [2/3]

bool cmlabs::PsyAPI::setParameter ( const char * name, float64 val )

inline

Set float parameter value.

Parameters

name	name of the parameter
val	value of the parameter

Returns

true if successful

Definition at line 956 of file PsyAPI.h.

setParameter() [3/3]

bool cmlabs::PsyAPI::setParameter ( const char * name, int64 val )

inline

Set integer parameter value.

Parameters

name	name of the parameter
val	value of the parameter

Returns

true if successful

Definition at line 944 of file PsyAPI.h.

setPrivateData()

bool cmlabs::PsyAPI::setPrivateData ( const char * name, const char * data, uint64 size, const char * mimetype = NULL )

inline

Store a named chunk of data centrally, in the system's shared component memory.

Private data survives the crank exiting (or crashing) and being re-triggered later — it lives in the node's shared memory, keyed by component id, not in the crank's process memory. Use it for state that must persist across activations without setting up a whiteboard or external storage.

// save state on the way out ...
MyState st = ...;
api->setPrivateData("state", (const char*)&st, sizeof(st));
// ... and restore it on the next activation:
uint64 size = 0;
if (char* data = api->getPrivateDataCopy("state", size)) {
    if (size == sizeof(MyState))
        memcpy(&st, data, sizeof(MyState));
    delete [] data;                 // caller owns the copy
}

Parameters

name	name of the data chunk
data	the data to be stored (copied; the caller keeps ownership of its buffer)
size	memory size of the data
mimetype	optional mimetype of the data

Returns

true if successful

Definition at line 569 of file PsyAPI.h.

Referenced by Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1setPrivateData_1_1SWIG_10(), and Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1setPrivateData_1_1SWIG_11().

shouldContinue()

bool cmlabs::PsyAPI::shouldContinue

(

)

Check whether the crank should keep running, or exit its loop.

This is the cooperative shutdown mechanism of the CMSDK: when the system (or the hosting space) shuts the component down, this starts returning false. There is no forced thread kill, so a crank MUST poll this regularly — typically as the condition of its main processing loop — or it will keep the process from shutting down cleanly.

while (api->shouldContinue()) {
    if (DataMessage* msg = api->waitForNewMessage(100)) {
        // handle msg
    }
    // short timeout above ensures shouldContinue() is re-checked often
}

Returns

true if the crank should continue.

Note

If the internal mutex cannot be acquired within 1 second this returns true (i.e. it errs on the side of "keep running").

Definition at line 93 of file PsyAPI.cpp.

Referenced by _wrap_PsyAPI_shouldContinue(), _wrap_PsyAPI_shouldContinue(), 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(), and Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1shouldContinue().

tweakParameter()

bool cmlabs::PsyAPI::tweakParameter ( const char * name, int32 tweak )

inline

Step up or down list or range parameter value.

If list steps to next or previous value, if range adds or subtracts interval while staying in the min-max range.

Parameters

name	name of the parameter
tweak	number of steps to tweak, positive is upwards, negative is downwards

Returns

true if successful

Definition at line 980 of file PsyAPI.h.

Referenced by Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1tweakParameter().

typeToText()

std::string cmlabs::PsyAPI::typeToText

(

PsyType

type

)

Get textual representation of the type.

Parameters

type	type as PsyType object

Returns

type as string

Definition at line 254 of file PsyAPI.cpp.

Referenced by cmlabs::Internal_Ping(), cmlabs::Internal_Print(), and cmlabs::Internal_RetrieveTest().

waitForNewMessage() [1/2]

DataMessage * cmlabs::PsyAPI::waitForNewMessage

(

uint32

ms

)

Wait for the next trigger message from the component's input queue.

This is the heart of a crank's main loop: it blocks (on a semaphore) for up to ms milliseconds until a trigger delivery is available, dequeues it, makes it the "current" message/trigger context (so getCurrentTriggerName(), postOutputMessage(), emitSignal(), retrieve() and queryCatalog() know which spec entries are active), updates the component's CPU/wall statistics, and returns the data message.

while (api->shouldContinue()) {
    DataMessage* msg = api->waitForNewMessage(100);
    if (!msg)
        continue;                        // timeout - loop and re-check shouldContinue()
    const char* text = msg->getString("content");
    // ... compute something ...
    DataMessage* out = new DataMessage();
    out->setString("result", "done");
    api->postOutputMessage(NULL, out);   // post per the active spec entries
}

Parameters

ms	Maximum time to block, in milliseconds. Use a short timeout (e.g. 100 ms) so the surrounding loop can re-check shouldContinue() promptly.

Returns

The message, or NULL if none arrived within the timeout.

Note

Ownership: the returned message is owned by the API handle — do NOT delete it. It remains valid until the next call to waitForNewMessage(), which frees the previous one (unless auto-delete has been disabled internally).

Backpressure: if the input queue has grown beyond 100 entries, queued messages whose policy includes MESSAGE_NON_GUARANTEED are silently dropped until the queue is back under the limit — only guaranteed traffic survives an overloaded component.

Warning

Call only from the single thread driving this crank; a PsyAPI is not meant to be shared between threads.

Definition at line 371 of file PsyAPI.cpp.

References waitForNewMessage().

Referenced by 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(), waitForNewMessage(), and waitForNewMessageGroup().

waitForNewMessage() [2/2]

DataMessage * cmlabs::PsyAPI::waitForNewMessage	(	uint32	ms,
		const char *&	triggerName )

This function waits for the next trigger message to arrive and if it did within the timeout (ms) the message is returned and triggerName indicates the name of the trigger from the spec.

The message is owned by the system and should never be deleted by the crank. If no message arrives within the timeout NULL is returned.

Parameters

ms	the timeout in milliseconds
triggerName	Receives a pointer to the trigger name from the spec, or NULL when the dequeued item was not a trigger delivery (e.g. an incoming query). Points into an internal buffer — valid only until the next waitForNewMessage() call; copy it if you need to keep it.

Returns

the message or NULL if none arrives

Note

Same blocking, ownership and overload-drop semantics as waitForNewMessage(uint32); see there for the details and a usage example.

Definition at line 388 of file PsyAPI.cpp.

References cmlabs::DataMessageHeader::chaincount, cmlabs::DataMessageHeader::chaincputime, cmlabs::DataMessageHeader::chainwalltime, COMPSTATUS_RUNNING, cmlabs::DataMessage::data, cmlabs::utils::GetCPUTicks(), cmlabs::DataMessage::getData(), cmlabs::GetTimeNow(), MAXKEYNAMELEN, MESSAGE_NON_GUARANTEED, and cmlabs::utils::strcpyavail().

waitForNewMessageGroup()

std::map< std::string, DataMessage * > cmlabs::PsyAPI::waitForNewMessageGroup	(	uint32	ms,
		std::string &	groupName )

T1.6: Wait for the next <triggergroup> joined-set delivery from the input queue.

Blocks up to ms ms for a CTRL_TRIGGER_GROUP activation, makes it the current trigger context (getCurrentTriggerName() returns the group name), and returns the completed (or partial, on timeout) set as a map of member trigger name -> message. Optional/absent members are simply not in the map (crank checks map.count("name")). Ordinary single-message deliveries are ignored here — use waitForNewMessage() for those.

Parameters

ms	Maximum time to block, in milliseconds.
groupName	Set to the group name that fired (empty if none/timeout).

Returns

Map of trigger name -> message; empty on timeout. Messages are owned by the API handle and freed on the next waitForNewMessageGroup()/waitForNewMessage() call.

Definition at line 502 of file PsyAPI.cpp.

References CTRL_TRIGGER_GROUP, and waitForNewMessage().

waitForSignal()

DataMessage * cmlabs::PsyAPI::waitForSignal	(	const char *	name,
		uint32	timeout,
		uint64	lastReceivedTime = 0 )

Wait for a signal (latest-value broadcast) by its spec name.

Blocks for up to timeout ms until a signal matching the spec entry name has been emitted. Because signals are latest-value, lastReceivedTime is how a polling loop avoids seeing the same emission twice: pass the send time of the last signal you processed and only newer ones are returned.

uint64 lastSeen = 0;
while (api->shouldContinue()) {
    if (DataMessage* sig = api->waitForSignal("Heartbeat", 500, lastSeen)) {
        lastSeen = sig->getCreatedTime();   // do not delete sig - owned by the API
        // react to the signal ...
    }
}

Parameters

name	name of the signal that is waited for (from the spec of the current trigger)
timeout	maximum time to block, in milliseconds
lastReceivedTime	signals sent at or before this PsyTime timestamp are skipped; 0 returns the next unread signal

Returns

the signal message, or NULL on timeout / unknown name / no active trigger context.

Note

Ownership: the returned message is owned by the API handle and freed on the next successful waitForSignal() call — do not delete it.

Definition at line 725 of file PsyAPI.cpp.

References cmlabs::SignalSpec::type.

Referenced by cmlabs::Internal_SignalPing(), and cmlabs::Internal_SignalPong().

Friends And Related Symbol Documentation

PsySpace

friend class PsySpace

friend

Definition at line 83 of file PsyAPI.h.

References PsySpace.

Referenced by PsyAPI(), and PsySpace.

Member Data Documentation

CTRL_ADDSUBSCRIPTION

struct PsyType cmlabs::PsyAPI::CTRL_ADDSUBSCRIPTION = { { 1,10305,0,0,0,0,0,0,0,0,0,0,0,0,0,0 } }

static

Adds triggers/posts to a registration at runtime.

Definition at line 103 of file PsyAPI.h.

Referenced by addSubscription(), Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1CTRL_1ADDSUBSCRIPTION_1get(), Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1CTRL_1ADDSUBSCRIPTION_1set(), Swig_var_PsyAPI_CTRL_ADDSUBSCRIPTION_get(), and Swig_var_PsyAPI_CTRL_ADDSUBSCRIPTION_set().

CTRL_CONTEXT_CHANGE

struct PsyType cmlabs::PsyAPI::CTRL_CONTEXT_CHANGE = { { 1,10297,0,0,0,0,0,0,0,0,0,0,0,0,0,0 } }

static

Announces a system context change.

Definition at line 94 of file PsyAPI.h.

Referenced by Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1CTRL_1CONTEXT_1CHANGE_1get(), Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1CTRL_1CONTEXT_1CHANGE_1set(), postOutputMessage(), Swig_var_PsyAPI_CTRL_CONTEXT_CHANGE_get(), and Swig_var_PsyAPI_CTRL_CONTEXT_CHANGE_set().

CTRL_CREATECUSTOMPAGE

struct PsyType cmlabs::PsyAPI::CTRL_CREATECUSTOMPAGE = { { 1,10304,0,0,0,0,0,0,0,0,0,0,0,0,0,0 } }

static

Registers a custom PsyProbe view.

Definition at line 102 of file PsyAPI.h.

Referenced by cmlabs::PsySpace::addPsyProbeCustomView(), Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1CTRL_1CREATECUSTOMPAGE_1get(), Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1CTRL_1CREATECUSTOMPAGE_1set(), Swig_var_PsyAPI_CTRL_CREATECUSTOMPAGE_get(), and Swig_var_PsyAPI_CTRL_CREATECUSTOMPAGE_set().

CTRL_INTERSYSTEM_QUERY

struct PsyType cmlabs::PsyAPI::CTRL_INTERSYSTEM_QUERY = { { 1,10998,0,0,0,0,0,0,0,0,0,0,0,0,0,0 } }

static

Query crossing to a different Psyclone system.

Definition at line 105 of file PsyAPI.h.

Referenced by Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1CTRL_1INTERSYSTEM_1QUERY_1get(), Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1CTRL_1INTERSYSTEM_1QUERY_1set(), queryCatalog(), queryCatalog(), queryRemoteCatalog(), Swig_var_PsyAPI_CTRL_INTERSYSTEM_QUERY_get(), and Swig_var_PsyAPI_CTRL_INTERSYSTEM_QUERY_set().

CTRL_INTERSYSTEM_QUERY_REPLY

struct PsyType cmlabs::PsyAPI::CTRL_INTERSYSTEM_QUERY_REPLY = { { 1,10999,0,0,0,0,0,0,0,0,0,0,0,0,0,0 } }

static

Reply from a different Psyclone system.

Definition at line 106 of file PsyAPI.h.

Referenced by Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1CTRL_1INTERSYSTEM_1QUERY_1REPLY_1get(), Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1CTRL_1INTERSYSTEM_1QUERY_1REPLY_1set(), cmlabs::PsySpace::queryReply(), Swig_var_PsyAPI_CTRL_INTERSYSTEM_QUERY_REPLY_get(), and Swig_var_PsyAPI_CTRL_INTERSYSTEM_QUERY_REPLY_set().

CTRL_PROCESS_GREETING

struct PsyType cmlabs::PsyAPI::CTRL_PROCESS_GREETING = { { 1,10202,0,0,0,0,0,0,0,0,0,0,0,0,0,0 } }

static

Handshake from a newly joined process.

Definition at line 92 of file PsyAPI.h.

Referenced by cmlabs::PsySpace::connect(), Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1CTRL_1PROCESS_1GREETING_1get(), Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1CTRL_1PROCESS_1GREETING_1set(), Swig_var_PsyAPI_CTRL_PROCESS_GREETING_get(), and Swig_var_PsyAPI_CTRL_PROCESS_GREETING_set().

CTRL_PROCESS_INITIALISE

struct PsyType cmlabs::PsyAPI::CTRL_PROCESS_INITIALISE = { { 1,10201,0,0,0,0,0,0,0,0,0,0,0,0,0,0 } }

static

Sent to a process to initialise it.

Definition at line 91 of file PsyAPI.h.

Referenced by cmlabs::PsySpace::connect(), Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1CTRL_1PROCESS_1INITIALISE_1get(), Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1CTRL_1PROCESS_1INITIALISE_1set(), Swig_var_PsyAPI_CTRL_PROCESS_INITIALISE_get(), and Swig_var_PsyAPI_CTRL_PROCESS_INITIALISE_set().

CTRL_PROCESS_SHUTDOWN

struct PsyType cmlabs::PsyAPI::CTRL_PROCESS_SHUTDOWN = { { 1,10203,0,0,0,0,0,0,0,0,0,0,0,0,0,0 } }

static

Orders a single process to shut down.

Definition at line 93 of file PsyAPI.h.

Referenced by Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1CTRL_1PROCESS_1SHUTDOWN_1get(), Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1CTRL_1PROCESS_1SHUTDOWN_1set(), cmlabs::PsySpace::shutdown(), Swig_var_PsyAPI_CTRL_PROCESS_SHUTDOWN_get(), and Swig_var_PsyAPI_CTRL_PROCESS_SHUTDOWN_set().

CTRL_PULLCOMPONENTDATA

struct PsyType cmlabs::PsyAPI::CTRL_PULLCOMPONENTDATA = { { 1,10303,0,0,0,0,0,0,0,0,0,0,0,0,0,0 } }

static

Requests component data from another node.

Definition at line 101 of file PsyAPI.h.

Referenced by Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1CTRL_1PULLCOMPONENTDATA_1get(), Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1CTRL_1PULLCOMPONENTDATA_1set(), Swig_var_PsyAPI_CTRL_PULLCOMPONENTDATA_get(), and Swig_var_PsyAPI_CTRL_PULLCOMPONENTDATA_set().

CTRL_QUERY

struct PsyType cmlabs::PsyAPI::CTRL_QUERY = { { 1,10301,0,0,0,0,0,0,0,0,0,0,0,0,0,0 } }

static

Carries a query to a component/catalog.

Definition at line 99 of file PsyAPI.h.

Referenced by Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1CTRL_1QUERY_1get(), Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1CTRL_1QUERY_1set(), queryCatalog(), queryCatalog(), retrieve(), Swig_var_PsyAPI_CTRL_QUERY_get(), and Swig_var_PsyAPI_CTRL_QUERY_set().

CTRL_QUERY_REPLY

struct PsyType cmlabs::PsyAPI::CTRL_QUERY_REPLY = { { 1,10302,0,0,0,0,0,0,0,0,0,0,0,0,0,0 } }

static

Carries a query reply back to the asker.

Definition at line 100 of file PsyAPI.h.

Referenced by Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1CTRL_1QUERY_1REPLY_1get(), Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1CTRL_1QUERY_1REPLY_1set(), queryReply(), cmlabs::PsySpace::queryReply(), Swig_var_PsyAPI_CTRL_QUERY_REPLY_get(), and Swig_var_PsyAPI_CTRL_QUERY_REPLY_set().

CTRL_RETRIEVESYSTEMIDS

struct PsyType cmlabs::PsyAPI::CTRL_RETRIEVESYSTEMIDS = { { 1,10306,0,0,0,0,0,0,0,0,0,0,0,0,0,0 } }

static

Requests the full id/name tables.

Definition at line 104 of file PsyAPI.h.

Referenced by Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1CTRL_1RETRIEVESYSTEMIDS_1get(), Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1CTRL_1RETRIEVESYSTEMIDS_1set(), Swig_var_PsyAPI_CTRL_RETRIEVESYSTEMIDS_get(), and Swig_var_PsyAPI_CTRL_RETRIEVESYSTEMIDS_set().

CTRL_SYSTEM_READY

struct PsyType cmlabs::PsyAPI::CTRL_SYSTEM_READY = { { 1,10200,0,0,0,0,0,0,0,0,0,0,0,0,0,0 } }

static

Broadcast when the system has fully started.

Definition at line 90 of file PsyAPI.h.

Referenced by Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1CTRL_1SYSTEM_1READY_1get(), Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1CTRL_1SYSTEM_1READY_1set(), Swig_var_PsyAPI_CTRL_SYSTEM_READY_get(), and Swig_var_PsyAPI_CTRL_SYSTEM_READY_set().

CTRL_SYSTEM_SHUTDOWN

struct PsyType cmlabs::PsyAPI::CTRL_SYSTEM_SHUTDOWN = { { 1,10298,0,0,0,0,0,0,0,0,0,0,0,0,0,0 } }

static

Orders a full system shutdown.

Definition at line 95 of file PsyAPI.h.

Referenced by Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1CTRL_1SYSTEM_1SHUTDOWN_1get(), Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1CTRL_1SYSTEM_1SHUTDOWN_1set(), Swig_var_PsyAPI_CTRL_SYSTEM_SHUTDOWN_get(), and Swig_var_PsyAPI_CTRL_SYSTEM_SHUTDOWN_set().

CTRL_SYSTEM_SHUTTINGDOWN

struct PsyType cmlabs::PsyAPI::CTRL_SYSTEM_SHUTTINGDOWN = { { 1,10299,0,0,0,0,0,0,0,0,0,0,0,0,0,0 } }

static

Broadcast while shutdown is in progress.

Definition at line 96 of file PsyAPI.h.

Referenced by Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1CTRL_1SYSTEM_1SHUTTINGDOWN_1get(), Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1CTRL_1SYSTEM_1SHUTTINGDOWN_1set(), Swig_var_PsyAPI_CTRL_SYSTEM_SHUTTINGDOWN_get(), and Swig_var_PsyAPI_CTRL_SYSTEM_SHUTTINGDOWN_set().

CTRL_TRIGGER

struct PsyType cmlabs::PsyAPI::CTRL_TRIGGER = { { 1,10300,0,0,0,0,0,0,0,0,0,0,0,0,0,0 } }

static

Wraps a trigger delivery to a component.

Definition at line 97 of file PsyAPI.h.

Referenced by Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1CTRL_1TRIGGER_1get(), Java_com_cmlabs_cmsdk_cmsdkJNI_PsyAPI_1CTRL_1TRIGGER_1set(), Swig_var_PsyAPI_CTRL_TRIGGER_get(), and Swig_var_PsyAPI_CTRL_TRIGGER_set().

CTRL_TRIGGER_GROUP

struct PsyType cmlabs::PsyAPI::CTRL_TRIGGER_GROUP = { { 1,10307,0,0,0,0,0,0,0,0,0,0,0,0,0,0 } }

static

T1.6: wraps a <triggergroup> joined-set delivery (member map) to a component.

Definition at line 98 of file PsyAPI.h.

Referenced by waitForNewMessageGroup().

---

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

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