Overview

Aggregate objects into an ensemble for remote batch opertaions.

dotsClientEnsemble is intended as a drop-in substitue for topsEnsemble. Instead of interacting with objects locally, dotsClientEnsemble acts as a proxy for an ensemble object which it creates in another Matlab instance, via dotsEnsembleUtilities and dotsEnsembleServer.

dotsClientEnsemble defines some static methods which can be invoked without creating an instance, for example to issue a reset command to a dotsEnsembleServer.

Inheritance diagram for dotsClientEnsemble:

[legend]

Properties and Events
Property	timeout = 5.0
	seconds to allow for network communications

Property	isSynchronized = false
	whether to use strong (true) or weak (false) synchrony

Properties and Events inherited from topsCallList
	calls
	struct array with fevalable cell arrays to call as a batch

Property	alwaysRunning = true
	true or false, whether to run indefinitely

Property	invertOrder = false
	true or false, invert order of calls

Properties and Events inherited from topsConcurrent
Property	runBrieflyString = 'runBriefly'
	string used for topsDataLog entry just before runBriefly()

Properties and Events inherited from topsRunnable
Property	startFevalable = {}
	optional fevalable cell array to invoke just before running

Property	finishFevalable = {}
	optional fevalable cell array to invoke just after running

Property	isRunning = false
	true or false, whether this object is currently busy running

Property	caller
	topsRunnable that invoked run() on this object, or empty

Property	startString = 'start'
	string used for topsDataLog entry just before run()

Property	finishString = 'finish'
	string used for topsDataLog entry just after run()

Properties and Events inherited from topsFoundation
Property	name = ''
	a string name to indentify the object

Property	clockFunction =@topsClock
	clock function, to standardize

Protected Properties
Property	clientIP
	IP address of the Snow Dots client.

Property	clientPort
	network port of the Snow Dots client

Property	serverIP
	IP address of the dotsEnsembleServer.

Property	serverPort
	network port of the dotsEnsembleServer

Property	socket
	socket identifier for communictions

Property	isConnected = false
	whether or not this ensemble connected to its server

Property	txnStatus
	status of the most recent transaction

Property	txnData
	data from the most recent transaction

Property	isProfiling = false
	whether or not to invoke the Matlab profiler during transactions

Property	profilingInfo
	data returned from the Matlab profiler

Protected Properties inherited from topsEnsemble
Property	objects = {}
	array of objects in the ensemble More...

Property	objectNames = {}
	optional array of object names, for convenience

Methods
self	dotsClientEnsemble (name, clientIP, clientPort, serverIP, serverPort)
	Constuct with network addresses optional. More...

	setAddresses (self, clientIP, clientPort, serverIP, serverPort)
	Use the given network addresses for messages.

	startProfiling (self, varargin)
	Start invoking the Matlab profiler during transactions. More...

	stopProfiling (self)
	Stop invoking the Matlab profiler during transactions. More...

	viewProfiling (self)
	View Matlab profiler "info" results for transactions. More...

	start (self)
	Enable calls to the call list. More...

	finish (self)
	Disable calls to the call list. More...

	run (self, duration)
	Start running on the server side, until finish(). More...

	runBriefly (self)
	Invoke active calls on the server side, not the client side. More...

index	addCall (self, varargin)
	Add an "fevalable" to the call list. More...

	setActiveByName (self, varargin)
	Toggle whether a call is active. More...

result	callByName (self, varargin)
	Invoke a call now, whether or not it's active. More...

index	addObject (self, varargin)
	Add one object to the ensemble. More...

object	removeObject (self, varargin)
	Remove one or more objects from the ensemble. More...

	assignObject (self, varargin)
	Assign one object to a property of one other object. More...

	passObject (self, varargin)
	Pass one object to a method of another object. More...

	setObjectProperty (self, varargin)
	Set a property for one or more objects. More...

value	getObjectProperty (self, varargin)
	Get a property value for one or more objects. More...

result	callObjectMethod (self, varargin)
	Call a method for one or more objects. More...

Methods inherited from topsEnsemble
self	topsEnsemble (varargin)
	Constuct with name optional. More...

