Using connection recovery (Windows)

This topic includes the following:

 

The connection recovery feature enables an xfServer client application to seamlessly reconnect to the server and recover its session context after an unexpected loss of connectivity.

To use connection recovery, both the server and clients must be version 10.3 or higher. This feature is supported only for Windows clients connecting to a Windows server. Older Windows clients and Unix clients can connect to a Windows server that has connection recovery enabled, but they cannot take advantage of it.

This feature is intended primarily for wireless networks, which may include laptop computers or mobile devices such as tablets, rather than for traditional, wired networks where the clients are desktop computers and loss of connectivity is rare. For example, in a large warehouse with overlapping Wi-Fi networks, a device running an application with a connection to xfServer would lose that connection as the user moved about the warehouse, going in and out of range of the various wireless network access points. And when the connection is lost, all contexts for the application are also lost, including which record in which file was being read, as well as records locked for updating. When this happens, the user gets an error and has to restart the application, determine where he was and what he was doing, and perhaps re-enter data.

With the connection recovery feature, however, when the connection is unexpectedly dropped, the client context will be saved on the server and the client application will attempt to reconnect. If it is able to reconnect within a certain time limit (which you can specify), the client context can be recovered. In the warehouse scenario, the end user would be unlikely to even notice what had happened. To handle the possibility of a longer disconnect period, you can add code to your application to ask the user whether to continue trying to reconnect.

How connection recovery works

Connection recovery can be run in master mode or slave mode. When master mode is enabled, the feature is enabled for all clients, but can be disabled on individual clients. When slave mode is enabled, activation of the feature is controlled by setting the SCSKEEPCONNECT environment variable on the client. (For devices such as tablets, where environment variables are not supported, connection recovery is implicitly activated on the client.) In both master and slave mode, you can control the length of time that the client continues to try to connect, how long client context is maintained, and how long (or if) records and files are kept locked. By default, connection recovery is enabled in slave mode with default settings for these time values.

To completely disable connection recovery, on the xfServer machine clear the Enable connection recovery check box in the Synergy Configuration Program or start rsynd from the command line with the -keepconnect=off option.

A disconnected socket may be detected on the server when it pings to see if an idle client is still present, or it may be detected by the client when it makes a request to the server. Once the dropped socket is detected, the client context is saved on the server machine and held for the length of time defined by the KeepContext value. If KeepLocks is non-zero, record and file locks will be maintained for the KeepLocks value. If KeepLocks is zero, record and file locks are released immediately when the disconnect is detected.

If the client detects the dropped connection, it will continue trying to reconnect to the server, making a request every 5 seconds for the length of time defined by the RetryTime value. Once that time has expired, a “Server connection retry failure” error ($ERR_SRVCONTRY) will be generated. However, if the KeepContext time has not expired, the context will continue to be maintained and can be recovered by the client if it reconnects.

It is important to understand that the KeepContext, KeepLocks, and RetryTime timers all start after the socket disconnect has been detected. How long this takes varies depending on your network and the Keepalive setting and whether the disconnect is detected by the server or the client. On the server side, a disconnect cannot be detected until the TCP keepalive timer fires. For this reason, you may want to set KeepAlive to a fairly short period so that dropped sockets are detected quickly. By default, KeepAlive is set to 150 seconds (two-and-a-half minutes).

Implementing connection recovery in your application

You can use this feature straight out of the box with the default settings without making any changes to your application. Be aware, however, that $ERR_SRVCONTRY, which occurs when the RetryTime expires, is a new error that your application may not be trapping for. To take full advantage of connection recovery, you may want to make some changes to your application.

Users actively using your application are unlikely to patiently wait a minute or two for a connection unless they know that the application is attempting to reconnect. One way to handle this is to trap for $ERR_SRVCONTRY and reissue the request. A simpler way to keep the user informed is to use the IOHooks reconnect_hook method. This method is called when the RetryTime value expires, prior to the $ERR_SRVCONTRY error being generated. Returning TRUE from reconnect_hook re-issues the failed request and resets RetryTime. Returning FALSE terminates the retry request and the $ERR_SRVCONTRY error is generated. For example, you could write a method that displays a message dialog that indicates the application is attempting to connect and offers the user the option to continue or terminate. For more information on using the IOHooks class, see Synergex.SynergyDE.IOExtensions.IOHooks.

Understanding the connection recovery options

You can set these values on the server from the Synergy Configuration Program or the command line. On the client, you can use the environment variables SCSKEEPCONTEXT, SCSKEEPALIVE, and SCSKEEPLOCKS to override the values on the server for that client. There is no client-side environment variable to override RetryTime, but you can do so by setting one of the profiles (see Understanding the predefined profiles).

KeepContext

Defines the length of time, in seconds, that xfServer will maintain the context for a client connection after an unexpected socket disconnect has been detected. Note that due to the keepalive timer, the disconnect may not be detected immediately, especially if the client is idle. If xfServer receives a reconnection request from the client within the KeepContext time, it will resume the suspended connection with the last known context, including open files, file position, and (depending on the KeepLocks setting) file and record locks. If the client does not reconnect within the specified time, the context is deleted and all file and record locks are released. The xfServer license is held with the context and not released until the KeepContext time expires.   

Tip

You can use the synxfmon utility to view suspended connections and how long they have been suspended. You can also terminate suspended connections with synxfmon. For more information, see Monitor utility for Windows (synxfmon).

KeepAlive

