PsyAPI.h File Reference

PsyAPI — the component-facing API handle of the CMSDK. More...

#include "MemoryManager.h"
#include "PsyTime.h"
#include "xml_parser.h"
#include "DataMessage.h"
#include "Subscriptions.h"
#include "PsySpace.h"

Include dependency graph for PsyAPI.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
class	cmlabs::PsyAPI
	The API handle a component (crank) uses to talk to the Psyclone system. More...

Namespaces
namespace	cmlabs

Macros
#define	LOG_COMPONENT   8
	Log source id used by components when writing entries to the system log.
Crank API status codes
States of a crank's API handle within its hosting PsySpace.
#define	CRANKAPI_FAILED   1
	The API could not be obtained or is invalid.
#define	CRANKAPI_INUSE   2
	The API is already in use by another thread.
#define	CRANKAPI_RUNNING   3
	The crank is currently executing.
#define	CRANKAPI_IDLE   4
	The crank is idle, waiting for input.
Post result codes
Negative return values of PsyAPI::postOutputMessage(); non-negative values are the number of messages posted.
#define	POST_FAILED   -1
	An error occurred while posting.
#define	POST_NOSPEC   -2
	Posting attempted before any trigger arrived (no active spec).
#define	POST_OUTOFCONTEXT   -3
	The crank's context is no longer active.
Query status codes
Status values returned by the query/retrieve family of calls (PsyAPI::queryCatalog(), PsySpace::query(), ...).
#define	QUERY_FAILED   1
	General failure.
#define	QUERY_TIMEOUT   2
	No reply within the timeout.
#define	QUERY_NAME_UNKNOWN   3
	The query name is not defined in the spec.
#define	QUERY_COMPONENT_UNKNOWN   4
	The target component is unknown.
#define	QUERY_QUERYFAILED   5
	The target processed the query but reported failure.
#define	QUERY_SUCCESS   6
	The query succeeded.
#define	QUERY_NOT_AVAILABLE   7
	The target exists but is not available.
#define	QUERY_NOT_REACHABLE   8
	The target could not be reached (e.g.

Typedefs
typedef std::pair< DataMessage *, DataMessage * >	cmlabs::TriggerAndMessage
	Pairing of a trigger message and its accompanying data message, as queued for a crank's input.

Detailed Description

PsyAPI — the component-facing API handle of the CMSDK.

While PsySpace is the process/shared-memory context a component lives in, PsyAPI is the handle an individual component (crank) uses to interact with the running Psyclone system: waiting for trigger messages, posting output messages, emitting and waiting for signals, storing private data, managing parameters, and querying whiteboards and catalogs. Each component gets its own PsyAPI instance, created and owned by its hosting PsySpace (see PsySpace::getCrankAPI()).

Typical crank usage:

PsySpace space("MyProcess");
space.connect(1);                              // join system 1
PsyAPI* api = space.getCrankAPI("MyModule.MyCrank");
while (api->shouldContinue()) {
    if (DataMessage* msg = api->waitForNewMessage(100)) {
        // process msg (owned by the system, do not delete)
        api->postOutputMessage();              // post per active spec entries
    }
}

Definition in file PsyAPI.h.

Macro Definition Documentation

CRANKAPI_FAILED

#define CRANKAPI_FAILED   1

The API could not be obtained or is invalid.

Definition at line 38 of file PsyAPI.h.

CRANKAPI_IDLE

#define CRANKAPI_IDLE   4

The crank is idle, waiting for input.

Definition at line 41 of file PsyAPI.h.

CRANKAPI_INUSE

#define CRANKAPI_INUSE   2

The API is already in use by another thread.

Definition at line 39 of file PsyAPI.h.

CRANKAPI_RUNNING

#define CRANKAPI_RUNNING   3

The crank is currently executing.

Definition at line 40 of file PsyAPI.h.

LOG_COMPONENT

#define LOG_COMPONENT   8

Log source id used by components when writing entries to the system log.

Definition at line 68 of file PsyAPI.h.

Referenced by cmlabs::PsyAPI::logPrint().

POST_FAILED

#define POST_FAILED   -1

An error occurred while posting.

Definition at line 47 of file PsyAPI.h.

Referenced by cmlabs::PsyAPI::postOutputMessage().

POST_NOSPEC

#define POST_NOSPEC   -2

Posting attempted before any trigger arrived (no active spec).

Definition at line 48 of file PsyAPI.h.

Referenced by cmlabs::PsyAPI::postOutputMessage().

POST_OUTOFCONTEXT

#define POST_OUTOFCONTEXT   -3

The crank's context is no longer active.

Definition at line 49 of file PsyAPI.h.

Referenced by cmlabs::PsyAPI::postOutputMessage().

QUERY_COMPONENT_UNKNOWN

#define QUERY_COMPONENT_UNKNOWN   4

The target component is unknown.

Definition at line 58 of file PsyAPI.h.

Referenced by cmlabs::PsyAPI::queryCatalog(), and cmlabs::PsyAPI::queryCatalog().

QUERY_FAILED

#define QUERY_FAILED   1

General failure.

Definition at line 55 of file PsyAPI.h.

Referenced by cmlabs::PsySpace::query(), cmlabs::PsyAPI::queryCatalog(), cmlabs::PsyAPI::queryCatalog(), cmlabs::PsyAPI::queryRemoteCatalog(), cmlabs::PsyAPI::retrieve(), cmlabs::PsyAPI::retrieve(), cmlabs::PsyAPI::retrieveFloatParam(), cmlabs::PsyAPI::retrieveIntegerParam(), cmlabs::PsyAPI::retrieveStringParam(), and cmlabs::PsyAPI::retrieveTimeParam().

QUERY_NAME_UNKNOWN

#define QUERY_NAME_UNKNOWN   3

The query name is not defined in the spec.

Definition at line 57 of file PsyAPI.h.

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

QUERY_NOT_AVAILABLE

#define QUERY_NOT_AVAILABLE   7

The target exists but is not available.

Definition at line 61 of file PsyAPI.h.

Referenced by cmlabs::PsyAPI::queryRemoteCatalog(), and cmlabs::PsyAPI::queryRemoteCatalog().

QUERY_NOT_REACHABLE

#define QUERY_NOT_REACHABLE   8

The target could not be reached (e.g.

remote system down).

Definition at line 62 of file PsyAPI.h.

Referenced by cmlabs::PsySpace::query(), and cmlabs::PsyAPI::queryRemoteCatalog().

QUERY_QUERYFAILED

#define QUERY_QUERYFAILED   5

The target processed the query but reported failure.

Definition at line 59 of file PsyAPI.h.

QUERY_SUCCESS

#define QUERY_SUCCESS   6

The query succeeded.

Definition at line 60 of file PsyAPI.h.

Referenced by cmlabs::PsyAPI::addSubscription(), cmlabs::Internal_QueryTest(), cmlabs::Internal_RetrieveTest(), cmlabs::PsySpace::query(), cmlabs::PsySpace::queryReply(), and cmlabs::PsyAPI::retrieve().

QUERY_TIMEOUT

#define QUERY_TIMEOUT   2

No reply within the timeout.

Definition at line 56 of file PsyAPI.h.

Referenced by cmlabs::Internal_QueryTest(), cmlabs::Internal_RetrieveTest(), and cmlabs::PsySpace::query().