eq::net::Session Class Reference

Provides higher-level functionality to a set of nodes. More...

#include <session.h>

Inheritance diagram for eq::net::Session:

[legend]

Collaboration diagram for eq::net::Session:

[legend]

List of all members.

Public Member Functions
	Session ()
	Construct a new session.
virtual	~Session ()
	Destruct this session.
Data Access

uint32_t	getID () const
NodePtr	getLocalNode ()
CommandQueue *	getCommandThreadQueue ()
NodePtr	getServer ()
Command Packet Dispatch

virtual bool	dispatchCommand (Command &packet)
	Dispatches a command packet to the registered command queue.
virtual CommandResult	invokeCommand (Command &packet)
	Invokes the registered handler method for a command packet.
Identifier management

uint32_t	genIDs (const uint32_t range)
	Generate a continous block of unique identifiers.
void	freeIDs (const uint32_t start, const uint32_t range)
	Free a continous block of unique identifiers.
void	setIDMaster (const uint32_t id, const NodeID &master)
	Set the master node for an identifier.
void	unsetIDMaster (const uint32_t id)
	Delete the master node for an identifiers.
const NodeID &	getIDMaster (const uint32_t id)
	Returns the master node id for an identifier.
Object Registration

bool	registerObject (Object *object)
	Register a distributed object.
void	deregisterObject (Object *object)
	Deregister a distributed object.
bool	mapObject (Object *object, const uint32_t id, const uint32_t version=VERSION_OLDEST)
	Map a distributed object.
uint32_t	mapObjectNB (Object *object, const uint32_t id, const uint32_t version=VERSION_OLDEST)
	Start mapping a distributed object.
bool	mapObjectSync (const uint32_t requestID)
	Finalize the mapping of a distributed object.
void	unmapObject (Object *object)
	Unmap a mapped object.
void	attachObject (Object *object, const uint32_t id, const uint32_t instanceID)
	Attach an object to an identifier.
void	detachObject (Object *object)
	Detach an object.
Notifications

virtual void	notifyMapped (NodePtr node)
	Notification that this session has been mapped to a node.
Protected Member Functions
void	expireInstanceData (const int64_t age)
Friends
class	Node
Sending session packets

base::RequestHandler	_requestHandler
	Registers request for packets awaiting a return value.
void	send (NodePtr node, SessionPacket &packet)
	Send a session packet to a node.
void	send (SessionPacket &packet)
	Send a packet to the session's server node.
template<typename T >
void	send (SessionPacket &packet, const std::vector< T > &data)
	Send a packet containing additional data to the session's server.
void	send (NodePtr node, SessionPacket &packet, const std::string &text)
	Send a packet containing a string to a node.
void	send (NodePtr node, SessionPacket &packet, const void *data, const uint64_t size)
	Send a packet containing additional data to a node.

Detailed Description

Provides higher-level functionality to a set of nodes.

A session provides unique identifiers and eq::net::Object mapping for a set of nodes. The master node registers the session, which makes this node the session server and assigns a node-unique identifier to the session. All other nodes map the session using this identifier.

A received SessionPacket is dispatched to the locally-mapped session of the same identifier.

Definition at line 47 of file session.h.

Constructor & Destructor Documentation

eq::net::Session::Session ( )

Construct a new session.

Definition at line 45 of file session.cpp.

References EQINFO.

eq::net::Session::~Session ( ) [virtual]

Destruct this session.

Definition at line 57 of file session.cpp.

References EQINFO, and EQWARN.

Member Function Documentation

uint32_t eq::net::Session::getID ( ) const [inline]

Returns:: the identifier of this session.

Definition at line 59 of file session.h.

Referenced by eq::net::Object::becomeMaster(), eq::net::Node::mapSession(), eq::server::Config::notifyNodeFrameFinished(), eq::net::Node::registerSession(), eq::Server::releaseConfig(), eq::net::Object::send(), eq::Config::sendEvent(), eq::FrameData::transmit(), eq::net::Node::unmapSession(), eq::net::Node::~Node(), and eq::net::Object::~Object().

Here is the caller graph for this function:

NodePtr eq::net::Session::getLocalNode ( ) [inline]

Returns:: the local node to which this session is mapped, or 0 if the session is not mapped.

Definition at line 65 of file session.h.

Referenced by eq::net::Object::becomeMaster(), eq::net::Barrier::enter(), eq::net::Object::getLocalNode(), and eq::Config::sendEvent().

Here is the caller graph for this function:

CommandQueue * eq::net::Session::getCommandThreadQueue ( )

Returns:: the queue to the command thread of the local node, or 0 if the session is not mapped.

Definition at line 104 of file session.cpp.

Referenced by eq::net::Object::attachToSession(), eq::FrameData::attachToSession(), eq::net::Barrier::attachToSession(), and eq::server::Config::notifyMapped().

Here is the caller graph for this function:

NodePtr eq::net::Session::getServer ( ) [inline]

Returns:: the server hosting this session, or 0 if the session is not mapped..

Reimplemented in eq::Config, and eq::server::Config.

Definition at line 75 of file session.h.

Referenced by eq::net::Node::unmapSession().

Here is the caller graph for this function:

bool eq::net::Session::dispatchCommand ( Command & packet ) [virtual]

Dispatches a command packet to the registered command queue.

Session packets are dispatch on this session, object packets to the appropriate objects mapped on this session.

Parameters:

packet

the command packet.

Returns:: true if the command was dispatched, false otherwise.

See also:: Dispatcher::dispatchCommand

Reimplemented from eq::net::Dispatcher.

Definition at line 525 of file session.cpp.

References eq::net::Dispatcher::dispatchCommand(), and EQVERB.

Here is the call graph for this function:

CommandResult eq::net::Session::invokeCommand ( Command & packet ) [virtual]

Invokes the registered handler method for a command packet.

For object packets, invocation is forwarded to the appropriate object(s).

Parameters:

packet

the command packet.

Returns:: the result of the operation.

See also:: Dispatcher::invokeCommand

Reimplemented from eq::net::Dispatcher.

Definition at line 565 of file session.cpp.

References eq::net::COMMAND_ERROR, EQVERB, and EQWARN.

uint32_t eq::net::Session::genIDs ( const uint32_t range )

Generate a continous block of unique identifiers.

The identifiers are unique within this session. Identifiers are reused when they are freed, that is, the same identifier might be returned twice from this function during runtime, if it was freed in between.

Out-of-IDs is signalled by returning EQ_ID_INVALID. This should rarely happen, since approximately 2^32 identifiers are available. However, ID fragmentation or generous ID allocation might deplete this pool.

Parameters:

range

the size of the block.

Returns:: the first identifier of the block, or EQ_ID_INVALID if no continous block of identifiers for the request is available.

See also:: base::IDPool

Definition at line 155 of file session.cpp.

References _requestHandler, EQWARN, eq::base::IDPool::genIDs(), eq::base::RequestHandler::registerRequest(), send(), and eq::base::RequestHandler::waitRequest().

Referenced by registerObject().

Here is the call graph for this function:

Here is the caller graph for this function:

void eq::net::Session::freeIDs	(	const uint32_t	start,
		const uint32_t	range
	)

Free a continous block of unique identifiers.

The block size does not need to match the block size during allocation of the identifiers.

Parameters:

	start	the first identifier in the block.
	range	the size of the block.

Definition at line 178 of file session.cpp.

References eq::base::IDPool::freeIDs().

Referenced by deregisterObject().

Here is the call graph for this function:

Here is the caller graph for this function:

void eq::net::Session::setIDMaster	(	const uint32_t	id,
		const NodeID &	master
	)

Set the master node for an identifier.

This can be used to identify the node which is responsible for the object, action or information associated with an identifier. The identifiers must be unique, it is therefore advised to allocate them using genIDs().

The master node must be reachable from this node and known by the session server node.

Parameters:

	id	the identifier.
	master	the master node for the block of identifiers.

Definition at line 187 of file session.cpp.

void eq::net::Session::unsetIDMaster ( const uint32_t id )

Delete the master node for an identifiers.

Parameters:

id

the identifier.

const NodeID & eq::net::Session::getIDMaster ( const uint32_t id )

Returns the master node id for an identifier.

Parameters:

id

the identifier.

Returns:: the master node, or Node::ZERO if no master node is set for the identifier.

Definition at line 224 of file session.cpp.

References _requestHandler, EQLOG, eq::base::RequestHandler::registerRequest(), send(), eq::base::Lock::set(), eq::base::Lock::unset(), eq::base::RequestHandler::waitRequest(), and eq::base::UUID::ZERO.

Referenced by eq::net::Object::becomeMaster(), and mapObjectNB().

Here is the call graph for this function:

Here is the caller graph for this function:

bool eq::net::Session::registerObject ( Object * object )

Register a distributed object.

Registering a distributed object assigns a session-unique identifier to this object, and makes this object the master version. The 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.

Definition at line 468 of file session.cpp.

References attachObject(), EQLOG, genIDs(), eq::net::Object::getChangeType(), and eq::net::Object::getID().

Referenced by eq::net::Object::becomeMaster(), eq::server::Frame::cycleData(), eq::server::Node::getBarrier(), eq::server::Config::getDistributorID(), eVolve::Config::init(), eqPly::Config::init(), and eq::server::CompoundInitVisitor::visit().

Here is the call graph for this function:

Here is the caller graph for this function:

void eq::net::Session::deregisterObject ( Object * object )

Deregister a distributed object.

Parameters:

object

the object instance.

Definition at line 488 of file session.cpp.

References detachObject(), EQLOG, freeIDs(), eq::net::Object::isMaster(), and eq::net::ObjectCM::ZERO.

Referenced by eq::Observer::deregister(), eq::server::Frame::flush(), eq::server::Config::unmap(), and eq::server::CompoundExitVisitor::visit().

Here is the call graph for this function:

Here is the caller graph for this function:

bool eq::net::Session::mapObject	(	Object *	object,
		const uint32_t	id,
		const uint32_t	version = `VERSION_OLDEST`
	)

Map a distributed object.

The mapped object becomes a slave instance of the master version which was registered to 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 the requested version does no longer exist, mapObject() will fail. 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:

	object	the object.
	id	the master object identifier.
	version	the 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

Definition at line 352 of file session.cpp.

References mapObjectNB(), and mapObjectSync().

Referenced by eq::ConfigDeserializer::applyInstanceData(), eVolve::Pipe::configInit(), eqPly::Pipe::configInit(), eqNbody::Pipe::configInit(), eq::Layout::deserialize(), eq::Canvas::deserialize(), eq::Node::getBarrier(), eq::Pipe::getFrame(), eq::Node::getFrameData(), eq::Pipe::getView(), eVolve::Config::mapData(), and eqPly::Config::mapData().

Here is the call graph for this function:

Here is the caller graph for this function:

uint32_t eq::net::Session::mapObjectNB	(	Object *	object,
		const uint32_t	id,
		const uint32_t	version = `VERSION_OLDEST`
	)

Start mapping a distributed object.

Definition at line 359 of file session.cpp.

References _requestHandler, EQLOG, EQWARN, eq::net::Object::getID(), getIDMaster(), eq::net::Object::isMaster(), eq::base::RequestHandler::registerRequest(), eq::net::Node::STATE_STOPPED, and eq::base::UUID::ZERO.

Referenced by eqPly::VertexBufferDist::applyInstanceData(), and mapObject().

Here is the call graph for this function:

Here is the caller graph for this function:

bool eq::net::Session::mapObjectSync ( const uint32_t requestID )

Finalize the mapping of a distributed object.

Definition at line 398 of file session.cpp.

References _requestHandler, EQLOG, eq::base::RequestHandler::getRequestData(), and eq::base::RequestHandler::waitRequest().

Referenced by eqPly::VertexBufferDist::applyInstanceData(), and mapObject().

Here is the call graph for this function:

Here is the caller graph for this function:

void eq::net::Session::unmapObject ( Object * object )

Unmap a mapped object.

Parameters:

object

the mapped object.

Definition at line 425 of file session.cpp.

References _requestHandler, detachObject(), EQERROR, EQLOG, eq::net::Object::isMaster(), eq::base::RefPtr< T >::isValid(), eq::base::RequestHandler::registerRequest(), send(), eq::base::Lock::set(), eq::base::Lock::unset(), and eq::base::RequestHandler::waitRequest().

Referenced by eq::net::Object::becomeMaster(), eVolve::Pipe::configExit(), eqPly::Pipe::configExit(), eqNbody::Pipe::configExit(), eq::Pipe::flushFrames(), eVolve::Config::mapData(), eqPly::Config::mapData(), eq::server::Observer::unmap(), eq::server::Layout::unmap(), and eq::server::Canvas::unmap().

Here is the call graph for this function:

Here is the caller graph for this function:

void eq::net::Session::attachObject	(	Object *	object,
		const uint32_t	id,
		const uint32_t	instanceID
	)

Attach an object to an identifier.

Attaching an object to an identifier enables it to receive object commands through this session. It does not establish any mapping to other object instances with the same identifier.

Parameters: