VuoTelemetry.h File Reference

Description

VuoTelemetry interface.

Copyright

Copyright © 2012–2020 Kosada Incorporated. This code may be modified and distributed under the terms of the MIT License. For more information, see https://vuo.org/license.

Definition in file VuoTelemetry.h.

Go to the source code of this file.

Enumerations
enum	VuoControlRequest {   VuoControlRequestCompositionStop, VuoControlRequestCompositionPause, VuoControlRequestCompositionUnpause, VuoControlRequestInputPortValueModify,   VuoControlRequestInputPortValueRetrieve, VuoControlRequestOutputPortValueRetrieve, VuoControlRequestInputPortSummaryRetrieve, VuoControlRequestOutputPortSummaryRetrieve,   VuoControlRequestTriggerPortFireEvent, VuoControlRequestPublishedInputPortNamesRetrieve, VuoControlRequestPublishedOutputPortNamesRetrieve, VuoControlRequestPublishedInputPortTypesRetrieve,   VuoControlRequestPublishedInputPortDetailsRetrieve, VuoControlRequestPublishedOutputPortTypesRetrieve, VuoControlRequestPublishedOutputPortDetailsRetrieve, VuoControlRequestPublishedInputPortFireEvent,   VuoControlRequestPublishedInputPortValueModify, VuoControlRequestPublishedInputPortValueRetrieve, VuoControlRequestPublishedOutputPortValueRetrieve, VuoControlRequestSlowHeartbeat,   VuoControlRequestInputPortTelemetrySubscribe, VuoControlRequestOutputPortTelemetrySubscribe, VuoControlRequestInputPortTelemetryUnsubscribe, VuoControlRequestOutputPortTelemetryUnsubscribe,   VuoControlRequestEventTelemetrySubscribe, VuoControlRequestEventTelemetryUnsubscribe, VuoControlRequestAllTelemetrySubscribe, VuoControlRequestAllTelemetryUnsubscribe }
	Control Requests, sent to the composition. More...
enum	VuoControlReply {   VuoControlReplyCompositionStopping, VuoControlReplyCompositionPaused, VuoControlReplyCompositionUnpaused, VuoControlReplyInputPortValueModified,   VuoControlReplyInputPortValueRetrieved, VuoControlReplyOutputPortValueRetrieved, VuoControlReplyInputPortSummaryRetrieved, VuoControlReplyOutputPortSummaryRetrieved,   VuoControlReplyTriggerPortFiredEvent, VuoControlReplyPublishedInputPortNamesRetrieved, VuoControlReplyPublishedOutputPortNamesRetrieved, VuoControlReplyPublishedInputPortTypesRetrieved,   VuoControlReplyPublishedInputPortDetailsRetrieved, VuoControlReplyPublishedOutputPortTypesRetrieved, VuoControlReplyPublishedOutputPortDetailsRetrieved, VuoControlReplyPublishedInputPortFiredEvent,   VuoControlReplyPublishedInputPortValueModified, VuoControlReplyPublishedInputPortValueRetrieved, VuoControlReplyPublishedOutputPortValueRetrieved, VuoControlReplyHeartbeatSlowed,   VuoControlReplyInputPortTelemetrySubscribed, VuoControlReplyOutputPortTelemetrySubscribed, VuoControlReplyInputPortTelemetryUnsubscribed, VuoControlReplyOutputPortTelemetryUnsubscribed,   VuoControlReplyEventTelemetrySubscribed, VuoControlReplyEventTelemetryUnsubscribed, VuoControlReplyAllTelemetrySubscribed, VuoControlReplyAllTelemetryUnsubscribed }
	Control Replies, sent from the composition. More...
enum	VuoLoaderControlRequest { VuoLoaderControlRequestCompositionReplace }
	Control Requests, sent to the composition loader. More...
enum	VuoLoaderControlReply { VuoLoaderControlReplyCompositionReplaced }
	Control Replies, sent from the composition loader. More...
