Collage  0.6.1
Public Member Functions | Public Types | Protected Member Functions | Friends
co::LocalNode Class Reference

Specialization of a local node. More...

#include <localNode.h>

+ Inheritance diagram for co::LocalNode:
+ Collaboration diagram for co::LocalNode:

List of all members.

Public Member Functions

CO_API void ackRequest (NodePtr node, const uint32_t requestID)
CO_API void ping (NodePtr remoteNode)
 Request keep-alive update from the remote node.
CO_API bool pingIdleNodes ()
 Request updates from all nodes above keep-alive timeout.
CO_API void setAffinity (const int32_t affinity)
 Set the affinity for this, the receiver and the command thread.
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.
virtual CO_API bool listen ()
 Open all connections and put this node into the listening state.
virtual CO_API bool listen (ConnectionPtr connection)
virtual CO_API bool close ()
 Close a listening node.
virtual bool exitLocal ()
 Close a listening node.
CO_API bool connect (NodePtr node)
 Connect a proxy node to this listening node.
CO_API NodePtr connect (const NodeID &nodeID)
 Create and connect a node given by an identifier.
virtual CO_API bool disconnect (NodePtr node)
 Disconnects a connected node.
Object Registry
CO_API void disableInstanceCache ()
 Disable the instance cache of a stopped local node.
CO_API void expireInstanceData (const int64_t age)
CO_API void enableSendOnRegister ()
 Enable sending instance data after registration.
CO_API void disableSendOnRegister ()
 Disable sending data of newly registered objects when idle.
virtual CO_API bool registerObject (Object *object)
 Register a distributed object.
virtual CO_API void deregisterObject (Object *object)
 Deregister a distributed object.
CO_API bool mapObject (Object *object, const UUID &id, const uint128_t &version=VERSION_OLDEST)
 Map a distributed object.
bool mapObject (Object *object, const ObjectVersion &v)
 Convenience wrapper for mapObject().
CO_API uint32_t mapObjectNB (Object *object, const UUID &id, const uint128_t &version=VERSION_OLDEST)
 Start mapping a distributed object.
virtual CO_API uint32_t mapObjectNB (Object *object, const UUID &id, const uint128_t &version, NodePtr master)
 Start mapping a distributed object from a known master.
virtual CO_API bool mapObjectSync (const uint32_t requestID)
 Finalize the mapping of a distributed object.
virtual CO_API void unmapObject (Object *object)
 Unmap a mapped object.
CO_API void releaseObject (Object *object)
 Convenience method to deregister or unmap an object.
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.
CO_API void registerPushHandler (const uint128_t &groupID, const PushHandler &handler)
 Register a custom handler for Object::push operations.
CO_API bool registerCommandHandler (const uint128_t &command, const CommandHandler &func, CommandQueue *queue)
 Register a custom command handler handled by this node.
CO_API void swapObject (Object *oldObject, Object *newObject)
Data Access
CO_API NodePtr getNode (const NodeID &id) const
 Get a node by identifier.
CO_API void getNodes (Nodes &nodes, const bool addSelf=true) const
 Assemble a vector of the currently connected nodes.
CO_API CommandQueuegetCommandThreadQueue ()
 Return the command queue to the command thread.
CO_API bool inCommandThread () const
CO_API int64_t getTime64 () const
Operations
CO_API ConnectionPtr addListener (ConnectionDescriptionPtr desc)
 Add a listening connection to this listening node.
CO_API void addListener (ConnectionPtr connection)
 Add a listening connection to this listening node.
CO_API void removeListeners (const Connections &connections)
 Remove listening connections from this listening node.
CO_API void flushCommands ()
 Flush all pending commands on this listening node.
CO_API CommandcloneCommand (Command &command)
CO_API CommandallocCommand (const uint64_t size)
CO_API bool dispatchCommand (Command &command)
 Dispatches a packet to the registered command queue.
CO_API SendToken acquireSendToken (NodePtr toNode)
 Acquire a singular send token from the given node.
CO_API void releaseSendToken (SendToken &token)
CO_API Zeroconf getZeroconf ()

Public Types

typedef NodePtr SendToken
 An acquired send token.
typedef boost::function< void(const
uint128_t &, const uint128_t
&, const uint128_t
&, DataIStream &) > 
PushHandler
 Function signature for push handlers.
typedef boost::function< bool(Command &) > CommandHandler
 Function signature for custom command handlers.

Protected Member Functions

CO_API bool connect (NodePtr node, ConnectionPtr connection)
virtual void notifyDisconnect (NodePtr node)
 Notify remote node disconnection from the receiver thread.

Friends

class detail::ReceiverThread
class detail::CommandThread
class ObjectStore

Detailed Description

Specialization of a local node.

Local nodes listen on network connections, manage connections to other nodes and provide session registration, mapping and command dispatch.

Definition at line 40 of file localNode.h.


Member Typedef Documentation

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

Function signature for custom command handlers.

Definition at line 56 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.

Definition at line 53 of file localNode.h.


Member Function Documentation

Acquire a singular send token from the given node.

Returns:
The send token to release.

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 if it was not stopped.

Referenced by exitLocal().

+ Here is the caller graph for this function:

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

Connect a proxy node to this listening node.

The connection descriptions of the node are used to connect the 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:
nodethe remote node.
Returns:
true if this node was connected, false otherwise.
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:
nodeIDthe identifier of the node to connect.
Returns:
the connected node, or an invalid RefPtr if the node could not be connected.
virtual CO_API void co::LocalNode::deregisterObject ( Object object) [virtual]

Deregister a distributed object.

Parameters:
objectthe object instance.

Implements co::ObjectHandler.

Disable the instance cache of a stopped local node.

Disable sending data of newly registered objects when idle.

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

Disconnects a connected node.

Parameters:
nodethe remote node.
Returns:
true if the node was disconnected correctly, false otherwise.
CO_API bool co::LocalNode::dispatchCommand ( Command command) [virtual]

Dispatches a packet to the registered command queue.

Parameters:
commandthe command.
Returns:
the result of the operation.
See also:
Command::invoke

Reimplemented from co::Dispatcher.

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.

virtual bool co::LocalNode::exitLocal ( ) [inline, virtual]

Close a listening node.

Definition at line 117 of file localNode.h.

References close().

+ Here is the call graph for this function:

Flush all pending commands on this listening node.

This causes the receiver thread to redispatch all pending commands, which are normally only redispatched when a new command is received.

Return the command queue to the command thread.

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

Get a node by identifier.

The node might not be connected.

Parameters:
idthe node identifier.
Returns:
the node.
CO_API void co::LocalNode::getNodes ( Nodes nodes,
const bool  addSelf = true 
) const

Assemble a vector of the currently connected nodes.

Returns:
a Zeroconf communicator handle for this node.
CO_API bool co::LocalNode::inCommandThread ( ) const
Returns:
true if executed from the command handler thread, false if not.
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 '--eq-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:
argcthe command line argument count.
argvthe command line argument values.
Returns:
true if the client was successfully initialized, false otherwise.
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 if not.
See also:
connect
CO_API bool co::LocalNode::mapObject ( Object object,
const UUID &  id,
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.

Parameters:
objectthe object.
idthe master object identifier.
versionthe initial version.
Returns:
true if the object was mapped, false if the master of the object is not found or the requested version is no longer available.
See also:
registerObject
bool co::LocalNode::mapObject ( Object object,
const ObjectVersion v 
) [inline]

Convenience wrapper for mapObject().

Definition at line 244 of file localNode.h.

References mapObject().

Referenced by mapObject().

+ Here is the call graph for this function:

+ Here is the caller graph for this function:

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

Start mapping a distributed object.

See also:
mapObject()
virtual CO_API uint32_t co::LocalNode::mapObjectNB ( Object object,
const UUID &  id,
const uint128_t &  version,
NodePtr  master 
) [virtual]

Start mapping a distributed object from a known master.

See also:
mapObject()

Implements co::ObjectHandler.

virtual CO_API bool co::LocalNode::mapObjectSync ( const uint32_t  requestID) [virtual]

Finalize the mapping of a distributed object.

Implements co::ObjectHandler.

virtual void co::LocalNode::notifyDisconnect ( NodePtr  node) [inline, protected, virtual]

Notify remote node disconnection from the receiver thread.

Definition at line 432 of file localNode.h.

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 upon reception of the pushed data from the command thread. Called on all nodes of a multicast group, even on 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:
groupIDThe group identifier given to Object::push()
objectTypeThe type identifier given to Object::push()
objectIDThe identifier of the pushed object
istreamthe input data stream containing the instance data.
CO_API void co::LocalNode::ping ( NodePtr  remoteNode)

Request keep-alive update from the remote node.

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.

Parameters:
commandthe unique identifier of the custom command
functhe handler function for the custom command
queuethe queue where the command should be inserted to
Returns:
true on successful registering, false otherwise
virtual CO_API bool co::LocalNode::registerObject ( Object object) [virtual]

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:
objectthe object instance.
Returns:
true if the object was registered, false otherwise.

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:
groupIDThe group identifier given to Object::push()
handlerThe handler function called for a registered groupID
CO_API void co::LocalNode::releaseObject ( Object object)

Convenience method to deregister or unmap an object.

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

Remove listening connections from this listening node.

CO_API void co::LocalNode::setAffinity ( const int32_t  affinity)

Set the affinity for this, the receiver and the command thread.

virtual CO_API void co::LocalNode::unmapObject ( Object object) [virtual]

Unmap a mapped object.

Parameters:
objectthe mapped object.

Implements co::ObjectHandler.


The documentation for this class was generated from the following file:
Generated on Mon Nov 26 2012 14:41:44 for Collage 0.6.1 by  doxygen 1.7.6.1