This directory contains the base implementation of all worker and worklet types. Also, this contains the implementation of the Web Workers API (Dedicated Worker and Shared Worker) and Worklets API.

Worker / Worklet types

  • Workers are divided into 2 types:
    • In-process workers (Dedicated Workers): A worker of this type always runs in the same renderer process with a parent document that starts the worker.
    • Out-of-process workers (Shared Workers and Service Workers): A worker of this type may run in a different renderer process with a parent document that starts the worker.
  • Worklets are divided into 2 types:
    • Main thread worklets (Paint Worklets and Layout Worklets): A worklet of this type runs on the main thread.
    • Threaded worklets (Audio Worklets and Animation Worklets): A worklet of this type runs on a worker thread.

Worklets always run in the same renderer process with a parent document that starts the worklet like the in-process-workers.

Naming conventions

Classes in this directory are named with the following conventions, there're still some exceptions though.

  • WorkerOrWorklet prefix: Classes commonly used for workers and worklets (e.g., WorkerOrWorkletGlobalScope).
  • Worker / Worklet prefix: Classes used for workers or worklets (e.g., WorkerGlobalScope).
  • Threaded prefix: Classes used for workers and threaded worklets (e.g., ThreadedMessagingProxyBase).
  • MainThreadWorklet prefix: Classes used for main thread worklets (e.g., MainThreadWorkletReportingProxy).

Thread hopping between the main (parent) thread and a worker thread is handled by proxy classes.

  • MessagingProxy is the main (parent) thread side proxy that communicates to the worker thread.
  • ObjectProxy is the worker thread side proxy that communicates to the main (parent) thread. Object indicates a worker/worklet JavaScript object on the parent execution context.

Off-the-main-thread fetch

All worker subresources, and some of worker/worklet top-level scripts, are fetched off-the-main-thread (i.e. on the worker/worklet thread). See following docs for more details.

There are two types of network fetch on the worker/worklet thread: insideSettings and outsideSettings fetch. The terms insideSettings and outsideSettings are originated from HTML spec and Worklet spec.

insideSettings fetch

insideSettings fetch is subresource fetch.

In the spec, insideSettings corresponds to the worker environment settings object of WorkerOrWorkletGlobalScope.

In the implementation, insideSettings roughly corresponds to WorkerOrWorkletGlobalScope. WorkerOrWorkletGlobalScope::Fetcher(), its corresponding WorkerFetchContext, and WorkerOrWorkletGlobalScope::GetContentSecurityPolicy() are used.

Currently, all subresource fetches are already off-the-main-thread.

outsideSettings fetch

outsideSettings fetch is off-the-main-thread top-level worker/worklet script fetch.

In the spec, an outsideSettings is the environment settings object of worker's parent context.

In the implementation, outsideSettings should correspond to Document (or WorkerOrWorkletGlobalScope for nested workers), but the worker thread can't access these objects due to threading restriction. Therefore, we pass FetchClientSettingsObjectSnapshot that contains information of these objects across threads, and create ResourceFetcher, WorkerFetchContext and ContentSecurityPolicy (separate objects from those used for insideSettings fetch) on the worker thread. They work as if the parent context, and are used via WorkerOrWorkletGlobalScope::CreateOutsideSettingsFetcher().

Note that, where off-the-main-thread top-level fetch is NOT enabled (e.g. classic workers), the worker scripts are fetched on the main thread and thus WorkerOrWorkletGlobalScope and the worker thread are not involved.

Metrics

UseCounter

UseCounter is available in all workers and worklets. The count mechanism varies based on worker and worklet types as follows.

  • Dedicated Workers and Worklets: A feature use in a dedicated worker or worklet is propagated to the parent document, and then recorded in the document's UseCounter. For nested dedicated workers, a feature use is propagated up to the ancestor document via parent workers.
  • Shared Workers: A feature use in a shared worker is propagated to all documents connected to the shared worker via mojo calls, and then recorded in their UseCounter.
  • Service Workers: A feature use in a service worker is propagated to all documents and workers being controlled by the service worker via mojo calls, and then recorded in their UseCounter. When a feature use occurs before the service worker finishes installing, the feature use is stored in service worker storage. It is read whenever the installed service worker is started. See content/browser/service_worker/README.md for details.

WorkerOrWorkletGlobalScope::CountUse() is the common entry point. For more details, see Design of UseCounter for workers and crbug 376039.

There are some fundamental metrics.

  • WorkerStart : Counts of new DedicatedWorker() calls in Document and DedicatedWorkerGlobalScope.
  • ClassicDedicatedWorker : Counts of new DedicatedWorker() calls with { type: 'classic' } or without WorkerOptions#type argument.
  • ModuleDedicatedWorker : Counts of new DedicatedWorker() calls with { type: 'module' }.
  • NestedDedicatedWorker : Counts of new DedicatedWorker() calls in DedicatedWorkerGlobalScope.
  • SharedWorkerStart : Counts of new SharedWorker() calls in Document.
  • ClassicSharedWorker : Counts of new SharedWorker() calls with { type: 'classic' } or without WorkerOptions#type argument.
  • ModuleSharedWorker : Counts of new SharedWorker() calls with { type: 'module' }.
  • WorkletAddModule : Counts of Worklet#addModule() calls in Document. This includes all worklet types. Each worklet type has its own counter, too.

Tests

When you add a new worker or worklet type, please consider adding tests in following files and directories to check integration with the underlying worker and worklet infrastructure.

Workers and worklets interact with various features. You should also add tests in the following files and directories to avoid breakage.

References