Manage a Sync Session - C++ SDK
On this page
When you use Atlas Device Sync, the Realm C++ SDK syncs data with Atlas in the background using a sync session. The sync session starts when you open a synced realm.
The sync session manages the following:
Uploading and downloading changes to the realm
Monitoring sync state
Prerequisites
Before you can manage a sync session state, you must:
Get the Sync Session
You can use the member function get_sync_session() to get a sync_session object for any synced realm. The SDK returns this object as an optional. It is a lightweight handle that you can pass around by value.
auto syncSession = realm.get_sync_session();
Check the Network Connection
Tip
The SDK's offline-first design means that you generally don't
need to check the current network connection state. That said, the
connection_state() property is available if your app calls for some
indication of connection state.
To check the connection state, you can read the
sync session instance's
connection_state() property directly.
syncSession->connection_state();
You can also observe the connection state with the observe_connection_change() function. This function registers a callback that the SDK invokes when the underlying sync session changes its connection state.
auto connectionToken = syncSession->observe_connection_change( [&](enum realm::sync_session::connection_state, enum realm::sync_session::connection_state new_state) { // Register a block to execute when connection state changes. });
If you register a connection change listener, you can unregister it when you're done listening for changes. Call the sync session instance's unregister_connection_change_observer() method to unregister an observation token.
syncSession->unregister_connection_change_observer(connectionToken);
The network connection state is distinct from the Device Sync connection state
that you can check with the state() method. For more information about
sync connection state, refer to the Check the Sync State documentation on
this page.
Pause or Resume a Sync Session
You can pause and resume the sync session on the realm. Pausing a sync session only suspends that realm's sync session. If you have more than one open realm, suspend does not affect the sync sessions for other realms.
To pause a sync session, call the sync session's pause() method.
syncSession->pause();
To resume a sync session, call the sync session's resume() method.
syncSession->resume();
When to Pause a Sync Session
For most applications, there is no need to manually pause and resume a sync session. However, there are a few circumstances under which you may want to pause or suspend a sync session:
You only want to sync after the user takes a specific action
You only want to sync during a certain time of the day
You don't want to attempt to sync when there is poor network connectivity
You want to explicitly force a sync session to connect
In the case of poor network connectivity, continually trying to establish a network connection can drain the user's device battery.
The case of explicitly forcing a sync session to connect is most commonly related to being offline for some time. The sync client attempts to connect, and upon failure, goes into exponential backoff. After being offline for a long time, the client may not immediately reconnect. Pausing and resuming the sync session explicitly forces the connection.
When you do pause a sync session, keep these things in mind:
If the client may be offline longer than the client maximum offline time, the client will be unable to resume syncing and must perform a client reset.
Pausing a sync session pauses it in both directions. Changes that your app makes on the device do not sync with the backend, and changes to the data in the backend or on other devices do not sync to the device. There is no way to pause only uploads or pause only downloads.
Do not pause a sync session if you want a client to permanently stop syncing with the backend. To permanently stop syncing, copy the contents of the synced realm into a non-synced realm, and use the non-synced realm in the client.
Do not pause sync to stop syncing for indefinite time periods or time ranges in months and years. The functionality is not designed or tested for these use cases. You could encounter a range of issues when using it this way.
Wait for Changes to Upload and Download
You can use the
sync_session's
wait_for_upload_completion() and wait_for_download_completion()
methods to wait for changes to upload to or download from Atlas. Both of these
methods can optionally take a callback to execute when upload or download
is complete.
To wait for all changes to upload to Atlas from your synced realm,
use the member function wait_for_upload_completion().
syncSession->wait_for_upload_completion().get();
To wait for all changes from Atlas
to download to your synced realm, use the member function
wait_for_download_completion(). Refresh the realm after downloading
any changes to be sure it reflects the most recent data.
syncSession->wait_for_download_completion().get(); realm.refresh();
Check the Sync State
You can use the sync_session's public
member function state() to check whether the sync session is active.
This returns an enum whose value reflects possible Device Sync states.
syncSession->state();
The sync connection state is distinct from the network connection state
that you can check with the connection_state() method. For more information
about network connection state, refer to the Check the Network Connection
documentation on this page.
Manually Reconnect All Sync Sessions
Realm automatically detects when a device regains connectivity after being offline and attempts to reconnect using an incremental backoff strategy.
You can choose to manually trigger a reconnect attempt with a sync session's reconnect() method instead of waiting for the duration of the incremental backoff. This is useful if you have a more accurate understanding of the network conditions and don't want to rely on Realm's automatic reconnect detection.
syncSession->reconnect();
When you call this method, the SDK forces all sync sessions to attempt to reconnect immediately. This resets any timers used for incremental backoff.
Calling this method does not guarantee the device can reconnect. If the SDK gets a fatal error, or if the device is already connected or is trying to connect, calling this method has no effect.
Important
Cannot Reconnect Within Socket Read Timeout Duration
Realm has an internal default socket read timeout of 2 minutes, where
Realm will time out if a read operation does not receive any data
within a 2-minute window. If you call reconnect() within that window,
the SDK does not attempt to reconnect.