MicroTask.h - mozsearch

Enable keyboard shortcuts

/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*-

 * vim: set ts=8 sts=4 et sw=4 tw=99:

 * This Source Code Form is subject to the terms of the Mozilla Public

 * License, v. 2.0. If a copy of the MPL was not distributed with this

 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#ifndef js_friend_MicroTask_h

#define js_friend_MicroTask_h

#include "mozilla/Attributes.h"

#include "jstypes.h"

#include "js/GCPolicyAPI.h"

#include "js/RootingAPI.h"

#include "js/TypeDecls.h"

#include "js/UniquePtr.h"

#include "js/ValueArray.h"

namespace JS {

// [SMDOC] MicroTasks in SpiderMonkey

//

// To enable higher performance, this header allows an embedding to work with

// a MicroTask queue stored inside the JS engine. This allows optimization of

// tasks by avoiding allocations in important cases.

//

// To make this work, we need some cooperation with the embedding.

//

// The high level thrust of this is that rather than managing the JobQueue

// themselves, embeddings assume that there's a JobQueue available to them

// inside the engine. When 'runJobs' happens, the embedding is responsible

// for pulling jobs of the queue, doing any setup required, then calling

// them.

//

// Embedding jobs are trivially supportable, since a MicroTask job is

// represented as a JS::Value, and thus an embedding job may be put on

// the queue by wrapping it in a JS::Value (e.g. using Private to store

// C++ pointers).

//

// The major requirement is that if a MicroTask identifies as a "JS"

// MicroTask, by passing the IsJSMicrotask predicate, the job must be

// run by calling RunJSMicroTask, while in the realm specified by the

// global returned by GetExecutionGlobalFromJSMicroTask, e.g

//

//    AutoRealm ar(cx, JS::GetExecutionGlobalFromJSMicroTask(job));

//    if (!JS::RunJSMicroTask(cx, job)) {

//      ...

//    }

// A MicroTask is a JS::Value. Using this MicroTask system allows

// embedders to put whatever pointer they would like into the queue.

// The task will be dequeued unchanged.

//

// The major requirement here is that if the MicroTask is a JS

// MicroTask (as determined by IsJSMicroTask), it must be run

// by calling RunJSMicroTask, while in the realm specified by

// GetExecutionGlobalFromJSMicroTask.

//

// An embedding is free to do with non-JS MicroTasks as it

// sees fit.

using MicroTask = JS::Value;

JS_PUBLIC_API bool IsJSMicroTask(Handle<JS::Value> hv);

// Run a MicroTask that is known to be a JS MicroTask. This will crash

// if provided an invalid task kind.

//

// This will return true except on OOM.

JS_PUBLIC_API bool RunJSMicroTask(JSContext* cx, Handle<MicroTask> entry);

// Queue Management. This is done per-JSContext.

//

// Internally we maintain two queues, one for 'debugger' microtasks. These

// are expected in normal operation to either be popped off the queue first,

// or processed separately.

//

// Non-debugger MicroTasks are "regular" microtasks, and go to the regular

// microtask queue.

//

// In general, we highly recommend that most embeddings use only the regular

// microtask queue. The debugger microtask queue mostly exists to support

// patterns used by Gecko.

JS_PUBLIC_API bool EnqueueMicroTask(JSContext* cx, const MicroTask& entry);

JS_PUBLIC_API bool EnqueueDebugMicroTask(JSContext* cx, const MicroTask& entry);

JS_PUBLIC_API bool PrependMicroTask(JSContext* cx, const MicroTask& entry);

// Dequeue the next MicroTask. If there are no MicroTasks of the appropriate

// kind, each of the below API returns JS::NullValue().

//

// The generic DequeueNext will always pull a debugger microtask first,

// if one exists, then a regular microtask if one exists.

// - DequeueNextDebuggerMicroTask only pulls from the debugger queue.

// - DequeueNextRegularMicroTask only pulls from the regular queue.

//

// Internally, these basically do

//

//    if (HasXMicroTask()) { return X.popFront(); } return NullValue()

//

// so checking for emptiness before calling these is not required, and is

// very slightly less efficient.

JS_PUBLIC_API MicroTask DequeueNextMicroTask(JSContext* cx);

JS_PUBLIC_API MicroTask DequeueNextDebuggerMicroTask(JSContext* cx);

JS_PUBLIC_API MicroTask DequeueNextRegularMicroTask(JSContext* cx);

// Returns true if there are -any- microtasks pending in the queue.

JS_PUBLIC_API bool HasAnyMicroTasks(JSContext* cx);

// Returns true if there are any debugger microtasks pending in the queue.

JS_PUBLIC_API bool HasDebuggerMicroTasks(JSContext* cx);

// Returns true if there are any regular (non-debugger) microtasks pending in

// the queue.

JS_PUBLIC_API bool HasRegularMicroTasks(JSContext* cx);

// Returns the length of the regular microtask queue.

JS_PUBLIC_API size_t GetRegularMicroTaskCount(JSContext* cx);

// This is the global associated with the realm RunJSMicroTask expects to be in.

JS_PUBLIC_API JSObject* GetExecutionGlobalFromJSMicroTask(

    const MicroTask& entry);

// To handle cases where the queue needs to be set aside for some reason

// (mostly the Debugger API), we provide a Save and Restore API.

//

// When restoring the saved queue, the JSContext microtask queue must be

// empty -- you cannot drop items by restoring over a non-empty queue

// (so HasAnyMicroTasks must be false).

class SavedMicroTaskQueue {

 public:

  SavedMicroTaskQueue() = default;

  virtual ~SavedMicroTaskQueue() = default;

  SavedMicroTaskQueue(const SavedMicroTaskQueue&) = delete;

  SavedMicroTaskQueue& operator=(const SavedMicroTaskQueue&) = delete;

};

// This will return nullptr (and set OutOfMemory) if the save operation

// fails.

JS_PUBLIC_API js::UniquePtr<SavedMicroTaskQueue> SaveMicroTaskQueue(

    JSContext* cx);

JS_PUBLIC_API void RestoreMicroTaskQueue(

    JSContext* cx, js::UniquePtr<SavedMicroTaskQueue> savedQueue);

// Via the following API functions various host defined data is exposed to the

// embedder (see JobQueue::getHostDefinedData).

//

// All of these may return null if there's no data, or if there's a

// security error.

JS_PUBLIC_API JSObject* MaybeGetHostDefinedDataFromJSMicroTask(

    const MicroTask& entry);

JS_PUBLIC_API JSObject* MaybeGetAllocationSiteFromJSMicroTask(

    const MicroTask& entry);

// In some circumstances an entry may not have host defined data but may

// still have a host defined global;

JS_PUBLIC_API JSObject* MaybeGetHostDefinedGlobalFromJSMicroTask(

    const MicroTask& entry);

JS_PUBLIC_API JSObject* MaybeGetPromiseFromJSMicroTask(const MicroTask& entry);

}  // namespace JS

#endif /* js_friend_MicroTask_h */