this class serves as an interface between the low level socket interface and NPL message queues. More...

#include <NPLDispatcher.h>

Public Member Functions
	CNPLDispatcher (CNPLNetServer *server)

CNPLNetServer *	GetNetServer ()
	the NPL Net server object. More...

void	Cleanup ()
	clean up all resources

NPLConnection_ptr	CreateGetNPLConnectionByNID (const string &sNID)
	Get the NPL connection object by a given NID. More...

NPLConnection_ptr	GetNPLConnectionByNID (const string &sNID)
	same as CreateGetNPLConnectionByNID(), except that the returned connection object may be null, if no sNID matches. More...

void	AddNPLConnection (const string &sNID, NPLConnection_ptr pConnection)
	A a new NPL connection to the m_active_connection_map. More...

bool	RemoveNPLConnection (NPLConnection_ptr pConnection)
	remove a given connection object from the active or pending connection map if any. More...

void	NPL_accept (const char tid, const char nid=NULL)
	accept a given connection. More...

void	NPL_SetProtocol (const char *nid, CNPLConnection::ProtocolType protocolType=CNPLConnection::ProtocolType::NPL)
	set transmission protocol, default value is 0. More...

void	RenameConnection (NPLConnection_ptr pConnection, const char *sNid)
	rename a given connection. More...

NPLReturnCode	Activate_Async (const NPLFileName &file_name, const char *code=NULL, int nLength=0, int priority=0)
	Activate the specified remote file. More...

NPLReturnCode	DispatchMsg (NPLMsgIn &msg)
	Dispatch a message from a given socket connection to a local NPL runtime state. More...

bool	AddNPLRuntimeAddress (NPLRuntimeAddress_ptr pAddress)
	add a given NPL runtime address to the fully trusted server addresses list. More...

NPLRuntimeAddress_ptr	GetNPLRuntimeAddress (const string &sNID)
	check to see if a given NID is trusted by the dispatcher. More...

void	AddPublicFile (const string &filename, int nID)
	add a nID, filename pair to the public file list. More...

void	ClearPublicFiles ()
	clear all public files, so that the NPL server will be completely private. More...

bool	GetPubFileNameByID (string &filename, int nID)
	get a public file name by its id in the public filename map [thread safe] More...

bool	CheckPubFile (string &filename, int &nID)
	return true if either filename or nID is in the public file list. More...

int	GetIDByPubFileName (const string &sString)
	get id by filename string in the public filename map [thread safe] More...

int	PostNetworkEvent (NPLReturnCode nNPLNetworkCode, const char sNid=NULL, const char sMsg=NULL)
	post network event It will post network message as {code=nNPLNetworkCode, nid=string, msg=string} More...

void	SetUseCompressionIncomingConnection (bool bCompressIncoming)
	whether to use compression on transport layer for incoming connections More...

bool	IsUseCompressionIncomingConnection ()

void	SetUseCompressionOutgoingConnection (bool bCompressOutgoing)
	whether to use compression on transport layer for outgoing connections More...

bool	IsUseCompressionOutgoingConnection ()

void	SetCompressionLevel (int nLevel)
	Set the zlib compression level to use in case compresssion is enabled. More...

int	GetCompressionLevel ()

void	SetCompressionThreshold (int nThreshold)
	set the default compression threshold for all connections on this machine. More...

int	GetCompressionThreshold ()

Protected Types
typedef std::map< string, NPLConnection_ptr >	ActiveConnectionMap_Type

typedef std::map< string, NPLRuntimeAddress_ptr >	ServerAddressMap_Type

typedef boost::bimap< int, std::string >	StringBimap_Type

Protected Member Functions
NPLConnection_ptr	CreateConnection (NPLRuntimeAddress_ptr pAddress)
	Create a new connection with a remote server and immediately connect and start the connection. More...

void	RenameConnectionImp (NPLConnection_ptr pConnection, const char *sNid)
	not thread safe. More...

Protected Attributes
ActiveConnectionMap_Type	m_active_connection_map
	a mapping from the authenticated NPL runtime id (NID) to its associated NPL connection. More...

ActiveConnectionMap_Type	m_pending_connection_map
	a mapping from the not connected or authenticated NPL runtime id (NID) to its associated NPL connection. More...

ServerAddressMap_Type	m_server_address_map
	a mapping from the NPL runtime id (NID) to its full NPLRuntimeAddress. More...

ParaEngine::mutex	m_mutex
	provide thread safe access to shared data members in this class. More...

bool	m_bUseCompressionIncomingConnection
	whether to use compression on transport layer for incoming connections

bool	m_bUseCompressionOutgoingConnection
	whether to use compression on transport layer for outgoing connections

int	m_nCompressionLevel
	zlib compression level to use in case compresssion is enabled. More...

int	m_nCompressionThreshold
	when msg is larger than this, we will compress it. More...

StringBimap_Type	m_public_filemap
	only files in the public file map can be activated remotely. More...

CNPLNetServer *	m_pServer
	the server object

Detailed Description

this class serves as an interface between the low level socket interface and NPL message queues.

when a socket connection receives an NPL message, it calls the NPLDispatcher to put messages to the correct NPL runtime state's input queue and inform the handler thread.
When the local NPL runtime sends an NPL message, the NPLDispatcher will create get a connection object that represents the target and then sends out the message.
when a NPL server accepts a new connection, it will add a new connection to the dispatcher with their sNID.

all handler_xxx functions are called from the dispatcher thread. the dispatching thread is an asynchronous io service for dispatching all messages of all sockets.

Member Function Documentation

§ Activate_Async()

NPL::NPLReturnCode NPL::CNPLDispatcher::Activate_Async	(	const NPLFileName &	file_name,
		const char *	code = `NULL`,
		int	nLength = `0`,
		int	priority = `0`
	)

Activate the specified remote file.

This function is called by CNPLRuntime::NPL_Activate

Parameters

runtime_state	the runtime environment
file_name	the full qualified remote file name
code	it is a chunk of pure data table init code that would be transmitted to the destination file.
nLength	the code length. if this is 0, length is determined from code by finding '\0',
priority	if 0 it is normal priority. if 1 it will be inserted to the front of the message queue.

Returns: if failed, such as the runtime state does not exist, etc.

§ AddNPLConnection()

void NPL::CNPLDispatcher::AddNPLConnection	(	const string &	sNID,
		NPLConnection_ptr	pConnection
	)

A a new NPL connection to the m_active_connection_map.

it also removes from the pending connection map if any. if there is already a connection with the same name, the previous one will be silently removed. This function is called by the ConnectionManager, when it has accepted a new incoming connection. [thread safe]

Parameters

sNID	the sNID of the connection.
pConnection	if pConnection is not connected, this function does nothing.

§ AddNPLRuntimeAddress()

bool NPL::CNPLDispatcher::AddNPLRuntimeAddress ( NPLRuntimeAddress_ptr pAddress )

add a given NPL runtime address to the fully trusted server addresses list.

[thread safe]

§ AddPublicFile()

void NPL::CNPLDispatcher::AddPublicFile	(	const string &	filename,
		int	nID
	)

add a nID, filename pair to the public file list.

we only allow remote NPL runtime to activate files in the public file list. Each public file has a user defined ID. The NPL network layer always try to use its ID for transmission to minimize bandwidth. There are some negotiations between sender and receiver to sync the string to ID map before they use it. [thread safe]

Parameters

nID	the integer to encode the string. it is usually small and positive number.
sString	the string for the id. if input is empty, it means removing the mapping of nID.

§ CheckPubFile()

bool NPL::CNPLDispatcher::CheckPubFile	(	string &	filename,
		int &	nID
	)

return true if either filename or nID is in the public file list.

[thread safe]

§ ClearPublicFiles()

void NPL::CNPLDispatcher::ClearPublicFiles ( )

clear all public files, so that the NPL server will be completely private.

[thread safe]

§ CreateConnection()

NPL::NPLConnection_ptr NPL::CNPLDispatcher::CreateConnection ( NPLRuntimeAddress_ptr pAddress )

protected

Create a new connection with a remote server and immediately connect and start the connection.

[Thread Safe]

Parameters

pAddress the target NPL runtime address to connect to.

Returns: The function returns immediately, so the returned connection may not have been connected or authenticated yet.

§ CreateGetNPLConnectionByNID()

NPL::NPLConnection_ptr NPL::CNPLDispatcher::CreateGetNPLConnectionByNID ( const string & sNID )

Get the NPL connection object by a given NID.

if the NID does not match a connection,a new connection object will be created and immediately returned. Please note that this function will always return a NPLConnection object. For newly created connection object, it may not even been connected or authenticated and all messages to it are cached in the output (pending) queue. [thread safe]