enum	VuoTelemetry {   VuoTelemetryStats, VuoTelemetryNodeExecutionStarted, VuoTelemetryNodeExecutionFinished, VuoTelemetryInputPortsUpdated,   VuoTelemetryOutputPortsUpdated, VuoTelemetryPublishedOutputPortsUpdated, VuoTelemetryEventFinished, VuoTelemetryEventDropped,   VuoTelemetryError, VuoTelemetryStopRequested }
	Types of published telemetry data. More...

Functions
char *	vuoCopyStringFromMessage (zmq_msg_t *message)
	Copies the message data into a newly allocated string. More...
void	vuoInitMessageWithString (zmq_msg_t *message, const char *string)
	Copies the string (including null terminator) into the message data. More...
void	vuoInitMessageWithInt (zmq_msg_t *message, int value)
	Copies the int value into the message data. More...
void	vuoInitMessageWithBool (zmq_msg_t *message, bool value)
	Copies the bool value into the message data. More...
bool	VuoTelemetry_hasMoreToReceive (void *socket)
	Returns true if there are more messages to receive on the socket currently. More...
char *	vuoReceiveAndCopyString (void *socket, char **error)
	Receives the next message on the socket and copies it into a newly allocated string. More...
unsigned long	vuoReceiveUnsignedInt64 (void *socket, char **error)
	Receives the next message on the socket and copies it into an unsigned long. More...
int	vuoReceiveInt (void *socket, char **error)
	Receives the next message on the socket and copies it into an int. More...
bool	vuoReceiveBool (void *socket, char **error)
	Receives the next message on the socket and copies it into a bool. More...
void	vuoSend (const char *name, void *socket, int type, zmq_msg_t *messages, unsigned int messageCount, bool isNonBlocking, char **error)
	Sends the multipart message messages on ZMQ socket socket. More...
void	vuoMemoryBarrier (void)
	"Individual ØMQ sockets are not thread safe except in the case where full memory barriers are issued when migrating a socket from one thread to another. More...

Enumeration Type Documentation

VuoControlReply

enum VuoControlReply

Control Replies, sent from the composition.

Enumerator
VuoControlReplyCompositionStopping	Composition shutdown has been initiated.
VuoControlReplyCompositionPaused	Composition has been paused.
VuoControlReplyCompositionUnpaused	Composition has been unpaused.
VuoControlReplyInputPortValueModified	The input port's value has been set.
VuoControlReplyInputPortValueRetrieved	A string representation of the input port's value has been retrieved. Includes data message-parts: char *valueAsString;
VuoControlReplyOutputPortValueRetrieved	A string representation of the output port's value has been retrieved. Includes data message-parts: char *valueAsString;
VuoControlReplyInputPortSummaryRetrieved	A brief description of the input port's value has been retrieved. Includes data message-parts: char *summary;
VuoControlReplyOutputPortSummaryRetrieved	A brief description of the output port's value has been retrieved. Includes data message-parts: char *summary;
VuoControlReplyTriggerPortFiredEvent	An event has been fired from the trigger port.
VuoControlReplyPublishedInputPortNamesRetrieved	The list of published input ports' names has been retrieved. Includes data message-parts: char *name0 char *name1 ...
VuoControlReplyPublishedOutputPortNamesRetrieved	The list of published output ports' names has been retrieved. Includes data message-parts: char *name0 char *name1 ...
VuoControlReplyPublishedInputPortTypesRetrieved	The list of published input ports' types, as string representations, has been retrieved. Includes data message-parts: char *type0 char *type1 ...
VuoControlReplyPublishedInputPortDetailsRetrieved	The list of published input ports' details, as string representations, has been retrieved. Includes data message-parts: char *details0 char *details1 ...
VuoControlReplyPublishedOutputPortTypesRetrieved	The list of published output ports' types, as string representations, has been retrieved. Includes data message-parts: char *type0 char *type1 ...
VuoControlReplyPublishedOutputPortDetailsRetrieved	The list of published output ports' details, as string representations, has been retrieved. Includes data message-parts: char *details0 char *details1 ...
VuoControlReplyPublishedInputPortFiredEvent	An event has been fired through the published input port.
VuoControlReplyPublishedInputPortValueModified	The published input port values have been set.
VuoControlReplyPublishedInputPortValueRetrieved	A string representation of the published input port's value has been retrieved. Includes data message-parts: char *valueAsString;
VuoControlReplyPublishedOutputPortValueRetrieved	A string representation of the published output port's value has been retrieved. Includes data message-parts: char *valueAsString;
VuoControlReplyHeartbeatSlowed	The composition's heartbeat telemetry has been slowed.
VuoControlReplyInputPortTelemetrySubscribed	The composition has started sending telemetry for each event through the input port. A summary of the port's current value is included in the message. Includes data message-parts: char *valueAsString;
VuoControlReplyOutputPortTelemetrySubscribed	The composition has started sending telemetry for each event through the output port. A summary of the port's current value is included in the message. Includes data message-parts: char *valueAsString;
VuoControlReplyInputPortTelemetryUnsubscribed	The composition has stopped sending telemetry for each event through the input port.
VuoControlReplyOutputPortTelemetryUnsubscribed	The composition has stopped sending telemetry for each event through the output port.
VuoControlReplyEventTelemetrySubscribed	The composition has started sending telemetry for all events.
VuoControlReplyEventTelemetryUnsubscribed	The composition has stopped sending telemetry for all events.
VuoControlReplyAllTelemetrySubscribed	The composition has started sending all telemetry.
VuoControlReplyAllTelemetryUnsubscribed	The composition has stopped sending all telemetry.