fig	gui (self)
	Open a GUI to view object details. More...

index	addObject (self, object, index)
	Add one object to the ensemble. More...

object	removeObject (self, index)
	Remove one or more objects from the ensemble. More...

object	getObject (self, index)
	Get one or more objects in the ensemble. More...

isMember index	containsObject (self, object)
	Is the given object a member of the ensemble? More...

	assignObject (self, innerIndex, outerIndex, varargin)
	Assign one object to a property of one other object. More...

	passObject (self, innerIndex, outerIndex, method, args, argIndex)
	Pass one object to a method of another object. More...

	setObjectProperty (self, property, value, index)
	Set a property for one or more objects. More...

result	callObjectMethod (self, method, args, index, isCell)
	Call a method for one or more objects. More...

index	automateObjectMethod (self, name, method, args, index, isCell, isActive)

Methods inherited from topsCallList
self	topsCallList (varargin)
	Constuct with name optional. More...

fig	gui (self)
	Open a GUI to view object details. More...

index	addCall (self, fevalable, name)
	Add an "fevalable" to the call list. More...

	setActiveByName (self, isActive, name)
	Toggle whether a call is active. More...

result	callByName (self, name, isActive)
	Invoke a call now, whether or not it's active. More...

	runBriefly (self)
	Invoke active calls in a batch.

Methods inherited from topsConcurrent
self	topsConcurrent (varargin)
	Constuct with name optional. More...

	run (self, duration)
	Do flow control. More...

	runBriefly (self)
	Do a little flow control and return as soon as possible. More...

Methods inherited from topsRunnable
self	topsRunnable (varargin)
	Constuct with name optional. More...

	run (self)
	Do flow control. More...

g	gui (self)
	Show heirarchy of topsRunnable[Composite] objects.

	start (self)
	Log action and prepare to do flow control. More...

	finish (self)
	Log, action and finish doing flow control. More...

	logAction (self, actionName, actionData)
	Log an event of interest with topsDataLog. More...

	logFeval (self, fevalName, fevalable)
	Log a function call with topsDataLog. More...

Methods inherited from topsFoundation
self	topsFoundation (name)
	Constuct with name optional. More...

fig	gui (self)
	Open a GUI to view object details. More...

p	guiPanel (self, varargin)
	Make a topsDetailPanel with details about this object. More...

name string name given to this automated method call

Prepare to repeatedly call a method, for one or more objects.

Parameters

method	function_handle of an ensemble object method
args	optional cell array of arguments to pass to method
index	optional ensemble object index or indexes
isCell	optional whether to pass objects in one cell array
isActive	whether the named method call should be active

Redefines this topsEnsemble method to work with a remote ensemble server.

index automateObjectMethod (self, varargin)

openSocket (self)

Get a socket for messages.

status txn requestServerCounterpart (self)

Tell the server to create a mirror of this ensemble.

status updateServerObject (self, index)

Update the indexed object, from client to server. More...

static status txn resetServer (timeout, clientIP, clientPort, serverIP, serverPort)

Tell an ensemble server to reset. More...

static status txn doSynchronousTransaction (txn, socket, timeout, isProfiling)

Block while doing a transaction with an ensemble server. More...

Additional Inherited Members
Static Methods inherited from topsEnsemble
static ensemble	makeEnsemble (name, objects)
	Convenient utility for combining a bunch of objects into an ensemble. More...

Static Methods inherited from topsCallList
static fevalable	makeFevalable (invertOrder)
	Utility to make a call list as an fevalable. More...

Static Methods inherited from topsFoundation
static c index	cellAdd (c, item, index)
	Add an item to a cell array. More...

static selector	cellContains (c, item)
	Does a cell array conatin an item? More...

static c	cellRemoveItem (c, item)
	Remove an item from a cell array. More...

static c	cellRemoveElement (c, index)
	Remove indexed elements from a cell array. More...

static index selector	findStructName (s, name)
	Where is the given name in the given struct array? More...

Constructor

◆ dotsClientEnsemble()

