sync/js/README.js

   1 Overview of chrome://sync-internals
   2 -----------------------------------
   3
   4 This note explains how chrome://sync-internals (also known as
   5 about:sync) interacts with the sync service/backend.
   6
   7 Basically, chrome://sync-internals sends messages to the sync backend
   8 and the sync backend sends the reply asynchronously.  The sync backend
   9 also asynchronously raises events which chrome://sync-internals listen
  10 to.
  11
  12 A message and its reply has a name and a list of arguments, which is
  13 basically a wrapper around an immutable ListValue.
  14
  15 An event has a name and a details object, which is represented by a
  16 JsEventDetails (js_event_details.h) object, which is basically a
  17 wrapper around an immutable DictionaryValue.
  18
  19 Message/event flow
  20 ------------------
  21
  22 chrome://sync-internals is represented by SyncInternalsUI
  23 (chrome/browser/ui/webui/sync_internals_ui.h).  SyncInternalsUI
  24 interacts with the sync service via a JsController (js_controller.h)
  25 object, which has a ProcessJsMessage() method that just delegates to
  26 an underlying JsBackend instance (js_backend.h).  The SyncInternalsUI
  27 object also registers itself (as a JsEventHandler
  28 [js_event_handler.h]) to the JsController object, and any events
  29 raised by the JsBackend are propagated to the JsController and then to
  30 the registered JsEventHandlers.
  31
  32 The ProcessJsMessage() takes a WeakHandle (weak_handle.h) to a
  33 JsReplyHandler (js_reply_handler.h), which the backend uses to send
  34 replies safely across threads.  SyncInternalsUI implements
  35 JsReplyHandler, so it simply passes itself as the reply handler when
  36 it calls ProcessJsMessage() on the JsController.
  37
  38 The following objects live on the UI thread:
  39
  40 - SyncInternalsUI (implements JsEventHandler, JsReplyHandler)
  41 - SyncJsController (implements JsController, JsEventHandler)
  42
  43 The following objects live on the sync thread:
  44
  45 - SyncManager::SyncInternal (implements JsBackend)
  46
  47 Of course, none of these objects need to know where the other objects
  48 live, since they interact via WeakHandles.