Definition at line 249 of file VuoTelemetry.h.

VuoControlRequest

enum VuoControlRequest

Control Requests, sent to the composition.

Enumerator
VuoControlRequestCompositionStop	Request that the composition stop executing (without serialization). Includes data message-parts: int timeoutInSeconds; bool isBeingReplaced; bool isLastEverInProcess;
VuoControlRequestCompositionPause	Request that the composition pause execution (without serialization).
VuoControlRequestCompositionUnpause	Request that the composition unpause execution.
VuoControlRequestInputPortValueModify	Request that the input port be set to the given value (converted to the port's type). Includes data message-parts: char *compositionIdentifier; char *portIdentifier; char *valueAsString;
VuoControlRequestInputPortValueRetrieve	Request that the input port's value be looked up and returned. Includes data message-parts: bool shouldUseInterprocessSerialization; char *compositionIdentifier; char *portIdentifier;
VuoControlRequestOutputPortValueRetrieve	Request that the output port's value be looked up and returned. Includes data message-parts: bool shouldUseInterprocessSerialization; char *compositionIdentifier; char *portIdentifier;
VuoControlRequestInputPortSummaryRetrieve	Request that the input port's summary be looked up and returned. Includes data message-parts: char *compositionIdentifier; char *portIdentifier;
VuoControlRequestOutputPortSummaryRetrieve	Request that the output port's summary be looked up and returned. Includes data message-parts: char *compositionIdentifier; char *portIdentifier;
VuoControlRequestTriggerPortFireEvent	Request that an event be fired from the trigger port. Includes data message-parts: char *compositionIdentifier; char *portIdentifier;
VuoControlRequestPublishedInputPortNamesRetrieve	Request that the published input ports' names be looked up and returned.
VuoControlRequestPublishedOutputPortNamesRetrieve	Request that the published output ports' names be looked up and returned.
VuoControlRequestPublishedInputPortTypesRetrieve	Request that the published input ports' types be looked up and returned.
VuoControlRequestPublishedInputPortDetailsRetrieve	Request that the published input ports' details be looked up and returned.
VuoControlRequestPublishedOutputPortTypesRetrieve	Request that the published output ports' types be looked up and returned.
VuoControlRequestPublishedOutputPortDetailsRetrieve	Request that the published output ports' details be looked up and returned.
VuoControlRequestPublishedInputPortFireEvent	Request that an event be fired through the published input port. Includes data message-parts: int count; char *name0; char *name1; ...
VuoControlRequestPublishedInputPortValueModify	Request that published input ports be set to the given values (converted to the port's type). Includes data message-parts: char *port0Name; char *port0Value; char *port1Name; char *port1Value; ...
VuoControlRequestPublishedInputPortValueRetrieve	Request that the published input port's value be looked up and returned. Includes data message-parts: bool shouldUseInterprocessSerialization; char *name;
VuoControlRequestPublishedOutputPortValueRetrieve	Request that the published output port's value be looked up and returned. Includes data message-parts: bool shouldUseInterprocessSerialization; char *name;
VuoControlRequestSlowHeartbeat	Request that the composition slow its heartbeat telemetry (since the sender has established its telemetry connection and no longer wants the rapid stream of messages).
VuoControlRequestInputPortTelemetrySubscribe	Request that the composition start sending telemetry for each event through this input port. The telemetry includes a summary of the port's data. Includes data message-parts: char *compositionIdentifier; char *portIdentifier;
VuoControlRequestOutputPortTelemetrySubscribe	Request that the composition start sending telemetry for each event through this output port. The telemetry includes a summary of the port's data. Includes data message-parts: char *compositionIdentifier; char *portIdentifier;
VuoControlRequestInputPortTelemetryUnsubscribe	Request that the composition stop sending telemetry for each event through this input port. The telemetry includes a summary of the port's data. Includes data message-parts: char *compositionIdentifier; char *portIdentifier;
VuoControlRequestOutputPortTelemetryUnsubscribe	Request that the composition stop sending telemetry for each event through this output port. The telemetry includes a summary of the port's data. Includes data message-parts: char *compositionIdentifier; char *portIdentifier;
VuoControlRequestEventTelemetrySubscribe	Request that the composition start sending telemetry for all events. Includes data message-parts: char *compositionIdentifier;
VuoControlRequestEventTelemetryUnsubscribe	Request that the composition stop sending telemetry for all events. Includes data message-parts: char *compositionIdentifier;
VuoControlRequestAllTelemetrySubscribe	Request that the composition start sending all telemetry. Includes data message-parts: char *compositionIdentifier;
VuoControlRequestAllTelemetryUnsubscribe	Request that the composition stop sending all telemetry. Includes data message-parts: char *compositionIdentifier;

Definition at line 17 of file VuoTelemetry.h.

VuoLoaderControlReply

enum VuoLoaderControlReply

Control Replies, sent from the composition loader.

Enumerator
VuoLoaderControlReplyCompositionReplaced	The composition has been replaced with an updated version.

Definition at line 474 of file VuoTelemetry.h.

VuoLoaderControlRequest

enum VuoLoaderControlRequest

Control Requests, sent to the composition loader.

Enumerator
VuoLoaderControlRequestCompositionReplace	Request that the composition be replaced with an updated version. Includes data message-parts: char *dylibPath; int resouceDylibsAddedCount; char *resourceDylibAdded0; char *resourceDylibAdded1; ... int resourceDylibsRemovedCount; char *resourceDylibRemoved0; char *resourceDylibRemoved1; ... char *compositionDiff;

Definition at line 451 of file VuoTelemetry.h.

VuoTelemetry

enum VuoTelemetry

Types of published telemetry data.

Enumerator
VuoTelemetryStats	General information about the composition process, published every half-second. Includes data message-parts: unsigned long utime; unsigned long stime;
VuoTelemetryNodeExecutionStarted	Published just prior to calling each node's nodeEvent/nodeInstanceEvent function. Includes data message-parts: char *compositionIdentifier; char *nodeIdentifier;
VuoTelemetryNodeExecutionFinished	Published just after each node's nodeEvent/nodeInstanceEvent function returns. Includes data message-parts: char *compositionIdentifier; char *nodeIdentifier;
VuoTelemetryInputPortsUpdated	Published just after an input port receives an event and/or data. Includes data message-parts: char *compositionIdentifier0; char *portIdentifier0; bool receivedEvent0; bool receivedData0; char *portDataSummary0; char *compositionIdentifier1; char *portIdentifier1; bool receivedEvent1; bool receivedData1; char *portData1; char *portDataSummary1; ...
VuoTelemetryOutputPortsUpdated	Published just after an output port transmits/fires an event and/or data. Includes data message-parts: char *compositionIdentifier0; char *portIdentifier0; bool sentEvent0; bool sentData0; char *portDataSummary0; char *compositionIdentifier1; char *portIdentifier1; bool sentEvent1; bool sentData1; char *portData1; char *portDataSummary1; ...
VuoTelemetryPublishedOutputPortsUpdated	Published just after an event travels through a published output port. Includes data message-parts: char *portIdentifier0; bool sentData0; char *portDataSummary0; char *portIdentifier1; bool sentData1; char *portData1; char *portDataSummary1; ...
VuoTelemetryEventFinished	Published when the event most recently fired into the published inputs (and any events spun off from it) finishes propagating through the composition.
VuoTelemetryEventDropped	Published just after a trigger port drops an event. Includes data message-parts: char *compositionIdentifier; char *portIdentifier;
VuoTelemetryError	Published when an uncaught error occurs in the composition. Includes data message-parts: char *message;
VuoTelemetryStopRequested	Published when a node in the composition requests that the composition stop.

Definition at line 485 of file VuoTelemetry.h.

Function Documentation

vuoCopyStringFromMessage()

char* vuoCopyStringFromMessage

(

zmq_msg_t *

message

)

Copies the message data into a newly allocated string.

Assumes the message data includes a null terminator.

If the message is zero-length, returns NULL.

Definition at line 22 of file VuoTelemetry.c.

vuoInitMessageWithBool()

void vuoInitMessageWithBool	(	zmq_msg_t *	message,
		bool	value
	)

Copies the bool value into the message data.

Definition at line 55 of file VuoTelemetry.c.

vuoInitMessageWithInt()

void vuoInitMessageWithInt	(	zmq_msg_t *	message,
		int	value
	)

Copies the int value into the message data.

Definition at line 45 of file VuoTelemetry.c.

vuoInitMessageWithString()

void vuoInitMessageWithString	(	zmq_msg_t *	message,
		const char *	string
	)

Copies the string (including null terminator) into the message data.

Definition at line 35 of file VuoTelemetry.c.

vuoMemoryBarrier()

void vuoMemoryBarrier

(

void

)

"Individual ØMQ sockets are not thread safe except in the case where full memory barriers are issued when migrating a socket from one thread to another.

"

http://api.zeromq.org/2-2:zmq https://stackoverflow.com/questions/5841896/0mq-how-to-use-zeromq-in-a-threadsafe-manner https://b33p.net/kosada/node/4226

Definition at line 268 of file VuoTelemetry.c.

vuoReceiveAndCopyString()

char* vuoReceiveAndCopyString	(	void *	socket,
		char **	error
	)

Receives the next message on the socket and copies it into a newly allocated string.

Definition at line 76 of file VuoTelemetry.c.

vuoReceiveBool()

bool vuoReceiveBool	(	void *	socket,
		char **	error
	)

Receives the next message on the socket and copies it into a bool.

Definition at line 194 of file VuoTelemetry.c.

vuoReceiveInt()

int vuoReceiveInt	(	void *	socket,
		char **	error
	)

Receives the next message on the socket and copies it into an int.

Definition at line 184 of file VuoTelemetry.c.

vuoReceiveUnsignedInt64()

unsigned long vuoReceiveUnsignedInt64	(	void *	socket,
		char **	error
	)

Receives the next message on the socket and copies it into an unsigned long.

Definition at line 174 of file VuoTelemetry.c.

vuoSend()

void vuoSend	(	const char *	name,
		void *	socket,
		int	type,
		zmq_msg_t *	messages,
		unsigned int	messageCount,
		bool	isNonBlocking,
		char **	error
	)

Sends the multipart message messages on ZMQ socket socket.

name is just used for printing error messages.

Definition at line 205 of file VuoTelemetry.c.

VuoTelemetry_hasMoreToReceive()

bool VuoTelemetry_hasMoreToReceive

(

void *

socket

)

Returns true if there are more messages to receive on the socket currently.

Definition at line 65 of file VuoTelemetry.c.