Parameters

sNID this is the sNID in NPLFileName. Please see NPLFileName for more details. It usually represents a network endpoint (IP/port). However, instead of using IP address "192.168.0.111/60001", we usually use email like addresses, like "1001@paraengine.com" the email address will latter be resolved to IP/port. if empty, it means the local runtime environment. Specially, "all@local" means all remote NIDs connecting to this local machine.

Note: : it is possible that multiple forms of sNID matches to the same NPL connection.

§ DispatchMsg()

NPL::NPLReturnCode NPL::CNPLDispatcher::DispatchMsg ( NPLMsgIn & msg )

Dispatch a message from a given socket connection to a local NPL runtime state.

This function is called by the connection object's data handler whenever a message is received from the network layer. This function just parse and insert message to a proper NPL runtime state's input queue and returns immediately.

Note: : this function is similar to Activate_Async, except that it takes input from a network message and always dispatched to a local runtime state.

Returns: if failed, such as the runtime state does not exist, etc.

§ GetIDByPubFileName()

int NPL::CNPLDispatcher::GetIDByPubFileName ( const string & sString )

get id by filename string in the public filename map [thread safe]

Returns: -1 if not found

§ GetNetServer()

CNPLNetServer* NPL::CNPLDispatcher::GetNetServer ( )

inline

the NPL Net server object.

§ GetNPLConnectionByNID()

NPL::NPLConnection_ptr NPL::CNPLDispatcher::GetNPLConnectionByNID ( const string & sNID )

same as CreateGetNPLConnectionByNID(), except that the returned connection object may be null, if no sNID matches.

[thread safe]

§ GetNPLRuntimeAddress()

NPL::NPLRuntimeAddress_ptr NPL::CNPLDispatcher::GetNPLRuntimeAddress ( const string & sNID )

check to see if a given NID is trusted by the dispatcher.

if so, return its address. [thread safe]

§ GetPubFileNameByID()

bool NPL::CNPLDispatcher::GetPubFileNameByID	(	string &	filename,
		int	nID
	)

get a public file name by its id in the public filename map [thread safe]

Returns: false if not found

§ NPL_accept()

void NPL::CNPLDispatcher::NPL_accept	(	const char *	tid,
		const char *	nid = `NULL`
	)

accept a given connection.

The connection will be regarded as authenticated once accepted. [thread safe]

Parameters

tid	the temporary id or NID of the connection to be accepted. usually it is from msg.tid or msg.nid.
nid	if this is not nil, tid will be renamed to nid after accepted.

§ NPL_SetProtocol()

void NPL::CNPLDispatcher::NPL_SetProtocol	(	const char *	nid,
		CNPLConnection::ProtocolType	protocolType = `CNPLConnection::ProtocolType::NPL`
	)

set transmission protocol, default value is 0.

§ PostNetworkEvent()

int NPL::CNPLDispatcher::PostNetworkEvent	(	NPLReturnCode	nNPLNetworkCode,
		const char *	sNid = `NULL`,
		const char *	sMsg = `NULL`
	)

post network event It will post network message as {code=nNPLNetworkCode, nid=string, msg=string}

Parameters

nNPLNetworkCode	one of the NPLReturnCode.
sNid	connection nid that sends this request. Can be NULL.
sMsg	a string message. Can be NULL.

§ RemoveNPLConnection()

bool NPL::CNPLDispatcher::RemoveNPLConnection ( NPLConnection_ptr pConnection )

remove a given connection object from the active or pending connection map if any.

This function is called automatically by the NPLConnection object when the connection is closed. [thread safe]

Returns: true if connection is found and removed. false if connection is not found.

§ RenameConnection()

void NPL::CNPLDispatcher::RenameConnection	(	NPLConnection_ptr	pConnection,
		const char *	sNid
	)

rename a given connection.

this is called by SetNid() and its function is same as NPL_accept. [thread safe]

Parameters

tid	the temporary id or NID of the connection to be accepted. usually it is from msg.tid or msg.nid.
nid	if this is not nil, tid will be renamed to nid after accepted.

§ RenameConnectionImp()

void NPL::CNPLDispatcher::RenameConnectionImp	(	NPLConnection_ptr	pConnection,
		const char *	sNid
	)

protected

not thread safe.

please see RenameConnection().

§ SetCompressionLevel()

void NPL::CNPLDispatcher::SetCompressionLevel ( int nLevel )

Set the zlib compression level to use in case compresssion is enabled.

default to 0, which means no compression. Compression level, which is an integer in the range of -1 to 9. Lower compression levels result in faster execution, but less compression. Higher levels result in greater compression, but slower execution. The zlib constant Z_DEFAULT_COMPRESSION, equal to -1, provides a good compromise between compression and speed and is equivalent to level 6. Level 0 actually does no compression at all, and in fact expands the data slightly to produce the zlib format (it is not a byte-for-byte copy of the input).

§ SetCompressionThreshold()

void NPL::CNPLDispatcher::SetCompressionThreshold ( int nThreshold )

set the default compression threshold for all connections on this machine.

when the message size is bigger than this number of bytes, we will use m_nCompressionLevel for compression. For message smaller than the threshold, we will not compress even m_nCompressionLevel is not 0.

§ SetUseCompressionIncomingConnection()

void NPL::CNPLDispatcher::SetUseCompressionIncomingConnection ( bool bCompressIncoming )

whether to use compression on transport layer for incoming connections

Parameters

bCompressIncoming if true, compression is used for all incoming connections. default to false.

§ SetUseCompressionOutgoingConnection()

void NPL::CNPLDispatcher::SetUseCompressionOutgoingConnection ( bool bCompressOutgoing )

whether to use compression on transport layer for outgoing connections

Parameters

bCompressIncoming if true, compression is used for all outgoing connections. default to false.

Member Data Documentation

§ m_active_connection_map

ActiveConnectionMap_Type NPL::CNPLDispatcher::m_active_connection_map

protected

a mapping from the authenticated NPL runtime id (NID) to its associated NPL connection.

§ m_mutex

ParaEngine::mutex NPL::CNPLDispatcher::m_mutex

protected

provide thread safe access to shared data members in this class.

Note: : a simple critical section mutex is better than boost::shared_mutex (read_write_lock), since we only lock a few cycles within spin count.

§ m_nCompressionLevel

int NPL::CNPLDispatcher::m_nCompressionLevel

protected

zlib compression level to use in case compresssion is enabled.

§ m_nCompressionThreshold

int NPL::CNPLDispatcher::m_nCompressionThreshold

protected

when msg is larger than this, we will compress it.

§ m_pending_connection_map

ActiveConnectionMap_Type NPL::CNPLDispatcher::m_pending_connection_map

protected

a mapping from the not connected or authenticated NPL runtime id (NID) to its associated NPL connection.

§ m_public_filemap

StringBimap_Type NPL::CNPLDispatcher::m_public_filemap

protected

only files in the public file map can be activated remotely.

bidirectional map between file id and filename.

§ m_server_address_map

ServerAddressMap_Type NPL::CNPLDispatcher::m_server_address_map

protected

a mapping from the NPL runtime id (NID) to its full NPLRuntimeAddress.

NPL runtime addresses in this set are fully trusted by the dispatcher. The dispatcher will automatically establish connections to those addresses if any no existing connection is available.

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

Client/trunk/ParaEngineClient/NPL/NPLDispatcher.h
Client/trunk/ParaEngineClient/NPL/NPLDispatcher.cpp

Public Member Functions

Protected Types

Protected Member Functions

Protected Attributes

Detailed Description

Member Function Documentation

§ Activate_Async()

§ AddNPLConnection()

§ AddNPLRuntimeAddress()

§ AddPublicFile()

§ CheckPubFile()

§ ClearPublicFiles()

§ CreateConnection()

§ CreateGetNPLConnectionByNID()

§ DispatchMsg()

§ GetIDByPubFileName()

§ GetNetServer()

§ GetNPLConnectionByNID()

§ GetNPLRuntimeAddress()

§ GetPubFileNameByID()

§ NPL_accept()

§ NPL_SetProtocol()

§ PostNetworkEvent()

§ RemoveNPLConnection()

§ RenameConnection()

§ RenameConnectionImp()

§ SetCompressionLevel()

§ SetCompressionThreshold()

§ SetUseCompressionIncomingConnection()

§ SetUseCompressionOutgoingConnection()

Member Data Documentation

§ m_active_connection_map

§ m_mutex

§ m_nCompressionLevel

§ m_nCompressionThreshold

§ m_pending_connection_map

§ m_public_filemap

§ m_server_address_map