This section discusses the requirements for an Open Server to migrate clients to other servers. When migrating clients to a different server your application must:
Create a unique session ID and send it to the clients in the connection handler.
Initiate connection migration.
Handle migration events.
Share the context of the connection, using the connection’s session ID, to other servers.
(Optional) Act on ongoing migrations in existing handlers.
The following sections further discuss these activities.
Open Server can use srv_send_ctlinfo() to send a migration request to the client. Client migration can be requested from any Open Server thread.
In the SRV_CONNECT event handler, your application must:
Check the SRV_T_MIGRATED property and determine if the connection is a migrated connection. If it is, your application must access the context based on the session ID provided by the client. The session ID can be retrieved using the SRV_T_SESSIONID thread property.
Check CS_REQ_MIGRATE to determine if the client supports connection migration. If the client supports connection migration, your application must send a session ID using the SRV_T_SESSIONID property to the client if the client has not yet received a session ID. By assigning the client a session ID, your application can instruct the client to migrate when the need arises.
The SRV_MIGRATE_STATE event handler must manage the migration state changes and execute the actions appropriate for each change:
SRV_MIGRATE_STATE changed to SRV_MIG_READY
A “ready” migration state indicates that the client is prepared to migrate and, for now, is not going to send any request. In the SRV_MIGRATE_STATE event handler, Open Server shares the client context with the server the client is migrating to. Afterwards, your application can return from the event handler, and Open Server can automatically instruct the client to start the migration.
SRV_MIGRATE_STATE changed to SRV_MIG_FAILED
If the SRV_MIGRATE_STATE event handler is triggered because the migration state changed to “failed,” your application must access the context again. Your application can request another migration attempt from the SRV_MIG_STATE event handler using the srv_send_ctlinfo() function. However, the client may have sent another query before it indicates it is ready to migrate again. The application must be able to service or migrate such a request.
For servers to start and continue servicing a client, the servers must have access to the client’s context which is identified by the client’s session ID. Typically, the client’s context contains data, such as global data, that event handlers for the client can access. The amount of context required for a connection depends on the service that the Open Server application provides. The more context-free the service is, the less context needs to be shared.
Your application sends the remaining results and messages to the client inside the SRV_MIGRATE_RESUME event handler. The results and messages that Open Server sends to the client depend on your application and the migration type. However, your application must end the SRV_MIGRATE_RESUME event handler by sending the SRV_DONE_FINAL result type to the client.
In the SRV_DISCONNECT event handler, your application must check SRV_T_MIGRATE_STATE to determine the client’s migration state:
A migration state of SRV_MIG_REQUESTED indicates that the SRV_DISCONNECT event has been triggered because the Open Server application terminated the connection before the client could respond to the migration request.
A migration state of SRV_MIG_MIGRATING indicates that the SRV_DISCONNECT event has been triggered because the client application, after a successful migrating to the new server, closed the connection.
For all other migration states, the client must make sure that connection-specific context is cleaned up because no other server will pick up this context.
An event handler that runs for long periods of time must occasionally inspect the migration state. Other Open Server threads can send a migration request even while an event handler process is still running. In this case, the event handler, if it is able to, must interrupt the process, and postpone the generation and sending of results until the connection has migrated to the new server.
When a client sends an attention message to cancel an outstanding request, the SRV_T_GOTATTENTION thread property is set to CS_TRUE and the SRV_ATTENTION event handler is called. The specific attention handling needs of a connection migration are described below:
For the SRV_MIGRATE_STATE event handler and SRV_MIG_READY state:
If the attention message arrives in the SRV_MIGRATE_STATE event handler before the client indicates that it is ready to migrate, Open Server acknowledges the attention when the SRV_MIGRATE_STATE event handler ends. This completes the request from the client. After a successful migration, the server that the client has migrated to does not receive this attention message and, because the client is not waiting for results from Open Server, the SRV_MIGRATE_RESUME event handler is not called.
Thus, your application must check if the SRV_T_GOTATTENTION property is set to CS_TRUE before making the context available to other servers. If SRV_T_GOTATTENTION is set to CS_TRUE, you must update the context to indicate that the client has cancelled the operation.
For the SRV_MIGRATE_RESUME event handler:
If the client has sent the attention message after the client indicated that it is ready to migrate and the migration succeeded, the attention is sent to the server to which the client has migrated. It is therefore possible that, after a successful migration, an attention can be received by the SRV_MIGRATE_RESUME event handler even if the original server has updated the context to reflect the cancellation. Thus, your application must check if the client has sent an attention to the server before it can execute the SRV_MIGRATE_RESUME event handler.
Your application can terminate a client connection even when a migration has been requested; however, a new client command that is sent just before Open Server issued the termination command may get lost. To avoid this, your application must:
If possible, avoid terminating connections when a client is instructed to migrate.
If there is a need to disconnect a client, Open Server must set a reasonable wait time before requesting the migration. This gives a client the time to detect the migration request before it issues another command.
When Open Server terminates a connection, the SRV_DISCONNECT event handler is called. Inside this handler, ensure that the context is available to other servers if the migration state is still set to SRV_MIG_REQUESTED.
