A simple example

Last updated 11 days ago

Let's use a simple example with the following assumptions:

Client 1 = Mobile Client 2 = Tablet Synced Object = Name (First, Last)

Objects are native to the respective programming language, e.g. Swift, Java, which are persisted in the Realm database. When a synced object is written to the local Realm database (client), the local state is automatically propagated to the server, integrated (with conflict resolution) into the reference realm and subsequently the new object state is distributed to all participating clients that share the same synced object.

Propagation of this change info is via a ‘changeset’, which denotes the difference between a known prior state or version of the object (as managed by the server) and applied writes. Multiple clients can initiate changes to the data (of the same version or even different) at the same time.

Let’s use the following simplified example:

3 participating parties (2 clients, one server) share and sync a object User = {First_Name, Last_Name}. Let’s assume that at time t1 the server and all clients share the same state (or version) of the object, which may be:

t1, Version = 1, User = {John, Doe}

At a subsequent time t2 client 1 will overwrite the name:

t2, Version = 1, User = {Michael, Doe}

The changes at t2 from client 1 will be propagated to the server via the respective changeset. It compares the change via the base version and merges it into a new version of the object: Version 2: User = {Michael, Doe}

This new Version 2 will be propagated to all clients subscribing to the shared object, which will integrate this change and use it as the new base.This is the typical case.

Due to the nature of offline behavior, changesets will arrive at any time that connectivity allows. Thus there is no guarantee that a changeset from Client1 at t2 will arrive prior to a changeset from a different Client 2 at t3 that applies to the same Version.

Thus let’s assume that sometime later at t3 (>t2) client 2 will change the same object in a different way:

t3, Version = 1, User = {Michael, Jackson}

The server in turn will have to be able to process these events out-of-order. To enable that, ROS keeps a history of transactions on a per Realm basis, which tracks which changeset was integrated when. Thus when changesets come out-of-order it will be possible to make a proper determination via merge and conflict resolution what the appropriate action is. In principle conflict resolution is based on “last-write-wins”.

Thus in the above case the server will receive a changeset from Client 2 from t3, based on version 1, which arrives AFTER version 2 has been created. Since changeset from t2 and t3 are based of the same base version it leverages the time of the write-event, in which t3 wins. Thus the result is:

Version 3: User = {Michael, Jackson}

This Version 3 is propagated to all clients participating in the synced object.

While this is a simple example it can get quickly more sophisticated. For example when sync insert changesets into Lists from the same base version Realm sync uses Operational Transform.