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 asynchronous messages to the 8 sync backend and the sync backend asynchronously raises events to 9 chrome://sync-internals, either when replying to messages or when 10 something interesting happens. 11 12 Both messages and events have a name and a list of arguments, the 13 latter of which is represented by a JsArgList (js_arg_list.h) object, 14 which is basically a wrapper around an immutable ListValue. 15 16 TODO(akalin): Move all the js_* files into a js/ subdirectory. 17 18 Message/event flow 19 ------------------ 20 21 chrome://sync-internals is represented by SyncInternalsUI 22 (chrome/browser/web_ui/sync_internals_ui.h). SyncInternalsUI 23 interacts with the sync service via a JsFrontend (js_frontend.h) 24 object, which has a ProcessMessage() method. The JsFrontend can 25 handle some messages itself, but it can also delegate the rest to a 26 JsBackend instance (js_backend.h), which also has a ProcessMessage() 27 method. A JsBackend can in turn handle some messages itself and 28 delegate to other JsBackend instances. 29 30 Essentially, there is a tree with a JsFrontend as the root and 31 JsBackend as non-root internal nodes and leaf nodes (although 32 currently, the tree is more like a simple list). The sets of messages 33 handled by the JsBackends and the JsFrontend are disjoint, which means 34 that at most one node handles a given message type. Also, the 35 JsBackends may live on different threads, but JsArgList is thread-safe 36 so that's okay. 37 38 SyncInternalsUI is a JsEventHandler (js_event_handler.h), which means 39 that it has a HandleJsEvent() method, but JsBackends cannot easily 40 access those objects. Instead, each JsBackend keeps track of its 41 parent router, which is a JsEventRouter object (js_event_router.h). 42 Basically, a JsEventRouter is another JsBackend object or a JsFrontend 43 object. So an event travels up through the JsEventRouter until it 44 reaches the JsFrontend, which knows about the existing JsEventHandlers 45 (via AddHandler()/RemoveHandler()) and so can delegate to the right 46 one. 47 48 A diagram of the flow of a message and its reply: 49 50 msg(args) -> F -> B -> B -> B 51 | | | 52 H <- R <- R <- R <- reply-event(args) 53 54 F = JsFrontend, B = JsBackend, R = JsEventRouter, H = JsEventHandler 55 56 Non-reply events are percolated up similarly. 57
