eq::net::Session Class Reference

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:

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=Object::VERSION_OLDEST)

Map a distributed object.

uint32_t mapObjectNB (Object *object, const uint32_t id, const uint32_t version=Object::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.

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

Constructor & Destructor Documentation

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

Construct a new session.

Definition at line 42 of file session.cpp.

References EQINFO.

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

Destruct this session.

Definition at line 52 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 55 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::net::ObjectInstanceDataOStream::sendBuffer(), eq::net::ObjectDeltaDataOStream::sendBuffer(), eq::Config::sendEvent(), eq::net::ObjectInstanceDataOStream::sendFooter(), eq::net::ObjectDeltaDataOStream::sendFooter(), 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 61 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 98 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 71 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 490 of file session.cpp.

References EQVERB, eq::net::Command::getPacket(), and eq::net::Command::isValid().

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

References eq::net::COMMAND_ERROR, EQVERB, EQWARN, and eq::net::Command::isValid().

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

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

Referenced by eq::net::Object::becomeMaster(), eq::server::Frame::cycleData(), eq::server::Node::getBarrier(), eq::server::Config::getDistributorID(), 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 475 of file session.cpp.

References EQLOG, freeIDs(), and unmapObject().

Referenced by eq::Observer::deregister(), eq::Layout::deregister(), eq::Canvas::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 = `Object::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 334 of file session.cpp.

References mapObjectNB(), and mapObjectSync().

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

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 = `Object::VERSION_OLDEST`
	)

Start mapping a distributed object.

Definition at line 341 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 382 of file session.cpp.

References _requestHandler, EQLOG, eq::base::RequestHandler::getRequestData(), eq::net::Object::isMaster(), 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 412 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(), eqPly::Pipe::configExit(), eq::Layout::deregister(), deregisterObject(), eq::Pipe::flushFrames(), 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:

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

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

Here is the call graph for this function:

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

Detach an object.

Parameters:

object

the attached object.

Definition at line 291 of file session.cpp.

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

Referenced by unmapObject().

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, and eq::server::Config.

Definition at line 107 of file session.cpp.

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

Here is the call graph for this function:

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

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

Referenced by eq::Config::exit(), eq::Config::finishAllFrames(), eq::Config::freezeLoadBalancing(), genIDs(), getIDMaster(), eq::Config::init(), eq::Config::startFrame(), eq::server::Config::unmap(), and unmapObject().

Here is the caller graph for this function:

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

Send a packet to the session's server node.

Parameters:

packet

the packet.

Definition at line 303 of file session.h.

template<typename T >

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

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

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

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

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

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

Member Data Documentation

base::RequestHandler eq::net::Session::_requestHandler [protected]

Registers request for packets awaiting a return value.

Definition at line 354 of file session.h.

Referenced by attachObject(), detachObject(), eq::Config::exit(), genIDs(), getIDMaster(), eq::Config::init(), mapObjectNB(), mapObjectSync(), eq::server::Config::unmap(), and unmapObject().

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


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=Object::VERSION_OLDEST)
	Map a distributed object.
uint32_t	mapObjectNB (Object *object, const uint32_t id, const uint32_t version=Object::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.
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.