Overview

Singleton to handle socket communications.

dotsTheMessenger uses an instance of dotsAllSocketObjects to do communications between Matlab instances (or looped-back communictaions to the same Matlab instance). Both Matlab instances are expected to be using dotsTheMessenger.

dotsTheMessenger improves on basic socket messaging in three ways:

It isolates the caller from platform-specific details.
It reduces message shuffling and collisions by waiting for message acknowledgement codes.
It reduces message loss by re-sending unacknowledged messages.

Inheritance diagram for dotsTheMessenger:

[legend]

Properties and Events
Property	socketsInfo
	topsGroupedList of info about opened sockets

Property	clockFunction
	any function that returns the current time as a number

Property	receiveTimeout
	time in seconds to wait to receive a message More...

Property	ackTimeout
	time in seconds to wait for acknowledgement of a sent message More...

Property	sendRetries
	number of times to resend unacknowledged messages More...

Property	socketClassName
	class name of a dotsAllSocketObjects subclass More...

Property	defaultClientIP
	string IP address that could be used for a client-side socket More...

Property	defaultServerIP
	string IP address that could be used for a server-side socket More...

Property	defaultClientPort
	port number that could be used for a client-side socket More...

Property	defaultServerPort
	port number that could be used for a server-side socket More...

Property	notAcknowledgedStatus = -111
	status code indicating a send message was never acknowqledged

Property	notReceivedStatus = -222
	status code indicating no message was received

Properties and Events inherited from dotsAllSingletonObjects
null	obj = theObject(varargin)
	Return the current class instance from the private constructor.

null	g = gui()
	Launch a grapical interface for the current instance.

Protected Properties
Property	socketObject
	an instance of socketClassName More...

Property	sentPrefix
	1-byte prefix for the previous sent message

Property	receivedPrefix
	1-byte prefixs for the previous received message at each socket

Property	prefixModulus = 255
	roll-over value for 1-byte message prefixes More...

Methods
	initialize (self)
	Restore the current instance to a fresh state.

status ackTime	sendMessageFromSocket (self, msg, sock, ackTimeout, sendRetries)
	Send a message from the given socket. More...

msg status	receiveMessageAtSocket (self, sock, receiveTimeout)
	Receive any message that arrived at the given socket. More...

sock	openSocket (self, localIP, localPort, remoteIP, remotePort)
	Open a socket for communicating via Ethernet and UDP. More...

status	closeSocket (self, sock)
	Close a socket. More...

status	flushSocket (self, sock)
	Clear any data messages and inernal accounting for a socket. More...

sock	openDefaultServerSocket (self)
	Open a socket with some default "server" properties.

sock	openDefaultClientSocket (self)
	Open a socket with some default "client" properties.

Methods inherited from dotsAllSingletonObjects
null	reset (varargin)
	Restore a fresh state without deleting the current instance.

null	initialize (self)
	Restore a fresh state without deleting the current object, used by constructor and reset(). More...

	initializeLists (self, listNames)
	Create or refresh topsGroupedList instances.

	set (self, varargin)
	Set multiple properties.

Protected Methods
	setSocketReceivedPrefix (self, sock, prefix)
	Keep track of the last message prefix received at a socket.

prefix	getSocketReceivedPrefix (self, sock)
	Get the last message prefix received at a socket.

Static Methods
static obj	theObject (varargin)
	Access the current instance.

static	reset (varargin)
	Restore the current instance to a fresh state.

static g	gui ()
	Launch a graphical interface for messenger properties.

static description	describeAddress (IP, port)
	Describe an IP address and socket with one string. More...

Private Methods
self	dotsTheMessenger (varargin)
	Constructor is private. More...

Constructor

◆ dotsTheMessenger()

self dotsTheMessenger ( varargin )

private

Constructor is private.

dotsTheMessenger is a singleton object, so its constructor is not accessible. Use dotsTheMessenger.theObject() to access the current instance.

Methods

◆ describeAddress()

static description describeAddress	(	IP	,
		port
	)

static

Describe an IP address and socket with one string.

Parameters

IP	string IP address like '127.0.0.1'
numeric	port number

Concatnates IP and port into a single descriptive string, with a colon delimiter between IP and port.

◆ sendMessageFromSocket()

status ackTime sendMessageFromSocket	(	self	,
		msg	,
		sock	,
		ackTimeout	,
		sendRetries
	)

Send a message from the given socket.

Parameters

msg	variable to send as a message
sock	numeric identifier for a socket, as returned by openSocket()
ackTimeout	seconds to wait for message acknowledgement
sendRetries	number of times to resend if unacknowledged

Converts msg to an array of bytes and sends the bytes from sock, to whatever address and port were specified in the call to openSocket(). msg must be one of the following variable types:

double
char
logical
cell
struct
function_handle

If msg is a cell or struct, it must compose elements of these types. Nested cells and structs are supported. Any msg or element that is an array, including cell arrays, should be at most two-dimensional (mxn). struct arrays should be one-dimenstional (1xn) but may have any number of fields.

If ackTimeout is non-negative, waits for the receiver to send back an acknowledgement of msg. If no acknowledgement arrives within ackTimeout seconds, re-sends msg. Waits and re-sends up to sendRetries times. If ackTimeout is negative, does not wait for any ancknowledgement. ackTimeout and sendRetries may be omitted, in which case the ackTimeout and sendRetries properties are used.

Returns a status code. May return notAcknowledgedStatus if the message was sent but never acknowledged. Other negative status indicates an error and that msg may not have been sent.

Also returns as a second output the amount of time spent waiting for message acknowledgement, whether or not it was ever acknowledged, in units of clockFunction.

◆ receiveMessageAtSocket()

msg status receiveMessageAtSocket	(	self	,
		sock	,
		receiveTimeout
	)

Receive any message that arrived at the given socket.

Parameters

sock	a numeric identifier for a socket, as returned by openSocket()
receiveTimeout	seconds to wait for a message to arrive

Waits up to receiveTimeout seconds for a message to arrive at the given sock. If a message arrives (or had already arrived), returns the message variable. Otherwise, returns []. receiveTimeout may be omitted, in which case the receiveTimeout property is used.

Also returns a status code as a second output. May return notReceivedStatus if no message was available. May return other negative status codes if there was an error reading from sock or decoding message bytes into a variable.

◆ openSocket()

sock openSocket	(	self	,
		localIP	,
		localPort	,
		remoteIP	,
		remotePort
	)

Open a socket for communicating via Ethernet and UDP.

Parameters

localIP	string IP address for this machine
localPort	integer port number to go with the local IP address
remoteIP	string IP address for this or another machine
remotePort	integer port number to go with the remote IP address

Opens a network socket connection between ports at two IP addresses. The IP addresses may be the same or different. localIP should be the address of this machine, and may be the "loopback" address, '127.0.0.1'. The port numbers must be different.

Returns a numeric identifier for the new UDP connection, suitable for use with sendMessageFromSocket(), receiveMessageAtSocket(), and waitForMessageAtSocket();

Stores information about each opened socket in socketsInfo

◆ closeSocket()

status closeSocket	(	self	,
		sock
	)

Close a socket.

Parameters

sock	a numeric identifier for a socket, as returned by openSocket()

Frees the resources associeted with sock.

Returns a status code. A negative status code probably indicates that sock is not a valid socket identifier.

Searches socketsInfo for sock and removes all instances it finds.

◆ flushSocket()

status flushSocket	(	self	,
		sock
	)

Clear any data messages and inernal accounting for a socket.

Parameters

sock	a numeric identifier for a socket, as returned by openSocket()

Reads from sock until it has no queued messages and resets dotsTheMessenger's internal accounting for sock, but does not close the sock.

Returns a status code. A negative status code probably indicates that sock is not a valid socket identifier.

Properties and Events

◆ receiveTimeout

Property receiveTimeout

time in seconds to wait to receive a message

Automatically gets the machine-specific default from dotsTheMachineConfiguration.

◆ ackTimeout

Property ackTimeout

time in seconds to wait for acknowledgement of a sent message

Automatically gets the machine-specific default from dotsTheMachineConfiguration.

◆ sendRetries

Property sendRetries

number of times to resend unacknowledged messages

Automatically gets the machine-specific default from dotsTheMachineConfiguration.

◆ socketClassName

Property socketClassName

class name of a dotsAllSocketObjects subclass

Instantiates an instance of socketClassName to use for opening and closing sockets, and sending and receiving messages. The named dotsAllSocketObjects subclass should be appropriate for the local hardware, operating system, etc.

Automatically gets the machine-specific default from dotsTheMachineConfiguration.

◆ defaultClientIP

Property defaultClientIP

string IP address that could be used for a client-side socket

Automatically gets the machine-specific default from dotsTheMachineConfiguration.

◆ defaultServerIP

Property defaultServerIP

string IP address that could be used for a server-side socket

Automatically gets the machine-specific default from dotsTheMachineConfiguration.

◆ defaultClientPort

Property defaultClientPort

port number that could be used for a client-side socket

Automatically gets the machine-specific default from dotsTheMachineConfiguration.

◆ defaultServerPort

Property defaultServerPort

port number that could be used for a server-side socket

Automatically gets the machine-specific default from dotsTheMachineConfiguration.

◆ socketObject

Property socketObject

protected

an instance of socketClassName

The instance of socketClassName that dotsTheMessenger is using for opening and closing sockets, and sending and receiving messages.

◆ prefixModulus

Property prefixModulus = 255

protected

roll-over value for 1-byte message prefixes

prefixModulus wants to be 256, but because of Matlab clips integers rather than rolling them over, 255 is easier to work with. Consider that 255+1 equals 255, not 0.

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

dotsTheMessenger.m

Overview

Properties and Events

Protected Properties

Methods

Protected Methods

Static Methods

Private Methods

Constructor

◆ dotsTheMessenger()

Methods

◆ describeAddress()

◆ sendMessageFromSocket()

◆ receiveMessageAtSocket()

◆ openSocket()

◆ closeSocket()

◆ flushSocket()

Properties and Events

◆ receiveTimeout

◆ ackTimeout

◆ sendRetries

◆ socketClassName

◆ defaultClientIP

◆ defaultServerIP

◆ defaultClientPort

◆ defaultServerPort

◆ socketObject

◆ prefixModulus