[Sync] Add a doc about the SharedModelTypeProcessor.
Just a brain-dump of my current understanding of how SMTP state works. BUG= Review-Url: https://codereview.chromium.org/2672123002 Cr-Commit-Position: refs/heads/master@{#448130}
This commit is contained in:
@ -31,8 +31,10 @@ namespace syncer {
|
||||
class CommitQueue;
|
||||
class ProcessorEntityTracker;
|
||||
|
||||
// A sync component embedded on the synced type's thread that helps to handle
|
||||
// communication between sync and model type threads.
|
||||
// A sync component embedded on the model type's thread that tracks entity
|
||||
// metadata in the model store and coordinates communication between sync and
|
||||
// model type threads. See //docs/sync/uss/shared_model_type_processor.md for a
|
||||
// more thorough description.
|
||||
class SharedModelTypeProcessor : public ModelTypeProcessor,
|
||||
public ModelTypeChangeProcessor,
|
||||
base::NonThreadSafe {
|
||||
@ -138,11 +140,26 @@ class SharedModelTypeProcessor : public ModelTypeProcessor,
|
||||
// Version of the above that generates a tag for |data|.
|
||||
ProcessorEntityTracker* CreateEntity(const EntityData& data);
|
||||
|
||||
/////////////////////
|
||||
// Processor state //
|
||||
/////////////////////
|
||||
|
||||
// The model type this object syncs.
|
||||
const ModelType type_;
|
||||
|
||||
// The model type metadata (progress marker, initial sync done, etc).
|
||||
sync_pb::ModelTypeState model_type_state_;
|
||||
|
||||
// Stores the start callback in between OnSyncStarting() and ReadyToConnect().
|
||||
StartCallback start_callback_;
|
||||
// ModelTypeSyncBridge linked to this processor. The bridge owns this
|
||||
// processor instance so the pointer should never become invalid.
|
||||
ModelTypeSyncBridge* const bridge_;
|
||||
|
||||
// Function to capture and upload a stack trace when an error occurs.
|
||||
const base::RepeatingClosure dump_stack_;
|
||||
|
||||
/////////////////
|
||||
// Model state //
|
||||
/////////////////
|
||||
|
||||
// The first model error that occurred, if any. Stored to track model state
|
||||
// and so it can be passed to sync if it happened prior to sync being ready.
|
||||
@ -155,6 +172,17 @@ class SharedModelTypeProcessor : public ModelTypeProcessor,
|
||||
// as false but will be set to true if we detect it's necessary to load data.
|
||||
bool waiting_for_pending_data_ = false;
|
||||
|
||||
////////////////
|
||||
// Sync state //
|
||||
////////////////
|
||||
|
||||
// Stores the start callback in between OnSyncStarting() and ReadyToConnect().
|
||||
StartCallback start_callback_;
|
||||
|
||||
// The callback used for informing sync of errors; will be non-null after
|
||||
// OnSyncStarting has been called.
|
||||
ModelErrorHandler error_handler_;
|
||||
|
||||
// Reference to the CommitQueue.
|
||||
//
|
||||
// The interface hides the posting of tasks across threads as well as the
|
||||
@ -162,6 +190,10 @@ class SharedModelTypeProcessor : public ModelTypeProcessor,
|
||||
// useful in tests.
|
||||
std::unique_ptr<CommitQueue> worker_;
|
||||
|
||||
//////////////////
|
||||
// Entity state //
|
||||
//////////////////
|
||||
|
||||
// A map of client tag hash to sync entities known to this processor. This
|
||||
// should contain entries and metadata for most everything, although the
|
||||
// entities may not always contain model type data/specifics.
|
||||
@ -173,17 +205,6 @@ class SharedModelTypeProcessor : public ModelTypeProcessor,
|
||||
// client tag hash. The other direction can use |entities_|.
|
||||
std::map<std::string, std::string> storage_key_to_tag_hash_;
|
||||
|
||||
// ModelTypeSyncBridge linked to this processor. The bridge owns this
|
||||
// processor instance so the pointer should never become invalid.
|
||||
ModelTypeSyncBridge* const bridge_;
|
||||
|
||||
// Function to capture and upload a stack trace when an error occurs.
|
||||
const base::RepeatingClosure dump_stack_;
|
||||
|
||||
// The callback used for informing sync of errors; will be non-null after
|
||||
// OnSyncStarting has been called.
|
||||
ModelErrorHandler error_handler_;
|
||||
|
||||
// WeakPtrFactory for this processor which will be sent to sync thread.
|
||||
base::WeakPtrFactory<SharedModelTypeProcessor> weak_ptr_factory_;
|
||||
|
||||
|
114
docs/sync/uss/shared_model_type_processor.md
Normal file
114
docs/sync/uss/shared_model_type_processor.md
Normal file
@ -0,0 +1,114 @@
|
||||
# SharedModelTypeProcessor
|
||||
|
||||
The [`SharedModelTypeProcessor`][SMTP] is a crucial piece of the USS codepath.
|
||||
It lives on the model thread and performs the tracking of sync metadata for the
|
||||
[`ModelTypeSyncBridge`][MTSB] that owns it by implementing the
|
||||
[`ModelTypeChangeProcessor`][MTCP] interface, as well as sending commit requests
|
||||
to the [`ModelTypeWorker`][MTW] on the sync thread via the [`CommitQueue`][CQ]
|
||||
interface and receiving updates from the same worker via the
|
||||
[`ModelTypeProcessor`][MTP] interface.
|
||||
|
||||
[SMTP]: https://cs.chromium.org/chromium/src/components/sync/model_impl/shared_model_type_processor.h
|
||||
[MTSB]: https://cs.chromium.org/chromium/src/components/sync/model/model_type_sync_bridge.h
|
||||
[MTCP]: https://cs.chromium.org/chromium/src/components/sync/model/model_type_change_processor.h
|
||||
[MTW]: https://cs.chromium.org/chromium/src/components/sync/engine_impl/model_type_worker.h
|
||||
[CQ]: https://cs.chromium.org/chromium/src/components/sync/engine/commit_queue.h
|
||||
[MTP]: https://cs.chromium.org/chromium/src/components/sync/engine/model_type_processor.h
|
||||
|
||||
[TOC]
|
||||
|
||||
## Lifetime
|
||||
|
||||
The bridge owns a processor object at all times and operates on the same thread
|
||||
as it. If sync is disabled, the processor is destroyed but a new one is
|
||||
immediately created to replace it.
|
||||
|
||||
## Processor State Machines
|
||||
|
||||
The processor sits between the model bridge and the sync engine. It has
|
||||
knowledge of what state each is in based on the calls it has receieved and
|
||||
performed. The states are not stored explicitly, but are implicit based on
|
||||
state stored in the processor. Here are the states of each, with notes on their
|
||||
transitions and how to determine them.
|
||||
|
||||
### Model States
|
||||
|
||||
* `UNREADY`
|
||||
* Waiting for `ModelReadyToStart` to be called.
|
||||
* Determined by: `waiting_for_metadata_ && !model_error_`
|
||||
* `NEEDS_DATA`
|
||||
* Waiting for data for pending commits to be loaded.
|
||||
* This state is skipped if there are no pending commits.
|
||||
* Determined by: `waiting_for_pending_data_ && !model_error_`
|
||||
* `READY`
|
||||
* The model is completely ready to sync.
|
||||
* Determined by: `!waiting_for_metadata_ && !waiting_for_pending_data &&
|
||||
!model_error`
|
||||
* `ERROR`
|
||||
* Something in the model or storage broke.
|
||||
* This state is permanent until DisableSync destroys the object.
|
||||
* Determined by: `!!model_error_`
|
||||
|
||||
### Sync States
|
||||
|
||||
* `DISCONNECTED`
|
||||
* Sync for this type has not started.
|
||||
* This state can be re-entered from any other state if Disconnect is
|
||||
called.
|
||||
* Determined by: `!error_handler_`.
|
||||
* `STARTED`
|
||||
* Sync has started but the model is not yet `READY` (or `ERROR`).
|
||||
* This state is skipped if the model is ready before sync is.
|
||||
* Determined by: `error_handler_ && start_callback_`
|
||||
* `CONNECT_PENDING`
|
||||
* Both the model and sync are ready. The start callback has been called
|
||||
and we're waiting to connect to the sync thread.
|
||||
* If the model was `ERROR`, the error is passed along and the callback is
|
||||
cleared; we're really waiting for DisableSync instead of connect.
|
||||
* Determined by: `error_handler_ && !start_callback_`
|
||||
* `CONNECTED`
|
||||
* We have a [`CommitQueue`][CQ] that passes changes to the
|
||||
[`ModelTypeWorker`][MTW] on the sync thread.
|
||||
* Determined by: `!!worker_`
|
||||
|
||||
### Processor States
|
||||
|
||||
Based on the interplay of the model and sync states, the processor effectively
|
||||
progresses through 3 states worth noting:
|
||||
|
||||
* `UNINITIALIZED`
|
||||
* Metadata isn't loaded so we have no knowledge of entities.
|
||||
* `Put` and `Delete` calls are not allowed in this state (will DCHECK).
|
||||
* `NOT_TRACKING`
|
||||
* Indicates that not metadata is being tracked and that `Put` and `Delete`
|
||||
calls will be ignored.
|
||||
* This state is entered if the loaded metadata shows an initial merge
|
||||
hasn't happened (`ModelTypeState::initial_sync_done` is false).
|
||||
* Exposed via `IsTrackingMetadata` for optimization, not correctness.
|
||||
* `TRACKING`
|
||||
* Indicates that metadata is being tracked and `Put` and `Delete` calls
|
||||
must happen for entity changes.
|
||||
* This state is entered if the loaded metadata shows an initial merge
|
||||
has happened (`ModelTypeState::initial_sync_done` is true).
|
||||
* `SYNCING`
|
||||
* Indicates that commits can be sent and updates can be received from the
|
||||
sync server. This is a superstate of `TRACKING`.
|
||||
* If the processor was in `TRACKING`, it progresses to this state as soon
|
||||
as it gets connected to the worker.
|
||||
* If the processor was in `NOT_TRACKING`, it progresses to this state
|
||||
after `MergeSyncData` is called and the metadata is initialized.
|
||||
|
||||
## Entity Tracker
|
||||
|
||||
The [`ProcessorEntityTracker`][PET] tracks the state of individual entities for
|
||||
the processor. It keeps the [`EntityMetadata`][EM] proto in memory, as well as
|
||||
any pending commit data until it gets acked by the server. It also stores the
|
||||
special `commit_requested_sequence_number_`, which tracks the sequence number of
|
||||
the last version that's been sent to the server.
|
||||
|
||||
The tracker holds the metadata in memory forever, which is needed so we know
|
||||
what to update the on-disk memory with when we get a new local or remote change.
|
||||
Changing this would require being able to handle updates asynchronously.
|
||||
|
||||
[PET]: https://cs.chromium.org/chromium/src/components/sync/model_impl/processor_entity_tracker.h
|
||||
[EM]: https://cs.chromium.org/chromium/src/components/sync/protocol/entity_metadata.proto
|
Reference in New Issue
Block a user