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

#include <session.h>

Inheritance diagram for eq::net::Session:

Collaboration diagram for eq::net::Session:

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

const SessionID &	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 bool	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.
bool	mapObject (Object *object, const ObjectVersion &v)
	Convenience wrapper for mapObject().
uint32_t	mapObjectNB (Object *object, const ObjectVersion &v)
	Convenience wrapper for mapObjectNB().
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.
void	releaseObject (Object *object)
	Convenience method to deregister or unmap an object.
Notifications

virtual void	notifyMapped (NodePtr node)
	Notification that this session has been mapped to a node.
Sending session packets

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.
Protected Member Functions
void	expireInstanceData (const int64_t age)
Friends
class	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 48 of file session.h.

Constructor & Destructor Documentation

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

Construct a new session.

Definition at line 39 of file session.cpp.

References EQINFO.

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

Destruct this session.

Definition at line 50 of file session.cpp.

References eq::base::className(), EQINFO, EQWARN, and eq::base::UUID::ZERO.

Here is the call graph for this function:

Member Function Documentation

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:

	object	the object.
	id	the object identifier.
	instanceID	the node-local instance identifier, or EQ_ID_INVALID if this method should generate one.

Definition at line 271 of file session.cpp.

Referenced by registerObject().

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 538 of file session.cpp.

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

Referenced by eq::server::Layout::deregister(), eq::server::Frame::flush(), releaseObject(), and eq::server::CompoundDeregisterVisitor::visit().

Here is the call graph for this function:

Here is the caller graph for this function:

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

Detach an object.

Parameters:

object

the attached object.

Definition at line 329 of file session.cpp.

Referenced by deregisterObject(), and unmapObject().

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 609 of file session.cpp.

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

Here is the call 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 174 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:

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 149 of file session.cpp.

References EQWARN, eq::base::IDPool::genIDs(), and send().

Referenced by registerObject().

Here is the call graph for this function:

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 96 of file session.cpp.

References eq::base::RefPtr< T >::isValid().

Referenced by eq::net::Barrier::attachToSession().

Here is the call graph for this function:

Here is the caller graph for this function:

const SessionID& eq::net::Session::getID ( ) const [inline]

Returns:: the identifier of this session.

Definition at line 60 of file session.h.

Referenced by eq::net::Object::commit(), eq::server::Node::configExit(), eq::server::Node::configInit(), eq::net::Node::mapSession(), eq::Server::releaseConfig(), eq::net::Object::send(), eq::net::Node::unmapSession(), and eq::net::Node::~Node().

Here is the caller graph for this function:

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 248 of file session.cpp.

References EQLOG, send(), and eq::base::UUID::ZERO.

Referenced by mapObjectNB().

Here is the call graph for this function:

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 66 of file session.h.

Referenced by eq::net::Barrier::enter(), and eq::Config::nextEvent().

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::fabric::Config< S, C, O, L, CV, N, V >, and eq::fabric::Config< Server, Config, Observer, Layout, Canvas, Node, ConfigVisitor >.

Definition at line 76 of file session.h.

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

Here is the caller graph for this function:

bool 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 681 of file session.cpp.

References EQVERB, and EQWARN.

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

Here is the caller graph for this function:

bool eq::net::Session::mapObject	(	Object *	object,
		const ObjectVersion &	v
	)			`[inline]`

Convenience wrapper for mapObject().

Definition at line 244 of file session.h.

References mapObject().

Referenced by mapObject().

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 373 of file session.cpp.

References mapObjectNB(), and mapObjectSync().

Referenced by osgScaleViewer::Pipe::configInit(), eVolve::Pipe::configInit(), eqPly::Pipe::configInit(), eqNbody::Pipe::configInit(), eq::fabric::Object::getName(), and eVolve::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 ObjectVersion &	v
	)			`[inline]`

Convenience wrapper for mapObjectNB().

Definition at line 248 of file session.h.

References mapObjectNB().

Referenced by mapObjectNB().

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 380 of file session.cpp.

References eq::base::className(), EQLOG, EQWARN, eq::net::Object::getID(), getIDMaster(), eq::net::Object::isMaster(), 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 443 of file session.cpp.

References eq::base::className(), and EQLOG.

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::notifyMapped ( NodePtr node ) [virtual]

Notification that this session has been mapped to a node.

Typically used by sub-classes to register command handlers. Always call the parent's notifyMapped() first.

Parameters:

node

the node to which the session has been mapped.

Reimplemented in eq::Config, eq::fabric::Config< S, C, O, L, CV, N, V >, eq::server::Config, and eq::fabric::Config< Server, Config, Observer, Layout, Canvas, Node, ConfigVisitor >.

Definition at line 105 of file session.cpp.

References eq::base::RefPtr< T >::isValid(), and eq::net::Dispatcher::registerCommand().

Here is the call 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 516 of file session.cpp.

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

Referenced by eq::server::Frame::cycleData(), eVolve::Config::init(), eq::server::Compound::update(), 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::releaseObject ( Object * object )

Convenience method to deregister or unmap an object.

Definition at line 579 of file session.cpp.

References deregisterObject(), eq::net::Object::isAttached(), eq::net::Object::isMaster(), and unmapObject().

Referenced by eq::fabric::Object::isDirty().

Here is the call graph for this function:

Here is the caller graph for this function:

void eq::net::Session::send	(	NodePtr	node,
		SessionPacket &	packet
	)			`[inline]`

Send a session packet to a node.

Parameters:

	node	the target node.
	packet	the packet.

Returns:: the success status of the transaction.

Definition at line 307 of file session.h.

Referenced by genIDs(), getIDMaster(), and unmapObject().

Here is the caller graph for this function:

template<typename T >

void eq::net::Session::send	(	SessionPacket &	packet,
		const std::vector< T > &	data
	)			`[inline]`

Send a packet containing additional data to the session's server.

Parameters:

	packet	the packet.
	data	the data to attach to the packet.

Definition at line 331 of file session.h.

void eq::net::Session::send	(	NodePtr	node,
		SessionPacket &	packet,
		const std::string &	text
	)			`[inline]`

Send a packet containing a string to a node.

Parameters:

	node	the target node.
	packet	the packet.
	text	the string to attach to the packet.

Returns:: the success status of the transaction.

Definition at line 345 of file session.h.

void eq::net::Session::send ( SessionPacket & packet ) [inline]

Send a packet to the session's server node.

Parameters:

packet

the packet.

Definition at line 318 of file session.h.

void eq::net::Session::send	(	NodePtr	node,
		SessionPacket &	packet,
		const void *	data,
		const uint64_t	size
	)			`[inline]`

Send a packet containing additional data to a node.

Parameters:

	node	the target node.
	packet	the packet.
	data	the data to attach to the packet.
	size	the size of the data.

Definition at line 360 of file session.h.

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: