Node specialization for a local node. More...

#include <localNode.h>

Inheritance diagram for co::LocalNode:

Collaboration diagram for co::LocalNode:

Public Types
enum	Counter { COUNTER_MAP_OBJECT_REMOTE, COUNTER_ALL }
	Counters are monotonically increasing performance variables for operations performed by a LocalNode instance. More...

Public Types inherited from co::Dispatcher
typedef CommandFunc< Dispatcher >	Func
	The signature of the base Dispatcher callback. More...

Public Member Functions
CO_API	LocalNode (const uint32_t type=co::NODETYPE_NODE)
	Construct a new local node of the given type. More...

CO_API void	ackRequest (NodePtr node, const uint32_t requestID)

CO_API void	ping (NodePtr remoteNode)
	Request keep-alive update from the remote node. More...

CO_API bool	pingIdleNodes ()
	Request updates from all nodes above keep-alive timeout. More...

CO_API void	setAffinity (const int32_t affinity)
	Bind this, the receiver and the command thread to the given lunchbox::Thread affinity.

CO_API void	addConnection (ConnectionPtr connection)

State Changes
The following methods affect the state of the node by changing its connectivity to the network.
virtual CO_API bool	initLocal (const int argc, char **argv)
	Initialize the node. More...

virtual CO_API bool	listen ()
	Open all connections and put this node into the listening state. More...

virtual CO_API bool	close ()
	Close a listening node. More...

virtual bool	exitLocal ()
	Close a listening node. More...

CO_API bool	connect (NodePtr node)
	Connect a remote node (proxy) to this listening node. More...

CO_API NodePtr	connect (const NodeID &nodeID)
	Create and connect a node given by an identifier. More...

CO_API NodePtr	connectObjectMaster (const uint128_t &id)
	Find and connect the node where the given object is registered. More...

virtual CO_API bool	disconnect (NodePtr node)
	Disconnect a connected node. More...

Launching a remote node
CO_API bool	launch (NodePtr node, const std::string &command)
	Launch a remote process using the given command. More...

CO_API NodePtr	syncLaunch (const uint128_t &nodeID, int64_t timeout)
	Wait for a launched node to connect. More...

Data Access
CO_API NodePtr	getNode (const NodeID &id) const
	Get a node by identifier. More...

CO_API Nodes	getNodes (const bool addSelf=true) const

CO_API CommandQueue *	getCommandThreadQueue ()
	Return the command queue to the command thread. More...

CO_API bool	inCommandThread () const

CO_API const Strings &	getCommandLine () const

CO_API int64_t	getTime64 () const

CO_API ssize_t	getCounter (const Counter counter) const

Public Member Functions inherited from co::Node
CO_API	Node (const uint32_t type=co::NODETYPE_NODE)
	Construct a new node proxy. More...

CO_API int64_t	getLastReceiveTime () const

CO_API std::string	serialize () const

CO_API bool	deserialize (std::string &data)

CO_API const NodeID &	getNodeID () const
	Get the node's unique identifier. More...

CO_API uint32_t	getType () const

bool	operator== (const Node *n) const

CO_API bool	isReachable () const

CO_API bool	isConnected () const

CO_API bool	isListening () const

CO_API bool	isClosed () const

CO_API bool	isClosing () const

bool	isLocal () const

CO_API void	addConnectionDescription (ConnectionDescriptionPtr cd)
	Add a new description how this node can be reached. More...

CO_API bool	removeConnectionDescription (ConnectionDescriptionPtr cd)
	Removes a connection description. More...

CO_API ConnectionDescriptions	getConnectionDescriptions () const

CO_API ConnectionPtr	getConnection (const bool multicast=false)
	Get an active connection to this node. More...

CO_API OCommand	send (const uint32_t cmd, const bool multicast=false)
	Send a command with optional data to the node. More...

CO_API CustomOCommand	send (const uint128_t &commandID, const bool multicast=false)
	Send a custom command with optional data to the node. More...

CO_API void	setHostname (const std::string &host)
	Set the host name for the launch command. More...

CO_API const std::string &	getHostname () const

virtual CO_API std::string	getWorkDir () const

virtual CO_API std::string	getLaunchQuote () const

Public Member Functions inherited from co::Dispatcher
Dispatcher &	operator= (const Dispatcher &)

template<typename T >
void	registerCommand (const uint32_t command, const CommandFunc< T > &func, CommandQueue *queue)
	Register a command member function for a command. More...

Public Member Functions inherited from co::ObjectHandler
CO_API void	releaseObject (Object *object)
	Convenience method to deregister or unmap an object. More...

Protected Member Functions
CO_API	~LocalNode () override
	Destruct this local node. More...

CO_API bool	connect (NodePtr node, ConnectionPtr connection)

virtual void	notifyConnect (NodePtr)

virtual void	notifyDisconnect (NodePtr)

virtual CO_API NodePtr	createNode (const uint32_t type)
	Factory method to create a new node. More...

Protected Member Functions inherited from co::Node
virtual CO_API	~Node ()
	Destruct this node. More...

void	_addConnectionDescription (ConnectionDescriptionPtr cd)

bool	_removeConnectionDescription (ConnectionDescriptionPtr cd)

ConnectionPtr	_getMulticast () const

ConnectionPtr	getMulticast ()
	Activate and return a multicast connection. More...

Protected Member Functions inherited from co::Dispatcher
CO_API	Dispatcher (const Dispatcher &from)

CO_API bool	_cmdUnknown (ICommand &command)
	The default handler for handling commands. More...

Protected Member Functions inherited from co::ObjectHandler
	ObjectHandler ()
	Construct a new object handler. More...

virtual	~ObjectHandler ()
	Destroy this object handler. More...

Friends
class	detail::ReceiverThread

class	detail::CommandThread

class	ObjectStore

Object Registry
typedef boost::function< void(const uint128_t &, const uint128_t &, const uint128_t &, DataIStream &)>	PushHandler
	Function signature for push handlers. More...

typedef boost::function< bool(CustomICommand &)>	CommandHandler
	Function signature for custom command handlers. More...

CO_API bool	registerObject (Object *object) override
	Register a distributed object. More...

CO_API void	deregisterObject (Object *object) override
	Deregister a distributed object. More...

CO_API f_bool_t	mapObject (Object *object, const uint128_t &id, NodePtr master, const uint128_t &version=VERSION_OLDEST)
	Map a distributed object. More...

f_bool_t	mapObject (Object *object, const ObjectVersion &v)
	Convenience wrapper for mapObject(). More...

f_bool_t	mapObject (Object *object, const uint128_t &id, const uint128_t &version=VERSION_OLDEST)

CO_API uint32_t	mapObjectNB (Object *object, const uint128_t &id, const uint128_t &version=VERSION_OLDEST)

CO_API uint32_t	mapObjectNB (Object *object, const uint128_t &id, const uint128_t &version, NodePtr master) override

CO_API bool	mapObjectSync (const uint32_t requestID) override

CO_API f_bool_t	syncObject (Object *object, const uint128_t &id, NodePtr master, const uint32_t instanceID=CO_INSTANCE_ALL) override
	Synchronize the local object with a remote object. More...

CO_API void	unmapObject (Object *object) override
	Unmap a mapped object. More...

CO_API void	disableInstanceCache ()
	Disable the instance cache of a stopped local node. More...

CO_API void	expireInstanceData (const int64_t age)

CO_API void	enableSendOnRegister ()
	Enable sending instance data after registration. More...

CO_API void	disableSendOnRegister ()
	Disable sending data of newly registered objects. More...

virtual CO_API void	objectPush (const uint128_t &groupID, const uint128_t &objectType, const uint128_t &objectID, DataIStream &istream)
	Handler for an Object::push() operation. More...

CO_API void	registerPushHandler (const uint128_t &groupID, const PushHandler &handler)
	Register a custom handler for Object::push operations. More...

CO_API bool	registerCommandHandler (const uint128_t &command, const CommandHandler &func, CommandQueue *queue)
	Register a custom command handler handled by this node. More...

CO_API void	swapObject (Object oldObject, Object newObject)

Operations
typedef lunchbox::RefPtr< co::SendToken >	SendToken
	A handle for a send token acquired by acquireSendToken(). More...

CO_API ConnectionPtr	addListener (ConnectionDescriptionPtr desc)
	Add a listening connection to this listening node. More...

CO_API void	addListener (ConnectionPtr connection)
	Add a listening connection to this listening node. More...

CO_API void	removeListeners (const Connections &connections)
	Remove listening connections from this listening node. More...

CO_API void	flushCommands ()

CO_API BufferPtr	allocBuffer (const uint64_t size)

CO_API bool	dispatchCommand (ICommand &command) override
	Dispatches a command to the registered command queue. More...

CO_API SendToken	acquireSendToken (NodePtr toNode)
	Acquire a send token from the given node. More...

CO_API void	releaseSendToken (SendToken token)

CO_API Zeroconf	getZeroconf ()

Detailed Description

Node specialization for a local node.

Local nodes listen on network connections, manage connections to other nodes and provide Object registration, mapping and command dispatch. Typically each process uses one local node to communicate with other processes.

Definition at line 49 of file localNode.h.

Member Typedef Documentation

typedef boost::function<bool(CustomICommand&)> co::LocalNode::CommandHandler

Function signature for custom command handlers.

Version: 1.0

Definition at line 414 of file localNode.h.

typedef boost::function<void(const uint128_t&, const uint128_t&, const uint128_t&, DataIStream&)> co::LocalNode::PushHandler

Function signature for push handlers.

Version: 1.0

Definition at line 399 of file localNode.h.

typedef lunchbox::RefPtr<co::SendToken> co::LocalNode::SendToken

A handle for a send token acquired by acquireSendToken().

Definition at line 511 of file localNode.h.

Member Enumeration Documentation

enum co::LocalNode::Counter

Counters are monotonically increasing performance variables for operations performed by a LocalNode instance.

Enumerator
COUNTER_MAP_OBJECT_REMOTE	Num of mapObjects served for other nodes.

Definition at line 58 of file localNode.h.

Constructor & Destructor Documentation

CO_API co::LocalNode::LocalNode ( const uint32_t type = co::NODETYPE_NODE )

explicit

Construct a new local node of the given type.

Version: 1.0

CO_API co::LocalNode::~LocalNode ( )

overrideprotected

Destruct this local node.

Version: 1.0

Member Function Documentation

CO_API SendToken co::LocalNode::acquireSendToken ( NodePtr toNode )

Acquire a send token from the given node.

The token is released automatically when it leaves its scope or explicitly using releaseSendToken().

Returns: The send token.

CO_API ConnectionPtr co::LocalNode::addListener ( ConnectionDescriptionPtr desc )

Add a listening connection to this listening node.

Returns: the listening connection, or 0 upon error.

CO_API void co::LocalNode::addListener ( ConnectionPtr connection )

Add a listening connection to this listening node.

virtual CO_API bool co::LocalNode::close ( )

virtual

Close a listening node.

Disconnects all connected node proxies, closes the listening connections and terminates all threads created in listen().

Returns: true if the node was stopped, false otherwise.

Version: 1.0

CO_API bool co::LocalNode::connect ( NodePtr node )

Connect a remote node (proxy) to this listening node.

The connection descriptions of the node are used to connect the remote local node. On success, the node is in the connected state, otherwise its state is unchanged.

This method is one-sided, that is, the node to be connected should not initiate a connection to this node at the same time. For concurrent connects use the other connect() method using node identifiers.

Parameters

node	the remote node.

Returns: true if this node was connected, false otherwise.

Version: 1.0

CO_API NodePtr co::LocalNode::connect ( const NodeID & nodeID )

Create and connect a node given by an identifier.

