zmqConnection Class Reference

Inheritance diagram for zmqConnection:

Public Member Functions
function	zmqConnection (in varargin)
function	open (in me)
	Class constructor for zmqConnection.
function	poll (in me, in events, in time)
	Opens the ØMQ socket connection.
function	sendCommand (in me, in command, in data, in getReply)
	poll socket to identify whether we can send ('out') or receive ('in')
function	receiveCommand (in me, in sendReply)
	Sends a command and optional data, then waits for a reply.
function	flush (in me)
	Receives a command and associated data, optionally sending an 'ok' reply.
function	get (in me, in option)
	Flushes the receive buffer of the socket.
function	set (in me, in option, in value)
	Gets the value of a ØMQ socket option.
function	send (in me, in data)
	Sets the value of a ØMQ socket option.
function	receive (in me)
	Sends raw data over the socket.
function	close (in me, in keepContext)
	Receives raw data from the socket.
function	delete (in me)
	Closes the ØMQ socket and optionally the context.
function get	endpoint (in me)
	Class destructor.
function	sendObject (in me, in command, in data, in useJSON, in options)
	Gets the full endpoint string for the connection.
function	receiveObject (in me, in useJSON, in options)
	(Private) Sends a command string and optional serialized MATLAB data.
Public Member Functions inherited from optickaCore
function	optickaCore (in varargin)
	Class constructor.
function get	fullName (in me)
function	getALF (in me, in subject, in lab, in create)
	get the ALF path
function	makeReport (in me, in rpt)
	Generate a detailed report for the opticka object.
function	findAttributes (in me, in attrName, in attrValue)
function	findAttributesandType (in me, in attrName, in attrValue, in type)
	find properties of object with specific attributes, for example all properties whose GetAcccess attribute is public and type is logical.
function	findPropertyDefault (in me, in propName)
	Return the declared default value for a class property.
function	clone (in me)
	Use this syntax to make a deep copy of the object, i.e. OBJ_OUT has the same field values, but will not behave as a handle-copy of me anymore.
function	checkSuperclasses (in List)
function	editProperties (in me, in properties)
	method to modify a set of properties
function	setProp (in me, in property, in value)
	method to fast change a particular value. This is useful for use in anonymous functions, like in the state machine.
function	initialiseSaveFile (in me, in varargin)
	just get date fragment for backwards compatibility
function	checkPaths (in me)
	checks the paths are valid

Public Attributes
Property	type
	ØMQ connection type, e.g. 'REQ', 'REP', 'PUB', 'SUB', 'PUSH', 'PULL'.
Property	transport
	transport for the socket, tcp | ipc | inproc
Property	address
	the address to open, use * for a server to bind to all interfaces
Property	port
	the port to open
Property	frameSize
	default size of chunk to read/write for tcp
Property	readTimeOut
	default read timeout in ms, -1 is blocking
Property	writeTimeOut
	default write timeout in ms, -1 is blocking
Property	verbose
	do we log to the command window?
Property	alwaysPoll
	for sendCommand and receiveCommand use zmq.core.poll?
Property	endpoint
	connection endpoint
Public Attributes inherited from optickaCore
Property	name
	object name
Property	comment
	comment
Property	verbose
	verbose logging, subclasses must assign this. This is normally logical true/false
Property	optickaVersion
	version number
Property	dateStamp
	clock() dateStamp set on construction
Property	uuid
	universal ID
Property	paths
	storage of various paths
Property	fullName
	The fullName is the object name combined with its uuid and class name.

Additional Inherited Members
Static Public Member Functions inherited from optickaCore
static function	initialiseGlobals (in doReset, in doOpen)
static function	makeArgs (in args)
	Converts cell args to structure array.
static function	addDefaults (in args, in defs)
	regularises and adds default options to arg input
static function	hasKey (in in, in key)
	check if a struct / object has a propery / field
static function	getKeys (in device)
	PTB Get key presses, stops key bouncing.
Protected Member Functions inherited from optickaCore
function	parseArgs (in me, in args, in allowedProperties)
	Sets properties from a structure or normal arguments pairs, ignores invalid or non-allowed properties.
function	addArgs (in me, in args)
function	setPaths (in me)
	Sets properties from a structure or normal arguments pairs, ignores invalid or non-allowed properties.
function	getFonts (in me)
	set paths for object
function	toStructure (in me)
	Converts properties to a structure.
function	getType (in me, in in)
function	logOutput (in me, in in, in message, in override)
	Give a metaproperty return the likely property class.
function	salutation (in me, in varargin)
	Prints messages dependent on verbosity.
Protected Attributes inherited from optickaCore
Property	cloning
	are we cloning this from another object
Property	mversion
	Matlab version number, this is transient so it is not saved.
Property	sansFont
	sans font
Property	monoFont
	monoFont
Property	className
	class name
Property	savePrefix
	save prefix generated from clock time
Property	fullName_
	cached full name

Constructor & Destructor Documentation

zmqConnection()

function zmqConnection::zmqConnection

(

in

varargin

)

Member Function Documentation

close()

function zmqConnection::close	(	in	me,
		in	keepContext
	)

Receives raw data from the socket.

Calls zmq.Socket.recv_multipart to receive data. If the result is a single-element cell array, it extracts the content.

Returns

data The received data, typically as a uint8 array or potentially a cell array for true multipart messages. Empty on failure or timeout.

status 0 on success (implied, not explicitly returned on success), -1 on failure (e.g., timeout).

Note

Updates sendState and recState. Logs errors to the console.

delete()

function zmqConnection::delete

(

in

me

)

Closes the ØMQ socket and optionally the context.

Closes the underlying zmq.Socket if it's open. If keepContext is false (default), it also closes the zmq.Context. Sets the isOpen flag to false.

Parameters

keepContext

(Optional) Logical flag. If true, the ØMQ context is kept open; otherwise (default), the context is also closed. Defaults to false.

Note

Uses try...end blocks to suppress errors during closure.

endpoint()

function get zmqConnection::endpoint

(

in

me

)

Class destructor.

Ensures the socket and context are closed by calling close(me, false) when the object is destroyed.

flush()

function zmqConnection::flush

(

in

me

)

Receives a command and associated data, optionally sending an 'ok' reply.

Calls receiveObject to get the command string and any serialized data. If sendReply is true (default) and a command was successfully received, it sends back an 'ok' command using sendObject.

Parameters

sendReply

(Optional) Logical flag. If true (default), sends an 'ok' reply upon successful receipt of a command. If false, no reply is sent by this function. Defaults to true.

Returns

command The received command string. Empty if receive failed or timed out.

data The deserialized MATLAB data received with the command. Empty if no data part or on error.

Note

Updates sendState and recState properties. Logs received command/data if verbose.

get()

function zmqConnection::get	(	in	me,
		in	option
	)

Flushes the receive buffer of the socket.

Temporarily sets the receive timeout (RCVTIMEO) to 0 (non-blocking) and enters a loop calling receive until it returns a status of -1 (indicating no more messages or an error). It then restores the original readTimeOut. This is useful for discarding any pending messages in the socket's incoming queue.

open()

function zmqConnection::open

(

in

me

)

Class constructor for zmqConnection.

Initializes a zmqConnection object, setting up default properties and parsing any provided arguments using the optickaCore superclass constructor and argument parsing.

Parameters

varargin

Optional name-value pairs to override default properties. Allowed properties are defined in me.allowedProperties.

Returns

me An instance of the zmqConnection class.

poll()

function zmqConnection::poll	(	in	me,
		in	events,
		in	time
	)

Opens the ØMQ socket connection.

Creates the ØMQ context if it doesn't exist, creates the socket based on the type property, sets socket options like RCVTIMEO, SNDTIMEO, and LINGER, and then either binds (for server types like REP, PUB, PUSH) or connects (for client types) to the specified endpoint. Sets the isOpen flag to true.

Note

Does nothing if the connection isOpen is already true.

receive()

function zmqConnection::receive

(

in

me

)

Sends raw data over the socket.

Determines the type of data and calls the appropriate zmq.Socket send method (send_string for char/string, send for uint8). If the data type is different, it attempts to use the private sendObject method (which might not be intended for raw data).

Parameters

data	The data to send. Can be a character array, string, or uint8 array.

Returns

status 0 on success, -1 on failure (e.g., timeout, incorrect socket state).

Note

Updates sendState and recState. Logs errors to the console.

receiveCommand()

function zmqConnection::receiveCommand	(	in	me,
		in	sendReply
	)

Sends a command and optional data, then waits for a reply.

Primarily for REQ/REP patterns. Uses sendObject to send the command string and serialized data. If successful, it then calls receiveObject to wait for and receive the reply command and data.

Parameters

command	The command string to send.
data	(Optional) MATLAB data to serialize and send along with the command. Defaults to empty.

Returns

rep The reply command string received from the peer.

dataOut The deserialized MATLAB data received in the reply.

status 0 on success (send and receive completed), -1 on failure (send or receive failed).

Note

Updates sendState and recState properties. Logs reply if verbose.

receiveObject()

function zmqConnection::receiveObject	(	in	me,
		in	useJSON,
		in	options
	)

(Private) Sends a command string and optional serialized MATLAB data.

This is the core sending method used by public methods like sendCommand and receiveCommand (for replies). It checks if the socket is open, validates the command is a string, serializes the data using getByteStreamFromArray (if provided), and sends the command and data as a two-part message using zmq.Socket.send with the 'sndmore' flag if both parts exist. Handles sending only command, only data, or an empty message if both are empty.

Parameters

command	The command string to send. Must be char or string.
data	(Optional) MATLAB data to serialize and send.
useJSON	(optional) wrap command and data with JSON
options	(Optional) Cell array of additional flags for the final send call (e.g., {'ZMQ_DONTWAIT'}).

Returns

status 0 on success, -1 on failure.

nbytes The total number of bytes sent across all parts.

msg An error message string if status is -1.

Note

This is a private method. Throws errors for invalid input or unopened socket.

send()

function zmqConnection::send	(	in	me,
		in	data
	)

Sets the value of a ØMQ socket option.

A wrapper around the zmq.Socket.set method.

Parameters

option	The name of the socket option to set (e.g., 'RCVTIMEO', 'LINGER'). Case-insensitive, 'ZMQ_' prefix is optional.
value	The value to assign to the socket option.

Returns

status 0 on success, non-zero on failure.

Warning

Issues warnings if option or value are not provided.

sendCommand()

function zmqConnection::sendCommand	(	in	me,
		in	command,
		in	data,
		in	getReply
	)

poll socket to identify whether we can send ('out') or receive ('in')

Parameters

events	string 'in' 'out' or 'both'
time	in ms, 0 = no wait, -1 = block until response

sendObject()

function zmqConnection::sendObject	(	in	me,
		in	command,
		in	data,
		in	useJSON,
		in	options
	)

Gets the full endpoint string for the connection.

Constructs the endpoint string (e.g., 'tcp://localhost:5555') based on the transport, address, and port properties.

Returns

endpoint The formatted endpoint string.

set()

function zmqConnection::set	(	in	me,
		in	option,
		in	value
	)

Gets the value of a ØMQ socket option.

A wrapper around the zmq.Socket.get method.

Parameters

option

The name of the socket option to retrieve (e.g., 'RCVTIMEO', 'SNDHWM'). Case-insensitive, 'ZMQ_' prefix is optional.

Returns

value The current value of the specified socket option.

Warning

Issues a warning if option is not provided.

Member Data Documentation

address

Property zmqConnection::address

the address to open, use * for a server to bind to all interfaces

alwaysPoll

Property zmqConnection::alwaysPoll

for sendCommand and receiveCommand use zmq.core.poll?

endpoint

Property zmqConnection::endpoint

connection endpoint

frameSize

Property zmqConnection::frameSize

default size of chunk to read/write for tcp

port

Property zmqConnection::port

the port to open

readTimeOut

Property zmqConnection::readTimeOut

default read timeout in ms, -1 is blocking

transport

Property zmqConnection::transport

transport for the socket, tcp | ipc | inproc

type

Property zmqConnection::type

ØMQ connection type, e.g. 'REQ', 'REP', 'PUB', 'SUB', 'PUSH', 'PULL'.

zmqConnection is a class to handle ØMQ connections for opticka class communication. We use matlab-zmq (a basic libzmq binding), and a REQ-REP pattern for main communication.

verbose

Property zmqConnection::verbose

do we log to the command window?

writeTimeOut

Property zmqConnection::writeTimeOut

default write timeout in ms, -1 is blocking

---

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

• communication/zmqConnection.m