This chapter describes NEX initialization settings.
NEX gives you the flexibility of choosing a threading model according to your game's specifications.
NEX is designed to perform internal processing and send and receive packets by periodically executing the Scheduler::Dispatch
function. Taking into account the CPU load and blocking time of the Scheduler::Dispatch
function, We recommend using a thread-unsafe transport buffer thread mode.
We recommend the following NEX settings and usage of other API functions. These settings generally make NEX run in a single thread, eliminating wasteful locking and minimizing the CPU load. Use these settings unless you have a specific reason not to do so.
Core::SetThreadMode
(Core::ThreadModeUnsafeTransportBuffer
)Scheduler::Dispatch
or the Scheduler::DispatchAll
function at the beginning and end of the frame.Note
Because operating system processes for sending and receiving packets block for several milliseconds, processing for sending and receiving packets through the operating system API are handled in separate threads to lessen the effect of extended blocking inside Scheduler::Dispatch
. Under NEX, such threads are called transport buffer threads.
The transport buffer thread never manipulates memory, because NEX allocates the memory that the thread requires before starting it. Also, NEX and the transport buffer thread are exclusive of each other regardless of the thread mode.
The Core::SetThreadMode
function is an easy way to configure the thread mode for the NEX library. There are two thread mode settings: ThreadModeUnsafeTransportBuffer
and hreadModeSafeTransportBuffer
.
ThreadModeUndefined
This undefined value is used as the initial value.
ThreadModeUnsafeTransportBuffer
The application must periodically execute the
Scheduler::Dispatch
function. The transport buffer thread starts.The CPU load is low because exclusive control (
CriticalSection
) inside NEX other than that with the transport buffer thread is disabled. You must either use all NEX API functions from the same thread or locking in the application, as appropriate. You can use a fast, thread-unsafe memory allocator.
ThreadModeSafeTransportBuffer
The application must periodically execute the
Scheduler::Dispatch
function. The transport buffer thread starts.The CPU load is higher because exclusive control (
CriticalSection
) inside NEX is enabled.You must use a thread-safe memory allocator when you are executing the
Scheduler::Dispatch
function and running duplicated object operations in another thread and exclusive control obtained by theScheduler::SystemLock
function in the application is required.
ThreadModeUnsafeUser
The application must periodically execute the
Scheduler::Dispatch
function. The socket calls in theScheduler::Dispatch
function can block for several milliseconds. Call theScheduler::Dispatch
function from a thread other than the main thread.The CPU load is low because exclusive control (
CriticalSection
) inside NEX is disabled. You must either use all NEX API functions from the same thread or locking in the application, as appropriate. You can use a fast, thread-unsafe memory allocator.
Scheduler::SystemLock
In addition to a thread-safe setting (ThreadModeSafeTransportBuffer
), exclusive control is also required to get Scheduler::SystemLock
when getting or setting duplicated object parameters from another thread calling Scheduler::Dispatch
.
Scheduler::SystemLock
The following sample code shows how to get a list of stations.
Code 4.1 Example of NEX Locking by Application
{
// The application must perform locking as follows. because it accesses the duplicated object directly.
ScopedCS oCS(Scheduler::GetInstance()->SystemLock());
for (nn::nex::Station::SelectionIterator station;!station.EndReached();++station)
{
if (!station->IsLocal())
{
// Perform on `Station` objects other than self.
}
}
}
Warning
Because Station::SelectionIterator
is failsafe, an assertion results when initialization is performed without executing the Scheduler::GetInstance
function followed by the SystemLock
function.
Scheduler::SystemLock
The following API function must be excluded using Scheduler::SystemLock()
.
Station
Class API (excluding the Station::ConvertStationIDToDOHandle
, Station::ConvertConnectionIDToDOHandle
, Station::ConvertDOHandleToStationID
, Station::ConvertDOHandleToDOID
, Station::ConvertDOHandleToID
, and Station::KickMe
functions)DuplicatedObject
class API functionsDOHandle::IsAKindOf()
, DOHandle::GetClassNameString()
, and DOHandle::GetDatasetNameString()
WKHandle::IsAKindOf()
, WKHandle::GetClassNameString()
, and WKHandle::GetDatasetNameString()
DORef
classDataSet
class API functionsPromotionReferee
class API functionsSessionClock
class API functions (except the SessionClock::GetTime
function)Session::RegisterJoinApprovalCallback()
IteratorOverDOs
class APIs and all SelectionIterator
(SelectionIteratorTemplate
instance classes)StreamSettings
class API functions. (Not required when used only during initialization. Not required for the StreamSettings::GetBundling
function.)Scheduler::SystemLock
The following duplicated object-related API functions do not require exclusion using Scheduler::SystemLock()
. DirectStream
, NetZ, and API functions unrelated to duplicated objects, such as Core
, do not require exclusion using Scheduler::SystemLock()
.
Station::ConvertStationIDToDOHandle, Station::ConvertConnectionIDToDOHandle, Station::ConvertDOHandleToStationID, Station::ConvertDOHandleToDOID, Station::ConvertDOHandleToID
DOHandle::GetValue()
, DOHandle::IsAWKHandle()
, DOHandle::IsACoreDO()
, and DOHandle::IsAUserDO()
DOHandle::GetDOID()
, DOHandle::GetDOClassID()
, and DOHandle::IsA()
WKHandle::GetValue()
, WKHandle::IsAWKHandle()
, WKHandle::IsACoreDO()
, and WKHandle::IsAUserDO()
WKHandle::GetDOID()
, WKHandle::GetDOClassID()
, and WKHandle::IsA()
SessionClock::GetTime()
Session
class API functions (except Session::RegisterJoinApprovalCallback()
)Operation
-related callback processing, such as JoinSessionOperation
Station::KickMe
The following functions cannot be called from multiple threads simultaneously. Do not simultaneously call two or more of the following functions or any combination thereof across all threads.
Either the nn::os::Thread::TryStartUsingAutoStack
or the nn::os::Thread::TryStart
function is used when generating threads. The nn::os::Thread::TryStartUsingAutoStack
function is used only when true
has been specified for the argument of the nn::nex::Core::UseThreadAutoStack
function.
Use the nn::os::Thread::TryStart
function when the nn::nex::Core::UseThreadAutoStack
function has not been called, or the argument of the nn::nex::Core::UseThreadAutoStack
function has been set to false
. In this case, the NEX library provides a thread stack that uses the memory-allocation functions registered using the nn::nex::MemoryManager::SetBasicMemoryFunctions
function.
nn::os::Thread::TryStartUsingAutoStack
: 28 KBnn::os::Thread::TryStart
: 28 KB (Approximately 32 KB (32 KB - 1 byte) of memory is actually allocated)The local communication link feature enables NetZ operations on other networks. By using the NetZ linked features in the Pia library, NetZ can be operated over a local communications network. This feature enables you to standardize applications that use local P2P communication and applications that use Internet P2P communication.
For more information, see the PiaLocal
section in the Pia Programming Manual.
CONFIDENTIAL