This method is two-sided and thread-safe, that is, it can be called by multiple threads on the same node with the same nodeID, or concurrently on two nodes with each others' nodeID.

Parameters

nodeID the identifier of the node to connect.

Returns: the connected node, or an invalid RefPtr if the node could not be connected.

Version: 1.0

CO_API NodePtr co::LocalNode::connectObjectMaster ( const uint128_t & id )

Find and connect the node where the given object is registered.

This method is relatively expensive, since potentially all connected nodes are queried.

Parameters

id	the identifier of the object to search for.

Returns: the connected node, or an invalid RefPtr if the node could not be found or connected.

See also: registerObject(), connect()

Version: 1.1.1

virtual CO_API NodePtr co::LocalNode::createNode ( const uint32_t type )

protectedvirtual

Factory method to create a new node.

Parameters

type	the type the node type

Returns: the node.

See also: ctor type parameter

Version: 1.0

CO_API void co::LocalNode::deregisterObject ( Object * object )

overridevirtual

Deregister a distributed object.

All slave instances should be unmapped before this call, and will be forcefully unmapped by this method.

Parameters

object the object instance.

Version: 1.0

Implements co::ObjectHandler.

CO_API void co::LocalNode::disableInstanceCache ( )

Disable the instance cache of a stopped local node.

Version: 1.0

CO_API void co::LocalNode::disableSendOnRegister ( )

Disable sending data of newly registered objects.

Version: 1.0

virtual CO_API bool co::LocalNode::disconnect ( NodePtr node )

virtual

Disconnect a connected node.

Parameters

node	the remote node.

Returns: true if the node was disconnected correctly, false otherwise.

Version: 1.0

CO_API bool co::LocalNode::dispatchCommand ( ICommand & command )

overridevirtual

Dispatches a command to the registered command queue.

Applications using custom command types have to override this method to dispatch the custom commands.

Parameters

command the command.

Returns: the result of the operation.

See also: ICommand::invoke

Version: 1.0

Reimplemented from co::Dispatcher.

CO_API void co::LocalNode::enableSendOnRegister ( )

Enable sending instance data after registration.

Send-on-register starts transmitting instance data of registered objects directly after they have been registered. The data is cached on remote nodes and accelerates object mapping. Send-on-register should not be active when remote nodes are joining a multicast group of this node, since they will potentially read out-of-order data streams on the multicast connection.

Enable and disable are counted, that is, the last enable on a matched series of disable/enable will be effective. The disable is completely synchronous, that is, no more instance data will be sent after the first disable.

Version: 1.0

virtual bool co::LocalNode::exitLocal ( )

inlinevirtual

Close a listening node.

Version: 1.0

Definition at line 125 of file localNode.h.

CO_API const Strings& co::LocalNode::getCommandLine ( ) const

Returns: the non-Collage command line options passed to initLocal().

CO_API CommandQueue* co::LocalNode::getCommandThreadQueue ( )

Return the command queue to the command thread.

Version: 1.0

CO_API NodePtr co::LocalNode::getNode ( const NodeID & id ) const

Get a node by identifier.

The node might not be connected. Thread safe.

Parameters

id	the node identifier.

Returns: the node.

Version: 1.0

CO_API Nodes co::LocalNode::getNodes ( const bool addSelf = true ) const

Returns: a vector of the currently connected nodes.

Version: 1.0

CO_API Zeroconf co::LocalNode::getZeroconf ( )

Returns: a Zeroconf communicator handle for this node.

Version: 1.0

CO_API bool co::LocalNode::inCommandThread ( ) const

Returns: true if executed from the command handler thread, false if not.

Version: 1.0

virtual CO_API bool co::LocalNode::initLocal	(	const int	argc,
		char **	argv
	)

virtual

Initialize the node.

Parses the following command line options and calls listen() afterwards:

The '–co-listen <connection description>' command line option is parsed by this method to add listening connections to this node. This parameter might be used multiple times. ConnectionDescription::fromString() is used to parse the provided description.

