3. NetZ Initialization and Finalization

3.1. NetZ Initialization

To initialize NetZ, a NetZ instance is generated. A NetZ instance must be created for each session.

Note that even when the Session::CreateSession and Session::JoinSession functions described in Chapter 5 have failed, you still must re-create the NetZ instance to join a session again.

When using NetZ with Internet communications, you must initialize the NAT transversal feature separately. For the initialization method to use, see P2P Communications in Server Services.

3.2. NetZ Finalization

To finalize NetZ, call the NetZ::Terminate function and destroy the NetZ instance.

It may take up to five seconds for the NetZ::Terminate function to complete the process, depending on the communication environment. Avoid any implementation that causes your application to freeze without updating screen rendering during that time. Note that if an attempt is made to destroy a NetZ instance without calling the NetZ::Terminate function, the destructor internally calls the NetZ::Terminate function and blocks other processing until finalization is complete.

Code 3.1 Calling the Non-blocking NetZ::Terminate Using CallContext

CallContext cc;
NetZ::GetInstance()->Terminate(&cc);
while (1) {
    // Processing by the application.
    SampleAppUpdate();
    // Run NEX processing.
    Scheduler::GetInstance()->DispatchAll();
    // Check if NetZ::Terminate has completed.
    if (cc.GetState() == CallContext::CallInProgress) {
        continue;
    }
    break;
}

Warning

The NetZ::Terminate function destroys duplicated objects. Even references remaining in the application are destroyed. Make sure that references to duplicated objects are not made after the NetZ::Terminate function terminates. Always release references to all duplicated objects before calling the NetZ::Terminate function.

3.3. Migration of Duplicated Objects

Duplicated objects for which the local station is the duplication master are migrated to the other stations when you call the NetZ::Terminate function. Migration time, which can take up to 4.2 seconds, is the primary reason for the processing time required by the NetZ::Terminate function.

If connectivity is poor, migration may be impossible within this time. In such cases, NetZ is finalized without migration. Migration is not guaranteed if normal communication with the remote station is unavailable because of connectivity issues.

Make sure to enable fault recovery for duplicated objects as necessary, so that the duplication master for duplicated objects can be selected among other stations. For more information about duplicated object fault recovery, see Section 11.8 Fault Tolerance.

3.4. Processing Time

Other than migration, the time required for processing is about one second. When migration is also considered, the NetZ::Terminate function takes up to 5.2 seconds to execute. These times assume that there is no other processing load other than NEX.

While waiting for the NetZ::Terminate function to complete, display graphics indicating that it is processing and avoid any implementation that causes your application to freeze without updating screen rendering during that time.

Execution terminates in about one second if there are no duplicated objects representing the duplication master, or if migration completes quickly. Execution also terminates in about one second when using forced termination mode, described in the following section.

3.5. Forced Termination Mode

To execute NetZ::Terminate quickly, use NetZ::SetTerminateImmediately to set forced termination mode under conditions when you do not need to migrate host or master privileges to another station.

Execution terminates in about one second when using forced termination mode. However, because a standard disconnection network from the network is not performed, the local station sometimes appears to be disconnected from the network (from the perspective of other peers) because of a keep-alive timeout. Refrain from this technique during a standard finalization sequence.

NetZ::SetTerminateImmediately() results in forced termination mode under the following conditions.

  • When a session is terminated because the host called the Session::GameOver function.
  • When the local system is not the host, and a call to Session::GameOver() on the host is received, and Session::CheckGameIsOver() returns true.
  • When a station leaves the session by calling Session::DestroySession() when a station is clearly disconnected from the network or there are no stations other than the local station.

Warning

Be careful when you use Session::DestroySession() because it can be used only under limited conditions. To forcibly terminate a peer-to-peer session that includes parent and child nodes, use the Session::GameOver function.

For more information about Session::GameOver, see the API reference.

Forced termination mode is maintained for each NetZ instance. The default termination mode is normal termination.


CONFIDENTIAL