Understanding Synchronization Knowledge

This topic provides an abstract view of how the Sync Framework synchronization algorithms use knowledge to enable change enumeration and conflict detection. Knowledge is the metadata that describes all the changes that have been applied to a replica, either directly or though synchronization. Change enumeration is the process of determining which items have been changed on the source replica that the destination replica does not have knowledge of. Conflict detection is the process of determining which operations were made by one replica without transferring knowledge of the change to the other replica, for example, when two replicas make local updates to the same item.

Note

Generally, synchronization providers and applications will not directly use knowledge. Instead, they will call Sync Framework methods that invoke knowledge operations on their behalf.

Knowledge Operations

The following table lists and describes the synchronization knowledge operations.

Operator Description

Contains

Determines whether a specified knowledge object contains a specified version of an item. (Version is a replica key and a tick count.) In other words, determine whether the replica that owns this knowledge has applied this change. The item ID and version are required inputs to this operation.

This operation is used in change enumeration and conflict detection.

Union

From two knowledge objects, constructs a new knowledge object that contains exactly the same set of changes that is contained by at least one of the original knowledge objects.

This operation is used during change application.

Project

By using a specified knowledge object and an item ID, change unit ID, or range of item IDs, generates a new knowledge object that contains the same changes as the original for the specified ID or range of IDs, and nothing for the rest of the items.

This operation is used when knowledge must be restricted to a particular item, change unit, or range of items; for example, during interrupted synchronization, batching, and some advanced forms of filtered synchronization.

Exclude

By using a specified knowledge object and an item ID or change unit ID, generates a new knowledge object that contains nothing for the specified ID, but the same changes as the original for the rest of the items. This operation is the opposite of the project operation: an exclude operation projects the knowledge on everything except the specified item.

This operation is typically used during failures in change application.

Change Enumeration

Change enumeration is implemented by the developer of the source provider. By using specified knowledge operations, change enumeration works as follows:

  1. The destination provider sends the current knowledge of the destination replica to the source provider.

  2. The source provider iterates through all items in the source replica and performs the following steps for each item:

    1. Determines whether the destination knowledge contains the item version that is stored in the source replica.

    2. If not, includes the item in the batch of changes to send to the destination provider.

Note

Change enumeration can also be handled by using either a direct query on the item store or by using a combination of a query and this algorithm, if it is supported by the item store.

Change Sending

Enumerated changes must be sent from the source provider to the destination provider. To do this, changes are divided into batches; and for every batch the following information is sent:

  • Metadata that describes the changes themselves. The provider adds metadata to the batch for each change contained in the batch.

  • The made-with knowledge, which is typically the current knowledge of the source replica, to be used in conflict detection. Made-with knowledge answers the question: What did you know when you made these changes? The provider adds made-with knowledge to the batch for each group of changes added to the batch.

  • The learned knowledge. This is the current knowledge of the source replica projected onto the subset of the items that are being sent in this batch, and also the logged conflicts. Learned knowledge answers the question: What will I learn when I apply these changes? Sync Framework computes the learned knowledge on behalf of the provider.

Note

Batching and change enumeration can be processed in parallel because batching does not have to wait for change enumeration to finish.

Ordering

Depending on the order in which changes are sent, projecting the knowledge onto the items in the batch can take more or less time to perform. For example, knowledge supports item ID ranges. Therefore, if changes are sent in the order of the item IDs to which they apply, knowledge projection will be very efficient.

Regardless of the ordering, the project operation can always project knowledge onto the batch that is being sent.

Errors

When the source provider cannot send an item that was enumerated, the item must then be excluded from the learned knowledge that is sent. This is achieved by using the exclude operator.

Conflict Detection

Conflict detection is handled by Sync Framework components, such as NotifyingChangeApplier (for managed code) or ISynchronousNotifyingChangeApplier (for unmanaged code).

After the destination provider has received a batch of changes, which contains the learned and made-with knowledge for the batch, the following determinations must be made for each change in the batch:

  • Is this change in conflict with the current version of the item stored in the destination replica?

  • Is this change obsolete (superseded by the current version of the item that is stored in the destination replica)?

Answering these questions is straightforward:

  • A change conflicts with the current version when the version on the item stored in the destination replica is not contained in the knowledge of the source replica.

  • A change is obsolete when its version is contained in the knowledge of the destination replica.

    Note

    Under typical circumstances, obsolete changes are not sent. However, race conditions can cause these changes to be sent. Therefore, Sync Framework must detect and handle them.

Change Application

After the changes have been received and conflicts have been detected, the changes can be applied to the destination replica. At this point, the destination provider performs the following steps:

  1. Adjusts the learned knowledge of the change batch for things that occurred locally:

    1. If only a subset of changes were applied because of interruptions or cancellations, sets a recoverable error for each change that was not applied. Sync Framework uses the project operator to restrict learned knowledge to only this set.

    2. If application of some changes failed because of Digital Rights Management (DRM) issues, such as objects being locked, the destination provider sets a recoverable error for each change that was not applied. Sync Framework uses the exclude operator to remove the failed changes from the learned knowledge.

    3. If any conflicts were detected and not resolved, Sync Framework uses the exclude operator to remove them also.

  2. Replaces the knowledge of the destination replica with the updated destination knowledge computed by Sync Framework.

See Also

Concepts

Enumerating Changes
Handling Conflicts
Applying Changes

Other Resources

Microsoft Sync Framework