The '–co-globals <string>' option is used to initialize the Globals. The string is parsed used Globals::fromString().

Please note that further command line parameters are recognized by co::init().

Parameters

argc	the command line argument count.
argv	the command line argument values.

Returns: true if the client was successfully initialized, false otherwise.

Version: 1.0

CO_API bool co::LocalNode::launch	(	NodePtr	node,
		const std::string &	command
	)

Launch a remote process using the given command.

The launched node will automatically connect with this node, if it passes the given options to its initLocal().

The following markers are replaced in the command:

h: Node::getHostname()
n: Node identifier in string representation
d: Node::getWorkDir()
q: Node::getLaunchQuote()
o: Options needed by remote initLocal() to connect this node. If not given, options are appended at the end of the given command.

Returns: true if the launch process execution was successful.

virtual CO_API bool co::LocalNode::listen ( )

virtual

Open all connections and put this node into the listening state.

The node will spawn a receiver and command thread, and listen on all connections for incoming commands. The node will be in the listening state if the method completed successfully. A listening node can connect other nodes.

Returns: true if the node could be initialized, false otherwise.

See also: connect()

Version: 1.0

CO_API f_bool_t co::LocalNode::mapObject	(	Object *	object,
		const uint128_t &	id,
		NodePtr	master,
		const uint128_t &	version = `VERSION_OLDEST`
	)

Map a distributed object.

The mapped object becomes a slave instance of the master version which was registered with the provided identifier. The given version can be used to map a specific version.

If VERSION_NONE is provided, the slave instance is not initialized with any data from the master. This is useful if the object has been pre-initialized by other means, for example from a shared file system.

If VERSION_OLDEST is provided, the oldest available version is mapped.

If a concrete requested version no longer exists, mapObject() will map the oldest available version.

If the requested version is newer than the head version, mapObject() will block until the requested version is available.

Mapping an object is a potentially time-consuming operation. Using mapObjectNB() and mapObjectSync() to asynchronously map multiple objects in parallel improves performance of this operation.

After mapping, the object will have the version used during initialization, or VERSION_NONE if mapped to this version.

When no master node is given, connectObjectMaster() is used to find the node with the master instance.

This method returns immediately after initiating the mapping. Evaluating the value of the returned lunchbox::Future will block on the completion of the operation and return true if the object was mapped, false if the master of the object is not found or the requested version is no longer available.

Parameters

object	the object.
id	the master object identifier.
master	the node with the master instance, may be 0.
version	the initial version.

Returns: A lunchbox::Future which will deliver the success status of the operation on evaluation.

See also: registerObject

Version: 1.0

f_bool_t co::LocalNode::mapObject	(	Object *	object,
		const ObjectVersion &	v
	)

inline

Convenience wrapper for mapObject().

Version: 1.0

Definition at line 286 of file localNode.h.

References co::ObjectVersion::identifier, and co::ObjectVersion::version.

f_bool_t co::LocalNode::mapObject	(	Object *	object,
		const uint128_t &	id,
		const uint128_t &	version = `VERSION_OLDEST`
	)

inline

Deprecated:

Definition at line 292 of file localNode.h.

CO_API uint32_t co::LocalNode::mapObjectNB	(	Object *	object,
		const uint128_t &	id,
		const uint128_t &	version = `VERSION_OLDEST`
	)

Deprecated:: use mapObject()

CO_API uint32_t co::LocalNode::mapObjectNB	(	Object *	object,
		const uint128_t &	id,
		const uint128_t &	version,
		NodePtr	master
	)

overridevirtual

Deprecated:: use mapObject()

Implements co::ObjectHandler.

CO_API bool co::LocalNode::mapObjectSync ( const uint32_t requestID )

overridevirtual

Deprecated:: use mapObject()

Implements co::ObjectHandler.

virtual CO_API void co::LocalNode::objectPush	(	const uint128_t &	groupID,
		const uint128_t &	objectType,
		const uint128_t &	objectID,
		DataIStream &	istream
	)