Defines the TCP keepalive timer setting when connection recovery is enabled. The keepalive timer fires when there has been no communication from the client for the length of time specified by the keepalive timer. For connection recovery, we recommend a fairly short keepalive time, so that disconnected sockets are detected quickly and the context saved. But this efficiency comes at the cost of more frequent TCP/IP pings, which may be undesirable in a busy network. For more information about the keepalive timer, see Rsynd: shutting down and timing out.

KeepLocks

Defines the length of time that records and files remain locked when a client context is saved. By default, records and files that are locked when the client context is saved remain locked for the length of time specified with the KeepLocks value. When KeepLocks expires, record locks are released. Files opened with exclusive locks (SHARE:Q_EXCL_RO or SHARE:Q_EXCL_RW) are released and closed. Files opened for output or append, however, remain locked until KeepContext expires or the client regains control of the context.

Note that files must be closed on the server to release the locks. Upon reconnecting, the client will receive a “Remote file has been closed” error ($ERR_SRVFILCL). Your application will need to handle re-opening the file.

Tip

We recommend using temporary filenames (or some other type of unique filenames) for output and append files such as log files. Otherwise, a restarted application might encounter a locked file.

All locks are released when KeepContext expires. Consequently, the KeepLocks time cannot be longer than the KeepContext time. If KeepLocks is shorter than KeepContext, a client that reconnects after locks have been released (but before the context expires) will need to relock records prior to updating; otherwise, a “No current record” error ($ERR_NOCURR) will be generated. If you do not want files and records to remain locked when a context is saved, set KeepLocks to 0 (zero). Even if KeepLocks is 0, files opened for output or append with exclusive locks will remain locked until the KeepContext time expires.

Tip

Take care when choosing a KeepLocks value. If your application uses optimistic locking (which we recommend), KeepLocks can be set to a very low value—even zero. But if your application holds on to record locks, you’ll probably want a larger value. In most cases, a relatively short time—no more than 5 minutes—should suffice. A longer time runs the risk that the user may give up waiting for the socket to reconnect, exit and restart the application, and then discover that records cannot be accessed because they are still locked.

RetryTime (client retry)

Defines the length of time that the client will continue to attempt to reconnect to a server thread when it detects that it has been disconnected. When a disconnected socket is detected by the client, it automatically attempts to reconnect, and will continue to make connection requests every 5 seconds for the length of RetryTime before generating a “Server connection retry failure” error ($ERR_SRVCONTRY).

Note

It is not necessary to make RetryTime as long as the KeepContext time because xfServer is continuously watching the socket, whereas the client application will detect a bad socket only when it attempts I/O. Chances are that the server will already be waiting for the client’s reconnect request, so it’s the KeepContext time that you need to set to indicate how long you want the context to be maintained.

Understanding the predefined profiles

There are three predefined profiles—Default, Mobile, and Mobile2—which simply offer a convenient way to set the four time values used by connection recovery. You can use these profiles on the server by selecting one in the Synergy Configuration Program (profiles are not available when starting rsynd from the command line) or on the client by specifying one with the SCSPROFILE environment variable. The profiles are defined as follows (times are in seconds):

Connection Recovery Profile Definitions

Setting

Default profile

Mobile profile

Mobile2 profile

KeepContext

300

7200

7200

KeepAlive

150

60

60

KeepLocks

300

300

300

RetryTime

60

60

20

The Default profile represents the built-in connection recovery defaults.

The Mobile profile is suitable for use with an application that has no special handling for socket failures. It provides a reasonable time to re-establish a failed connection, so it’s a good choice if you are using connection recovery out of the box without any modifications to your application.

The Mobile2 profile is suitable for use with an application with built-in awareness of socket failures, which enables the application to control what action to take after a failure. This awareness may be in the form of an IOHooks reconnect_hook method or it could be code that reissues the request upon trapping a “Server connection retry failure” ($ERR_SRVCONTRY) error.

Using connection recovery in slave mode

In slave mode, the connection recovery feature is activated only when the client requests it. The advantage of slave mode is that it lets you determine which clients on your network need the feature. For example, your network may include both wired desktop systems (which rarely, if ever, experience a socket disconnect) and laptops using Wi-Fi (which may experience socket disconnects as they are moved around the office).

1. On the xfServer machine, in the Synergy Configuration Program, select the Enable connection recovery check box and the Slave radio button.
2. Choose a profile or select Custom and specify your own time values.
3. Set the SCSKEEPCONNECT environment variable to ON on clients that you want to use connection recovery. Leave SCSKEEPCONNECT unset or set it to OFF on clients that you do not want to use the feature.
4. By default, clients use the connection recovery settings on the server. To override these settings, set the SCSKEEPCONTEXT, SCSKEEPALIVE, and SCSKEEPLOCKS environment variables on the client. Alternatively, you can set SCSPROFILE on the client to specify a predefined set of values.
Tip

When connection recovery is enabled in slave mode, setting SCSKEEPCONTEXT, SCSKEEPALIVE, SCSKEEPLOCKS, or SCSPROFILE on the client will enable the feature for that client, as long as SCSKEEPCONNECT is not set to OFF.

Using connection recovery in master mode

When connection recovery is enabled in master mode, the feature is activated for all clients, unless individual clients request that it be disabled.

1. On the xfServer machine, in the Synergy Configuration Program, select the Enable connection recovery check box and the Master radio button.
2. Choose a profile or select Custom and specify your own time values.
3. By default, clients use the connection recovery settings on the server. To override these settings, set the SCSKEEPCONTEXT, SCSKEEPALIVE, and SCSKEEPLOCKS environment variables on the client, or use the SCSPROFILE environment variable to specify a predefined set of values.
4. To disable connection recovery for individual clients, set the SCSKEEPCONNECT environment variable to OFF on the client.

See also