services/sync/docs/rust-engines.rst

   1 ================================
   2 How Rust Engines are implemented
   3 ================================
   4
   5 There are 2 main components to engines implemented in Rust
   6
   7 The bridged-engine
   8 ==================
   9
  10 Because Rust engines still need to work with the existing Sync infrastructure,
  11 there's the concept of a `bridged-engine <https://searchfox.org/mozilla-central/source/services/sync/modules/bridged_engine.js>`_.
  12 In short, this is just a shim between the existing
  13 `Sync Service <https://searchfox.org/mozilla-central/source/services/sync/modules/service.js>`_
  14 and the Rust code.
  15
  16 The bridge
  17 ==========
  18
  19 `"Golden Gate" <https://searchfox.org/mozilla-central/source/services/sync/golden_gate>`_
  20 is a utility to help bridge any Rust implemented Sync engines with desktop. In
  21 other words, it's a "rusty bridge" - get it? Get it? Yet another of Lina's puns
  22 that live on!
  23
  24 One of the key challenges with integrating a Rust Sync component with desktop
  25 is the different threading models. The Rust code tends to be synchronous -
  26 most functions block the calling thread to do the disk or network IO necessary
  27 to work - it assumes that the consumer will delegate this to some other thread.
  28
  29 So golden_gate is this background thread delegation for a Rust Sync engine -
  30 gecko calls golden-gate on the main thread, it marshalls the call to a worker
  31 thread, and the result is marshalled back to the main thread.
  32
  33 It's worth noting that golden_gate is just for the Sync engine part - other
  34 parts of the component (ie, the part that provides the functionality that's not
  35 sync related) will have its own mechanism for this. For example, the
  36 `webext-storage bridge <https://searchfox.org/mozilla-central/source/toolkit/components/extensions/storage/webext_storage_bridge/src>`_
  37 uses a similar technique `which has some in-depth documentation <../../toolkit/components/extensions/webextensions/webext-storage.html>`_.