self dotsClientEnsemble	(	name	,
		clientIP	,
		clientPort	,
		serverIP	,
		serverPort
	)

Constuct with network addresses optional.

Parameters

name	unique name for this object
clientIP	string IP address of the Snow Dots client
clientPort	network port number of the Snow Dots client
serverIP	string IP address of the ensemble server
serverPort	netowrk port number of the ensemble server

name should be a unique name for this ensemble. If name is provided, assigns name to this object.

If clientIP, clientPort, serverIP, and serverPort are provided, attempts to connect to a server using the given addresses. Otherwise, uses default provided by dotsTheMessenger.

Methods

◆ startProfiling()

startProfiling	(	self	,
		varargin
	)

Start invoking the Matlab profiler during transactions.

Parameters

varargin optional configuraiton arguments to pass to profile()

startProfiling() clears any old results from the Matlab profiler and sets isProfiling to true. If provided, varargin is passed to the built in profile() for configuration.

While isProfiling is true, this client ensemble will invoke the Matalb profiler and append data specific to remote transactions.

◆ stopProfiling()

stopProfiling ( self )

Stop invoking the Matlab profiler during transactions.

stopProfiling() sets isProfiling to false and stops invoking the Matlab profiler during remote transactions. Also saves the profiler "info" to profilingInfo.

◆ viewProfiling()

viewProfiling ( self )

View Matlab profiler "info" results for transactions.

viewProfiling() saves any Matlab profiler "info" to profilingInfo and invokes the built-in profview() for viewing the info.

◆ start()

start ( self )

Enable calls to the call list.

Redefines this topsRunnable list method to work with a remote ensemble server.

◆ finish()

finish ( self )

Disable calls to the call list.

Redefines this topsRunnable method to work with a remote ensemble server.

◆ run()

run	(	self	,
		duration
	)

Start running on the server side, until finish().

Parameters

duration how long in seconds to keep running

Redefines this topsConcurrent method to start running on the server side.

By default, invokes start() on the server side to enable server-side function calls, then returns. Server-side function calls will continue until finish() is called.

If duration is provided, invokes start() on the server side to enable server-side function calls. Then blocks for duration sectonds. Once duration has elapsed, invokes finish() on the server side to disable server-side function calls, and returns.

◆ runBriefly()

runBriefly ( self )

Invoke active calls on the server side, not the client side.

Redefines this topsConcurrent method to do nothing on the client side.

◆ addCall()

index addCall	(	self	,
		varargin
	)

Add an "fevalable" to the call list.

Parameters

fevalable	a cell array with contents to pass to feval()
name	unique name to assign to fevalable

Redefines this topsCallList method to work with a remote ensemble server. fevalable should contain primitives, not objects. The function must be defined and on the path, on the server side.

◆ setActiveByName()

setActiveByName	(	self	,
		varargin
	)

Toggle whether a call is active.

Parameters

name	given to an fevalable during addCall()
isActive	true or false, whether to invoke the named fevalable during runBriefly()

Redefines this topsCallList method to work with a remote ensemble server.

◆ callByName()

result callByName	(	self	,
		varargin
	)

Invoke a call now, whether or not it's active.

Parameters

name	given to an fevalable during addCall()
isActive	whether to activate or un-activate the call at the same time

Redefines this topsCallList method to work with a remote ensemble server.

◆ addObject()

index addObject	(	self	,
		varargin
	)

Add one object to the ensemble.

Parameters

object	any object to add to the ensemble
index	optional index where to insert the object

Redefines this topsEnsemble method to work with a remote ensemble server.

◆ removeObject()

object removeObject	(	self	,
		varargin
	)

Remove one or more objects from the ensemble.

Parameters

index ensemble object index or indexes

Redefines this topsEnsemble method to work with a remote ensemble server.

◆ assignObject()

assignObject	(	self	,
		varargin
	)

Assign one object to a property of one other object.

Parameters

innerIndex	ensemble index of the object to be assigned
outerIndex	ensemble index of the object that will receive
varargin	asignment specification pased to substruct()

Redefines this topsEnsemble method to work with a remote ensemble server.

