ClientMigration

Client migration

Overview

Since the Snipe server core supports multiple slave server threads of execution for any meta-server sometimes you will need to migrate the clients from one thread to another, for example, in the case of them joining a game round while being on different threads. The core provides two options for client migration. The first one is the heavy one: the logged in client logs out on the server, then switches the thread and logs back in. You can imagine that this is a pretty heavy operation but it is the only way to ensure the process result in the cleanest way possible. The second one is lightweight: with the login message the client can supply the slave server thread ID that it wants to migrate to. In this case the client has not yet logged into the server, so the process is much faster and smoother - switch the thread and run the actual login procedure. In both cases the client will not notice anything and the socket will remain connected.

Manual client migration

The manual client migration is potentially the heavy one since the client has already logged into the game (you can also manually migrate the clients that have not yet logged in). It is done through the use of "Server.migrateClient()" API call. The migration will be treated by higher-level code as the new client session - all of the login and logout hooks will run, the blocks will be updated, unlocked and then locked again, etc. It is not recommended to run multiple migrations for the same client in very quick succession since that might result in dropped client messages.

Note also that the client message handling order of the messages that accumulated during the migration process is not guaranteed. If the migration process is started from the client message handling method (called from "Module.call()"), the client response from that method will be ignored due to the start of migration.

Here is the example code (also used in the Extended Matchmaking package):

// NOTIFY: start the client migration
  function migrate(msg: { id: Int, id2: Int, serverID: Int })
    {
      var c = server.getClient(msg.id, true);
      if (c == null)
        return;

      // start the client migration
      server.migrateClient(c, msg.serverID, msg, "game.migratePost");
    }


// HOOK: post-client migration, find the game and join it
  function migratePost(c: Client, msg: { id2: Int })
    {
      var c2 = server.getClient(msg.id2, true);
      if (c2 == null || c2.state != 'game')
        return;

      // get client room
      var room: TestRoom = cast server.roomModule.getClientRoom(c2);
      if (room == null)
        throw 'game.migratePost(): no such game room';

      c.state = 'game';
      room.join(c);
    }

Using the notification from the cache server as a start for the migration process, we call the "Server.migrateClient()" and supply it with the server thread ID, notification parameters object and the name of notification function to run after the migration is completed. This callback will run after the login procedure is completed.

Automatic client migration

Automatic or lightweight client migration is controlled by supplying the user login message with the desired local server ID in the "migrateServerID" message field. The server will migrate the client before running the login procedure.