lifetime.rst (7563B)
1 Search Lifecycle 2 ================ 3 4 When a character is typed into the address bar, or the address bar is focused, 5 we initiate a search. What follows is a simplified version of the 6 lifetime of a search, describing the pipeline that returns results for a typed 7 string. Some parts of the query lifetime are intentionally omitted from this 8 document for clarity. 9 10 The search described in this document is internal to the address bar. It is not 11 the search sent to the default search engine when you press Enter. Parts of this 12 process often occur multiple times per keystroke, as described below. 13 14 It is recommended that you first read the :doc:`nontechnical-overview` to become 15 familiar with the terminology in this document. This document is current as 16 of April 2023. 17 18 #. 19 The user types a query (e.g. "coffee near me") into the *UrlbarInput* 20 `<input> DOM element <https://searchfox.org/mozilla-central/rev/1f4f99a8f331cce8467a50742178b6d46914ab89/browser/base/content/navigator-toolbox.inc.xhtml#330-336>`_. 21 That DOM element `tells <https://searchfox.org/mozilla-central/rev/1f4f99a8f331cce8467a50742178b6d46914ab89/browser/components/urlbar/UrlbarInput.sys.mjs#3312>`_ 22 *UrlbarInput* that text is being input. 23 24 #. 25 *UrlbarInput* `starts a search <https://searchfox.org/mozilla-central/rev/1f4f99a8f331cce8467a50742178b6d46914ab89/browser/components/urlbar/UrlbarInput.sys.mjs#3395>`_. 26 It `creates <https://searchfox.org/mozilla-central/rev/1f4f99a8f331cce8467a50742178b6d46914ab89/browser/components/urlbar/UrlbarInput.sys.mjs#1549>`_ 27 a `UrlbarQueryContext <https://firefox-source-docs.mozilla.org/browser/urlbar/overview.html#the-urlbarquerycontext>`_ 28 and `passes it to UrlbarController <https://searchfox.org/mozilla-central/rev/1f4f99a8f331cce8467a50742178b6d46914ab89/browser/components/urlbar/UrlbarInput.sys.mjs#1548>`_. 29 The query context is an object that will exist for the lifetime of the query 30 and it's how we keep track of what results to show. It contains information 31 like what kind of results are allowed, the search string ("coffee near me", 32 in this case), and other information about the state of the Urlbar. A new 33 *UrlbarQueryContext* is created every time the text in the input changes. 34 35 #. 36 *UrlbarController* `tells UrlbarProvidersManager <https://searchfox.org/mozilla-central/rev/0ffaecaa075887ab07bf4c607c61ea2faa81b172/browser/components/urlbar/UrlbarController.sys.mjs#140>`_ 37 that the providers should fetch results. 38 39 #. 40 *UrlbarProvidersManager* tells `each <https://searchfox.org/mozilla-central/rev/0ffaecaa075887ab07bf4c607c61ea2faa81b172/browser/components/urlbar/UrlbarProvidersManager.sys.mjs#408>`_ 41 provider to decide if it wants to provide results for this query by calling 42 their `isActive <https://searchfox.org/mozilla-central/rev/0ffaecaa075887ab07bf4c607c61ea2faa81b172/browser/components/urlbar/UrlbarProvidersManager.sys.mjs#422>`_ 43 methods. The provider can decide whether or not it will be active for this 44 query. Some providers are rarely active: for example, 45 *UrlbarProviderTopSites* `isn't active if the user has typed a search string <https://searchfox.org/mozilla-central/rev/0ffaecaa075887ab07bf4c607c61ea2faa81b172/browser/components/urlbar/UrlbarProviderTopSites.sys.mjs#97>`_. 46 47 #. 48 *UrlbarProvidersManager* then tells the *active* providers to fetch results by 49 `calling their startQuery method <https://searchfox.org/mozilla-central/rev/0ffaecaa075887ab07bf4c607c61ea2faa81b172/browser/components/urlbar/UrlbarProvidersManager.sys.mjs#462>`_. 50 51 #. 52 The providers fetch results for the query asynchronously. Each provider 53 fetches results in a different way. As one example, if the default search 54 engine is Google, *UrlbarProviderSearchSuggestions* would send the string 55 "coffee near me" to Google. Google would return a list of suggestions and 56 *UrlbarProviderSearchSuggestions* would create a *UrlbarResult* for each one. 57 58 #. 59 The providers send their results back to *UrlbarProvidersManager*. They do 60 this one result at a time by `calling the addCallback callback <https://searchfox.org/mozilla-central/rev/0ffaecaa075887ab07bf4c607c61ea2faa81b172/browser/components/urlbar/UrlbarProviderSearchSuggestions.sys.mjs#292>`_ 61 passed into startQuery. *UrlbarProvidersManager* takes all the results from all the 62 providers and `puts them into the list of unsorted results <https://searchfox.org/mozilla-central/rev/0ffaecaa075887ab07bf4c607c61ea2faa81b172/browser/components/urlbar/UrlbarProvidersManager.sys.mjs#607>`_. 63 64 Due to the asynchronous and parallel nature of providers, this and the 65 following steps may occur multiple times per search. Some providers may take 66 longer than others to return their results. We don't want to wait for slow 67 providers before showing results. To handle slow providers, 68 *UrlbarProvidersManager* gathers results from providers in "chunks". A timer 69 fires on an internal. Every time the timer fires, we take whatever results we 70 have from the active providers (the "chunk" of results) and perform the 71 following steps. 72 73 #. 74 *UrlbarProvidersManager* `asks <https://searchfox.org/mozilla-central/rev/0ffaecaa075887ab07bf4c607c61ea2faa81b172/browser/components/urlbar/UrlbarProvidersManager.sys.mjs#648>`_ 75 *UrlbarMuxer* to sort the unsorted results. 76 77 #. 78 *UrlbarMuxer* chooses the results that will be shown to the user. It groups 79 and sorts the results to determine the order in which the results will be 80 shown. This process usually involves discarding irrelevant and duplicate 81 results. We also cap results at a limit, defined in the 82 ``browser.urlbar.maxRichResults`` preference. 83 84 #. 85 Once the results are sorted, *UrlbarProvidersManager* 86 `tells UrlbarController <https://searchfox.org/mozilla-central/rev/0ffaecaa075887ab07bf4c607c61ea2faa81b172/browser/components/urlbar/UrlbarProvidersManager.sys.mjs#675>`_ 87 that results are ready to be shown. 88 89 #. 90 *UrlbarController* `sends out a notification <https://searchfox.org/mozilla-central/rev/0ffaecaa075887ab07bf4c607c61ea2faa81b172/browser/components/urlbar/UrlbarController.sys.mjs#213>`_ 91 that results are ready to be shown. *UrlbarView* was `listening <https://searchfox.org/mozilla-central/rev/0ffaecaa075887ab07bf4c607c61ea2faa81b172/browser/components/urlbar/UrlbarView.sys.mjs#662>`_ 92 for that notification. Once the view gets the notification, it `calls #updateResults <https://searchfox.org/mozilla-central/rev/0ffaecaa075887ab07bf4c607c61ea2faa81b172/browser/components/urlbar/UrlbarView.sys.mjs#670>`_ 93 to create `DOM nodes <https://searchfox.org/mozilla-central/rev/0ffaecaa075887ab07bf4c607c61ea2faa81b172/browser/components/urlbar/UrlbarView.sys.mjs#1185>`_ 94 for each *UrlbarResult* and `inserts them <https://searchfox.org/mozilla-central/rev/0ffaecaa075887ab07bf4c607c61ea2faa81b172/browser/components/urlbar/UrlbarView.sys.mjs#1156>`_ 95 into the view's DOM element. 96 97 As described above, we may reach this step multiple times per search. That 98 means we may be updating the view multiple times per keystroke. A view that 99 visibly changes many times after a single keystroke is perceived as 100 "flickering" by the user. As a result, we try to limit the number of times 101 the view needs to update. 102 103 104 .. figure:: assets/lifetime/lifetime.png 105 :alt: A chart with boxes representing the various components of the 106 address bar. An arrow moves between the boxes to illustrate a query 107 moving through the components. 108 :scale: 80% 109 :align: center