virtual

Handler for an Object::push() operation.

Called at least on each node listed in an Object::push() operation upon reception of the pushed data from the command thread. Called on all nodes of a multicast group, even for nodes not listed in the Object::push().

The default implementation calls registered push handlers. Typically used to create an object on a remote node, using the objectType for instantiation, the istream to initialize it, and the objectID to map it using VERSION_NONE. The groupID may be used to differentiate multiple concurrent push operations.

Parameters

groupID	The group identifier given to Object::push()
objectType	The type identifier given to Object::push()
objectID	The identifier of the pushed object
istream	the input data stream containing the instance data.

Version: 1.0

CO_API void co::LocalNode::ping ( NodePtr remoteNode )

Request keep-alive update from the remote node.

CO_API bool co::LocalNode::pingIdleNodes ( )

Request updates from all nodes above keep-alive timeout.

Returns: true if at least one ping was send.

CO_API bool co::LocalNode::registerCommandHandler	(	const uint128_t &	command,
		const CommandHandler &	func,
		CommandQueue *	queue
	)

Register a custom command handler handled by this node.

Custom command handlers are invoked on reception of a CustomICommand send by Node::send( uint128_t, ... ). The command identifier needs to be unique. It is recommended to use servus::make_uint128() to generate this identifier.

Parameters

command	the unique identifier of the custom command
func	the handler function for the custom command
queue	the queue where the command should be inserted to

Returns: true on successful registering, false otherwise

Version: 1.0

CO_API bool co::LocalNode::registerObject ( Object * object )

overridevirtual

Register a distributed object.

Registering a distributed object makes this object the master version. The object's identifier is used to map slave instances of the object. Master versions of objects are typically writable and can commit new versions of the distributed object.

Parameters

object the object instance.

Returns: true if the object was registered, false otherwise.

Version: 1.0

Implements co::ObjectHandler.

CO_API void co::LocalNode::registerPushHandler	(	const uint128_t &	groupID,
		const PushHandler &	handler
	)

Register a custom handler for Object::push operations.

The registered handler function will be called automatically for an incoming object push. Threadsafe with itself and objectPush().

Parameters

groupID	The group identifier given to Object::push()
handler	The handler function called for a registered groupID

Version: 1.0

CO_API void co::LocalNode::releaseSendToken ( SendToken token )

Deprecated:: Token will auto-release when leaving scope.

CO_API void co::LocalNode::removeListeners ( const Connections & connections )

Remove listening connections from this listening node.

CO_API NodePtr co::LocalNode::syncLaunch	(	const uint128_t &	nodeID,
		int64_t	timeout
	)

Wait for a launched node to connect.

Returns: the remote node handle, or 0 on timeout.

CO_API f_bool_t co::LocalNode::syncObject	(	Object *	object,
		const uint128_t &	id,
		NodePtr	master,
		const uint32_t	instanceID = `CO_INSTANCE_ALL`
	)

overridevirtual

Synchronize the local object with a remote object.

The object is synchronized to the newest version of the first attached object on the given master node matching the instanceID. When no master node is given, connectObjectMaster() is used to find the node with the master instance. When CO_INSTANCE_ALL is given, the first instance is used. Before a successful return, applyInstanceData() is called on the calling thread to synchronize the given object.

Parameters

object	The local object instance to synchronize.
master	The node where the synchronizing object is attached.
id	the object identifier.
instanceID	the instance identifier of the synchronizing object.

Returns: A lunchbox::Future which will deliver the success status of the operation on evaluation.

Version: 1.1.1

Implements co::ObjectHandler.

CO_API void co::LocalNode::unmapObject ( Object * object )

overridevirtual

Unmap a mapped object.

Parameters

object the mapped object.

Version: 1.0

Implements co::ObjectHandler.

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

localNode.h

Public Types

Public Member Functions

Protected Member Functions

Friends

Object Registry

Operations

Detailed Description

Member Typedef Documentation

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation