6.9. Basic Features - Host Migration

This chapter describes the host migration feature.

You can use the host migration feature with PiaSession to maintain the session when the host leaves. With this feature, when the host leaves the session, authority is transferred to one of the remaining clients, making it the new session host and keeping the session active.

Configuring Host Migration

You can change whether host migration is used by setting the bUsingHostMigration member of Session::StartupSetting to true or false.

Selecting the Next Host

Two methods are available for selecting the next host in host migration: single-candidate mode and multiple-candidate mode. The features of each mode are as follows.

Single-Candidate Mode
  • When host migration occurs, the system selects one client as the candidate to be the next host.
  • If the next host candidate disconnects after host migration begins, host migration fails for all clients.
Multiple-Candidate Mode
  • When host migration occurs, the system ranks each client as a candidate for the next host.
  • Host migration can succeed even if the top candidate for the next host disconnects after host migration begins because the system selects the next candidate in the ranking.

The next host is selected using single-candidate mode for local communication and multiple-candidate mode for Internet communication.

Host Leaving Without Destroying the Session

The host can leave the session without destroying it only when host migration is used. The process for leaving the session is identical to 6.8. Basic Features - Leaving Sessions.

When the host calls the function for leaving the session, the remaining clients start host migration and determine the next host.

State Change Events That Only Occur When Using Host Migration

When using host migration, events occur that notify the results of the host migration process. The notifications are: "Change of host due to host migration" and "Host migration failure."

Code 6-20. State Change Event Callback Function
// Sample state change event callback function.
void sampleSessionEventCallback( nn::pia::session::Session::EventType eventType, nn::pia::StationId id )
{
    // The eventType argument is an enumerated type that indicates the content of the state change that occurred.
    // The id argument is the StationId that indicates the target of the state change that occurred.
    switch( eventType )
    {
    case nn::pia::session::Session::EVENT_JOIN:
        {
            // When the station assigned the id joined.
        }break;
    case nn::pia::session::Session::EVENT_LEAVE:
        {
            // When the station assigned the id left.
        }break;
    case nn::pia::session::Session::EVENT_SESSION_HOST_CHANGED: // Note: Event only used for host migration.
        {
            // When the id station becomes the new session host due to host migration.
        }break;
    case nn::pia::session::Session::EVENT_HOST_MIGRATION_FAILED: // Note: Event only used for host migration.
        {
            // When the host migration process fails.
            // For this event, the id argument becomes STATION_ID_INVALID.
        }break;
    }
}