For full featured NPL runtime, one need to use NPL::CNPLRuntime. More...
#include <NPLMiniRuntime.hpp>
Classes | |
| struct | NPLRuntimeState_PtrOps |
| compare functions for runtime state ptr More... | |
Public Types | |
| typedef boost::shared_ptr< typename NPL_STATE > | NPLRuntimeState_ptr |
| typedef std::vector< NPLRuntimeState_ptr > | NPLRuntime_Temp_Pool_Type |
| typedef std::set< NPLRuntimeState_ptr, NPLRuntimeState_PtrOps > | NPLRuntime_Pool_Type |
Public Member Functions | |
| virtual void | Init () |
| initialize NPL runtime environment | |
| virtual void | Run (bool bToEnd=true) |
| call this function regularly in the main game thread to process packages. More... | |
| virtual void | Cleanup () |
| clean up the NPL runtime environment | |
| virtual void | SetHostMainStatesInFrameMove (bool bHostMainStatesInFrameMove) |
| whether we will process messages in the main threads in the frame move function. More... | |
| virtual NPL::INPLRuntimeState * | CreateState (const char *name, NPL::NPLRuntimeStateType type_=NPL::NPLRuntimeStateType_NPL) |
| create a new runtime state. More... | |
| virtual NPL::INPLRuntimeState * | GetState (const char *name=NULL) |
| get a runtime state with an explicit name. More... | |
| virtual NPL::INPLRuntimeState * | CreateGetState (const char *name, NPL::NPLRuntimeStateType type_=NPL::NPLRuntimeStateType_NPL) |
| it get runtime state first, if none exist, it will create one and add it to the main threaded state | |
| virtual bool | DeleteState (NPL::INPLRuntimeState *pRuntime_state) |
| create a given runtime state. More... | |
| virtual NPL::INPLRuntimeState * | GetMainState () |
| get the default (main) runtime state. More... | |
| virtual bool | AddToMainThread (NPL::INPLRuntimeState *runtime_state) |
| add a given runtime state to the main game thread. More... | |
| virtual void | SetUseCompression (bool bCompressIncoming, bool bCompressOutgoing) |
| whether to use compression on transport layer for incoming and outgoing connections More... | |
| virtual void | SetCompressionKey (const byte *sKey=0, int nSize=0, int nUsePlainTextEncoding=0) |
| set the compression method of incoming the outgoing messages. More... | |
| virtual void | SetCompressionLevel (int nLevel) |
| Set the zlib compression level to use in case compression is enabled. More... | |
| virtual int | GetCompressionLevel () |
| virtual void | SetCompressionThreshold (int nThreshold) |
| set the default compression threshold for all connections on this machine. More... | |
| virtual int | GetCompressionThreshold () |
| virtual void | SetTCPKeepAlive (bool bEnable) |
| System level Enable/disable SO_KEEPALIVE. More... | |
| virtual bool | IsTCPKeepAliveEnabled () |
| whether SO_KEEPALIVE is enabled. More... | |
| virtual void | SetKeepAlive (bool bEnable) |
| enable application level keep alive. More... | |
| virtual bool | IsKeepAliveEnabled () |
| virtual void | EnableIdleTimeout (bool bEnable) |
| Enable idle timeout. More... | |
| virtual bool | IsIdleTimeoutEnabled () |
| virtual void | SetIdleTimeoutPeriod (int nMilliseconds) |
| how many milliseconds of inactivity to assume this connection should be timed out. More... | |
| virtual int | GetIdleTimeoutPeriod () |
| virtual void | StartNetServer (const char *server=NULL, const char *port=NULL) |
| start the NPL net server's io_service loop. More... | |
| virtual void | StopNetServer () |
| stop the net server | |
| virtual void | AddPublicFile (const std::string &filename, int nID) |
| add a nID, filename pair to the public file list. More... | |
| virtual void | ClearPublicFiles () |
| clear all public files, so that the NPL server will be completely private. More... | |
| virtual void | GetIP (const char *nid, char *pOutput) |
| get the ip address of given NPL connection. More... | |
| virtual void | accept (const char *tid, const char *nid=NULL) |
| accept a given connection. More... | |
| virtual void | reject (const char *nid, int nReason=0) |
| reject and close a given connection. More... | |
| virtual ParaEngine::INPLJabberClient * | GetJabberClient (const char *sJID) |
| get an existing jabber client instance interface by its JID. More... | |
| virtual ParaEngine::INPLJabberClient * | CreateJabberClient (const char *sJID) |
| Create a new jabber client instance with the given jabber client ID. More... | |
| virtual bool | CloseJabberClient (const char *sJID) |
| close a given jabber client instance. More... | |
| virtual bool | AppendURLRequest (ParaEngine::CURLRequestTask *pUrlTask, const char *sPoolName=NULL) |
| Append URL request to a pool. More... | |
| virtual bool | ChangeRequestPoolSize (const char *sPoolName, int nCount) |
| There is generally no limit to the number of requests sent. More... | |
| virtual void | AsyncDownload (const char *url, const char *destFolder, const char *callbackScript, const char *DownloaderName) |
| Asynchronously download a file from the url. More... | |
| virtual void | CancelDownload (const char *DownloaderName) |
| cancel all asynchronous downloads that matches a certain downloader name pattern More... | |
| virtual int | Download (const char *url, const char *destFolder, const char *callbackScript, const char *DownloaderName) |
| Synchronous call of the function AsyncDownload(). More... | |
| virtual void | NPL_AddDNSRecord (const char *sDNSName, const char *sAddress) |
| add a DNS server record to the current NPL runtime. More... | |
| virtual void | NPL_SetDefaultChannel (int channel_ID) |
| Set the default channel ID, default value is 0. More... | |
| virtual int | NPL_GetDefaultChannel () |
| Get the default channel ID, default value is 0. More... | |
| virtual void | NPL_SetChannelProperty (int channel_ID, int priority, int reliability) |
| Messages can be sent via predefined channels. More... | |
| virtual void | NPL_ResetChannelProperties () |
| reset all 16 predefined channel properties. More... | |
| virtual void | NPL_GetChannelProperty (int channel_ID, int *priority, int *reliability) |
| see also NPL_SetChannelProperty More... | |
| virtual int | Activate (NPL::INPLRuntimeState *pRuntimeState, const char *sNeuronFile, const char *code=NULL, int nLength=0, int channel=0, int priority=2, int reliability=3) |
| activate the specified file. More... | |
| NPLRuntimeState_ptr | CreateRuntimeState (const std::string &name, NPL::NPLRuntimeStateType type_=NPL::NPLRuntimeStateType_NPL) |
| create a new runtime state. More... | |
| NPLRuntimeState_ptr | GetRuntimeState (const std::string &name) |
| get a runtime state with an explicit name. More... | |
| NPLRuntimeState_ptr | CreateGetRuntimeState (const std::string &name, NPL::NPLRuntimeStateType type_=NPL::NPLRuntimeStateType_NPL) |
| it get runtime state first, if none exist, it will create one and add it to the main threaded state | |
| bool | DeleteRuntimeState (NPLRuntimeState_ptr runtime_state) |
| create a given runtime state. More... | |
| NPLRuntimeState_ptr | GetMainRuntimeState () |
| get the default (main) runtime state. More... | |
 Public Member Functions inherited from NPL::INPLRuntime | |
| virtual INPLRuntimeState * | CreateState (const char *name, NPLRuntimeStateType type_=NPLRuntimeStateType_NPL)=0 |
| create a new runtime state. More... | |
| virtual INPLRuntimeState * | CreateGetState (const char *name, NPLRuntimeStateType type_=NPLRuntimeStateType_NPL)=0 |
| it get runtime state first, if none exist, it will create one and add it to the main threaded state | |
Protected Attributes | |
| NPLRuntimeState_ptr | m_runtime_state_main |
| the default (main) NPL runtime state. | |
| NPLRuntime_Pool_Type | m_runtime_states |
| all NPL runtime states in the NPL runtime | |
| NPLRuntime_Temp_Pool_Type | m_temp_rts_pool |
| temporary run time states queue | |
| std::map< std::string, NPLRuntimeState_ptr > | m_active_state_map |
| a mapping from the runtime state name to runtime state instance pointer | |
| ParaEngine::Mutex | m_mutex |
| ParaEngine::Semaphore | m_semaphore |
Detailed Description
template<class NPL_STATE = CNPLMiniState>
class NPLInterface::CNPLMiniRuntimeT< NPL_STATE >
For full featured NPL runtime, one need to use NPL::CNPLRuntime.
Example usage 1: derive your NPLRuntime implementation from CNPLMiniState class CMyNPLStateImp : public CNPLMiniState { public: CMyNPLStateImp(){}; virtual ~CMyNPLStateImp(){}; } define a NPLRuntime that uses your NPL state typedef CNPLMiniRuntimeT<CMyNPLStateImp> CMyNPLRuntime;
Finally create CMyNPLRuntime and call Run() method at regular interval.
Example usage 2: typedef NPLInterface::CNPLMiniRuntimeT<> CNPLMiniRuntime; CNPLMiniRuntime
Member Function Documentation
§ accept()
|
inlinevirtual |
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.
Implements NPL::INPLRuntime.
§ Activate()
|
inlinevirtual |
activate the specified file.
file name is used as message target. [thread safe] This function is thread safe, if and only if pRuntimeState is still valid
- Note
- : pure data table is defined as table consisting of only string, number and other table of the above type. NPL.activate function also accepts ParaFileObject typed message data type. ParaFileObject will be converted to base64 string upon transmission. There are size limit though of 10MB. one can also programmatically check whether a script object is pure date by calling NPL.SerializeToSCode() function. Please note that data types that is not pure data in sCode will be ignored instead of reporting an error.
Implements NPL::INPLRuntime.
§ AddPublicFile()
|
inlinevirtual |
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.
Implements NPL::INPLRuntime.
§ AddToMainThread()
|
inlinevirtual |
add a given runtime state to the main game thread.
this function is thread safe
Implements NPL::INPLRuntime.
§ AppendURLRequest()
|
inlinevirtual |
Append URL request to a pool.
- Parameters
-
pUrlTask must be new CURLRequestTask(), the ownership of the task is transfered to the manager. so the caller should never delete the pointer. sPoolName the request pool name. If the pool does not exist, it will be created. If null, the default pool is used.
Implements NPL::INPLRuntime.
§ AsyncDownload()
|
inlinevirtual |
Asynchronously download a file from the url.
- Parameters
-
callbackScript script code to be called, a global variable called msg is assigned, as below msg = {DownloadState=""|"complete"|"terminated", totalFileSize=number, currentFileSize=number, PercentDone=number}
Implements NPL::INPLRuntime.
§ CancelDownload()
|
inlinevirtual |
cancel all asynchronous downloads that matches a certain downloader name pattern
- Parameters
-
DownloaderName:regular expression. such as "proc1", "proc1.*", ".*"
Implements NPL::INPLRuntime.
§ ChangeRequestPoolSize()
|
inlinevirtual |
There is generally no limit to the number of requests sent.
However, each pool has a specified maximum number of concurrent worker slots. the default number is 1. One can change this number with this function.
Implements NPL::INPLRuntime.
§ ClearPublicFiles()
|
inlinevirtual |
clear all public files, so that the NPL server will be completely private.
[thread safe]
Implements NPL::INPLRuntime.
§ CloseJabberClient()
|
inlinevirtual |
close a given jabber client instance.
Basically, there is no need to close a web service, unless one wants to reopen it with different credentials
- Parameters
-
sJID such as "lixizhi@paraweb3d.com"
Implements NPL::INPLRuntime.
§ CreateJabberClient()
|
inlinevirtual |
Create a new jabber client instance with the given jabber client ID.
It does not open a connection immediately.
- Parameters
-
sJID such as "lixizhi@paraweb3d.com"
Implements NPL::INPLRuntime.
§ CreateRuntimeState()
|
inline |
create a new runtime state.
this function is thread safe
- Parameters
-
name if "", it is an anonymous runtime state. otherwise it should be a unique name. type_ the runtime state type.
- Returns
- the newly created state is returned. If an runtime state with the same non-empty name already exist, the old one is returned.
§ CreateState()
|
inlinevirtual |
create a new runtime state.
this function is thread safe
- Parameters
-
name if "", it is an anonymous runtime state. otherwise it should be a unique name. type_ the runtime state type.
- Returns
- the newly created state is returned. If an runtime state with the same non-empty name already exist, the old one is returned.
§ DeleteRuntimeState()
|
inline |
create a given runtime state.
this function is thread safe
§ DeleteState()
|
inlinevirtual |
§ Download()
|
inlinevirtual |
Synchronous call of the function AsyncDownload().
This function will not return until download is complete or an error occurs. this function is rarely used. AsyncDownload() is used.
- Returns
- :1 if succeed, 0 if fail
Implements NPL::INPLRuntime.
§ EnableIdleTimeout()
|
inlinevirtual |
Enable idle timeout.
This is the application level timeout setting. We will create a global timer which examines all send/receive time of all open connections, if a connection is inactive (idle for GetIdleTimeoutPeriod()) we will
- if IsKeepAliveEnabled() is false, actively close the connection. This is the method used by HTTP, which is the only solution to detect broken connection without sending additional keep alive message.
- if IsKeepAliveEnabled() is true, send an empty message to the other end (keep alive messages) to more accurately detect dead connections (see SetKeepAlive).
Implements NPL::INPLRuntime.
§ GetIP()
|
inlinevirtual |
get the ip address of given NPL connection.
this function is usually called by the server for connected clients.
- Parameters
-
nid nid or tid. pOutPut it must be at least [256] bytes big, that receives the output.
- Returns
- : the ip address in dot format. empty string is returned if connection can not be found.
Implements NPL::INPLRuntime.
§ GetJabberClient()
|
inlinevirtual |
get an existing jabber client instance interface by its JID.
If the client is not created using CreateJabberClient() before, function may return NULL.
- Parameters
-
sJID such as "lixizhi@paraweb3d.com"
Implements NPL::INPLRuntime.
§ GetMainRuntimeState()
|
inline |
get the default (main) runtime state.
§ GetMainState()
|
inlinevirtual |
get the default (main) runtime state.
Implements NPL::INPLRuntime.
§ GetRuntimeState()
|
inline |
get a runtime state with an explicit name.
this function is thread safe
- Parameters
-
name the name of the runtime state. if empty or "main", the main runtime state is returned.
§ GetState()
|
inlinevirtual |
get a runtime state with an explicit name.
this function is thread safe
- Parameters
-
name the name of the runtime state. if NULL or "main", the main runtime state is returned.
Implements NPL::INPLRuntime.
§ IsTCPKeepAliveEnabled()
|
inlinevirtual |
§ NPL_AddDNSRecord()
|
inlinevirtual |
add a DNS server record to the current NPL runtime.
DNS server record is a mapping from name to (IP:port) if one maps several IP:port to the same name, the former ones will be overridden.
- Parameters
-
sDNSName the DNS server name. the DNS name "_world" is used for the current world DNS server. It is commonly used as a DNS reference to the current world that the user is exploring. sAddress "IP:port". e.g. "192.168.1.10:4000"
Implements NPL::INPLRuntime.
§ NPL_GetChannelProperty()
|
inlinevirtual |
see also NPL_SetChannelProperty
- Parameters
-
channel_ID priority [out] reliability [out]
Implements NPL::INPLRuntime.
§ NPL_GetDefaultChannel()
|
inlinevirtual |
Get the default channel ID, default value is 0.
Default channel is used when NPL.activate() call¡¯s does not contain the channel property.
- Returns
- channel_ID It can be a number in [0,15].default is 0
Implements NPL::INPLRuntime.
§ NPL_ResetChannelProperties()
|
inlinevirtual |
reset all 16 predefined channel properties.
according to table1. Default NPL channel properties. see also NPL_SetChannelProperty The following table shows the default NPL channel properties. It is advised for users to stick to this default mapping when developing their own applications. Table 1. Default NPL channel properties channel_ID Priority Reliability Usage 0 med RELIABLE_ORDERED System message 1 med UNRELIABLE_SEQUENCED Character positions 2 med RELIABLE_ORDERED Large Simulation Object transmission, such as terrain height field. 4 med RELIABLE_ORDERED Chat message 14 med RELIABLE files transmission and advertisement 15 med RELIABLE_SEQUENCED Voice transmission 11-15 med RELIABLE_ORDERED
Implements NPL::INPLRuntime.
§ NPL_SetChannelProperty()
|
inlinevirtual |
Messages can be sent via predefined channels.
There are 16 channels from 0 to 15 to be used. 0 is the default channel. This method sets the channel property for a given channel. The default channel property is given in table. The following table shows the default NPL channel properties. It is advised for users to stick to this default mapping when developing their own applications. Table 1. Default NPL channel properties channel_ID Priority Reliability Usage 0 med RELIABLE_ORDERED System message 1 med UNRELIABLE_SEQUENCED Character positions 2 med RELIABLE_ORDERED Large Simulation Object transmission, such as terrain height field. 4 med RELIABLE_ORDERED Chat message 14 med RELIABLE files transmission and advertisement 15 med RELIABLE_SEQUENCED Voice transmission 11-15 med RELIABLE_ORDERED
- Parameters
-
channel_ID priority reliability
Implements NPL::INPLRuntime.
§ NPL_SetDefaultChannel()
|
inlinevirtual |
Set the default channel ID, default value is 0.
Default channel is used when NPL.activate() call¡¯s does not contain the channel property.
- Parameters
-
channel_ID It can be a number in [0,15].default is 0
Implements NPL::INPLRuntime.
§ reject()
|
inlinevirtual |
reject and close a given connection.
The connection will be closed once rejected. [thread safe]
- Parameters
-
nid the temporary id or NID of the connection to be rejected. usually it is from msg.tid or msg.nid.
Implements NPL::INPLRuntime.
§ Run()
|
inlinevirtual |
call this function regularly in the main game thread to process packages.
This function also dispatches messages for the (main) runtime state if it is configured so.
- Parameters
-
bToEnd if true, the function will only return when there is no more input packages in the queue
Implements NPL::INPLRuntime.
§ SetCompressionKey()
|
inlinevirtual |
set the compression method of incoming the outgoing messages.
If this is not called, the default internal key is used for message encoding. [Not Thread Safe]: one must call this function before sending or receiving any encoded messages. so it is usually called when the game engine starts.
- Parameters
-
sKey the byte array of key. the generic key that is used for encoding/decoding nSize size in bytes of the sKey. default is 64 bytes nUsePlainTextEncoding default to 0. if 0, the key is used as it is. if 1, the input key will be modified so that the encoded message looks like plain text(this can be useful to pass some firewalls). if -1, the input key will be modified so that the encoded message is binary.
Implements NPL::INPLRuntime.
§ SetCompressionLevel()
|
inlinevirtual |
Set the zlib compression level to use in case compression 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).
Implements NPL::INPLRuntime.
§ SetCompressionThreshold()
|
inlinevirtual |
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.
Implements NPL::INPLRuntime.
§ SetHostMainStatesInFrameMove()
|
inlinevirtual |
whether we will process messages in the main threads in the frame move function.
It is default to true; However, it is possible for server to set to false, if one wants to have a more responsive main state on the server. For example, it does high-frequency dispatcher jobs, instead of monitoring. But client application, it is only advised to set to true, otherwise the scripting and render modules will be run in different threads, leading to complexity and bugs. : One can only call this function once to set to false. This function is only used by the ParaEngineServer
Implements NPL::INPLRuntime.
§ SetIdleTimeoutPeriod()
|
inlinevirtual |
how many milliseconds of inactivity to assume this connection should be timed out.
if 0 it is never timed out.
Implements NPL::INPLRuntime.
§ SetKeepAlive()
|
inlinevirtual |
enable application level keep alive.
we will use a global idle timer to detect if a connection has been inactive for GetIdleTimeoutPeriod(), if so, we may send the keep alive message.
- Parameters
-
bEnable enable keep alive will automatically enable EnableIdleTimeout()
Implements NPL::INPLRuntime.
§ SetTCPKeepAlive()
|
inlinevirtual |
System level Enable/disable SO_KEEPALIVE.
one needs set following values in linux procfs or windows registry in order to work as expected.
- tcp_keepalive_intvl (integer; default: 75) The number of seconds between TCP keep-alive probes.
- tcp_keepalive_probes (integer; default: 9) The maximum number of TCP keep-alive probes to send before giving up and killing the connection if no response is obtained from the other end.
- tcp_keepalive_time (integer; default: 7200) The number of seconds a connection needs to be idle before TCP begins sending out keep-alive probes. Keep-alives are only sent when the SO_KEEPALIVE socket option is enabled. The default value is 7200 seconds (2 hours). An idle connection is terminated after approximately an additional 11 minutes (9 probes an interval of 75 seconds apart) when keep-alive is enabled. Note that underlying connection tracking mechanisms and application timeouts may be much shorter. Use the default system level TCP keep alive setting for this socket. Please see TCP keep alive for more information. It can be used to solve the "half-open connection". it is arguable whether to use protocol level keep alive or implement it in the application level.
- Parameters
-
bEnable true to enable.
Implements NPL::INPLRuntime.
§ SetUseCompression()
|
inlinevirtual |
whether to use compression on transport layer for incoming and outgoing connections
- Parameters
-
bCompressIncoming if true, compression is used for all incoming connections. default to false. bCompressIncoming if true, compression is used for all outgoing connections. default to false.
Implements NPL::INPLRuntime.
§ StartNetServer()
|
inlinevirtual |
start the NPL net server's io_service loop.
This function returns immediately. it will spawn the accept and dispatcher thread. call this function only once per process.
- Parameters
-
server default to "127.0.0.1" port default to "60001"
Implements NPL::INPLRuntime.
The documentation for this class was generated from the following file:
- Client/trunk/ParaEngineClient/Core/NPLMiniRuntime.hpp