◆ passObject()

passObject	(	self	,
		varargin
	)

Pass one object to a method of another object.

Parameters

innerIndex	ensemble index of the object to pass
outerIndex	ensemble index of the receiving object
method	function_handle of a receiving object method
args	optional cell array of arguments to pass to method
argIndex	optional index into args of the object to pass

Redefines this topsEnsemble method to work with a remote ensemble server.

◆ setObjectProperty()

setObjectProperty	(	self	,
		varargin
	)

Set a property for one or more objects.

Parameters

property	string name of an ensemble object property
value	one value to assign to property
index	optional ensemble object index or indexes

Redefines this topsEnsemble method to work with a remote ensemble server.

◆ getObjectProperty()

value getObjectProperty	(	self	,
		varargin
	)

Get a property value for one or more objects.

Parameters

property	string name of an ensemble object property
index	optional ensemble object index or indexes

Redefines this topsEnsemble method to work with a remote ensemble server.

◆ callObjectMethod()

result callObjectMethod	(	self	,
		varargin
	)

Call a method for one or more objects.

Parameters

method	function_handle of an ensemble object method
args	optional cell array of arguments to pass to method
index	optional ensemble object index or indexes
isCell	optional whether to pass objects in one cell array

Redefines this topsEnsemble method to work with a remote ensemble server.

◆ updateServerObject()

status updateServerObject	(	self	,
		index
	)

protected

Update the indexed object, from client to server.

Parameters

index ensemble object index

Iterates the public properties of the indexed object and sends them one at a time to the server side. If any transaction fails, returns immediately with the failure status. Check txnStatus and txnData for details of the bad transaction.

◆ resetServer()

static status txn resetServer	(	timeout	,
		clientIP	,
		clientPort	,
		serverIP	,
		serverPort
	)

static

Tell an ensemble server to reset.

Parameters

timeout	time in seconds to keep running
clientIP	string IP address of the Snow Dots client
clientPort	network port number of the Snow Dots client
serverIP	string IP address of the ensemble server
serverPort	netowrk port number of the ensemble server

Commands a remote dotsEnsembleServer to reset. If clientIP, clientPort, serverIP, and serverPort are provided, attempts to connect to the server using the given addresses. Otherwise, uses default addresses provided by dotsTheMessenger. @deatils If timeout is provided, waits for that many seconds for the server to report that it's done resetting. Otherwise uses the default timeout from dotsTheMessenger. If the sever never reports, returns a negative status.

Also returns as a second output a struct with details about the remote transaction.

◆ doSynchronousTransaction()

static status txn doSynchronousTransaction	(	txn	,
		socket	,
		timeout	,
		isProfiling
	)

static

Block while doing a transaction with an ensemble server.

Parameters

txn	formatted transaction struct
socket	socket identifier for dotsTheMessenger
timeout	time in seconds to keep running
isProfiling	whether or not to invoke the Matlab profiler

Does the transaction specified in the given txn, with the ensemble server connected to the given socket. txn should have the format provided by dotsEnsembleUtilities.

If timeout is provided, allows that many seconds to finish communicating with the server. Otherwise uses the default timeout from dotsTheMessenger.

If isProfiling is provided and true, invokes the Matlab profiler before starting the transaction, and turns off the profiler afterwards.

Returns a non-negative status if communication finished within the given timeout. Fills in txn with timing details and data received from the server, and returns the updated txn as a second output.

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

dotsClientEnsemble.m

Overview

Properties and Events

Protected Properties

Methods

name string name given to this automated method call

Additional Inherited Members

Constructor

◆ dotsClientEnsemble()

Methods

◆ startProfiling()

◆ stopProfiling()

◆ viewProfiling()

◆ start()

◆ finish()

◆ run()

◆ runBriefly()

◆ addCall()

◆ setActiveByName()

◆ callByName()

◆ addObject()

◆ removeObject()

◆ assignObject()

◆ passObject()

◆ setObjectProperty()

◆ getObjectProperty()

◆ callObjectMethod()

◆ updateServerObject()

◆ resetServer()

◆ doSynchronousTransaction()