Scheduler: postTask() Methode

callback

Eine Rückruffunktion, die die Aufgabe implementiert. Der Rückgabewert des Rückrufs wird verwendet, um das Promise zu erfüllen, das von dieser Funktion zurückgegeben wird.

options Optional

Aufgabenoptionen, einschließlich:

priority Optional

Die unveränderliche Priorität der Aufgabe. Eine der folgenden: "user-blocking", "user-visible", "background". Wenn gesetzt, wird diese Priorität für die gesamte Lebensdauer der Aufgabe verwendet und die bei signal gesetzte Priorität ignoriert.

signal Optional

Ein TaskSignal oder AbortSignal, das verwendet werden kann, um die Aufgabe (von ihrem zugehörigen Controller aus) abzubrechen.

Wenn der Parameter options.priority gesetzt ist, kann die Aufgabenpriorität nicht geändert werden, und jede Priorität auf dem Signal wird ignoriert. Andernfalls, wenn das Signal ein TaskSignal ist, wird seine Priorität verwendet, um die anfängliche Aufgabenpriorität festzulegen, und der Controller des Signals kann es später verwenden, um die Aufgabenpriorität zu ändern.

delay Optional

Die Mindestzeit, nach der die Aufgabe der Planerwarteschlange hinzugefügt wird, in ganzen Millisekunden. Die tatsächliche Verzögerung kann höher als angegeben sein, aber nicht weniger. Die Standardverzögerung beträgt 0.

Gibt ein Promise zurück, das mit dem Rückgabewert der callback-Funktion erfüllt wird oder mit dem Abbruchgrund des signal (AbortSignal.reason) abgelehnt werden kann. Das Promise kann auch mit einem Fehler abgelehnt werden, der während der Ausführung des Rückrufs ausgelöst wird.

Die folgenden Beispiele sind leicht vereinfachte Versionen der Live-Beispiele, die unter Prioritized Task Scheduling API > Examples bereitgestellt werden.

Prüfen Sie, ob die priorisierte Aufgabenplanung unterstützt wird, indem Sie das scheduler-Eigenschaft im globalen Scope testen (wie Window.scheduler im Fenster-Scope oder WorkerGlobalScope.scheduler im Worker-Scope).

Zum Beispiel protokolliert der folgende Code "Feature: Supported", wenn die API in diesem Browser unterstützt wird.

// Check that feature is supported
if ("scheduler" in globalThis) {
  console.log("Feature: Supported");
} else {
  console.error("Feature: NOT Supported");
}

Aufgaben werden gepostet, indem im ersten Argument eine Rückruffunktion (Aufgabe) und ein optionales zweites Argument angegeben wird, das zum Festlegen einer Aufgabenpriorität, eines Signals und/oder einer Verzögerung verwendet werden kann. Die Methode gibt ein Promise zurück, das mit dem Rückgabewert der Rückruffunktion erfüllt wird oder mit einem Abbruchfehler oder einem in der Funktion ausgelösten Fehler abgelehnt wird.

Da sie ein Promise zurückgibt, kann postTask() mit anderen Promises verkettet werden. Unten zeigen wir, wie man auf die Erfüllung des Promises mit then oder die Ablehnung mit catch wartet. Die Priorität ist nicht angegeben, daher wird die Standardpriorität user-visible verwendet.

// A function that defines a task
function myTask() {
  return "Task 1: user-visible";
}

// Post task with default priority: 'user-visible' (no other options)
// When the task resolves, Promise.then() logs the result.
scheduler
  .postTask(myTask, { signal: abortTaskController.signal })
  .then((taskResult) => console.log(`${taskResult}`)) // Log resolved value
  .catch((error) => console.error("Error:", error)); // Log error or abort

Die Methode kann auch mit await in einer asynchronen Funktion verwendet werden. Der folgende Code zeigt, wie Sie diesen Ansatz verwenden können, um auf eine user-blocking-Aufgabe zu warten.

function myTask2() {
  return "Task 2: user-blocking";
}

async function runTask2() {
  const result = await scheduler.postTask(myTask2, {
    priority: "user-blocking",
  });
  console.log(result); // 'Task 2: user-blocking'.
}
runTask2();

Aufgabenprioritäten können mit dem priority-Parameter im optionalen zweiten Argument festgelegt werden. Prioritäten, die auf diese Weise gesetzt werden, können nicht geändert werden (sind unveränderlich).

Unten posten wir zwei Gruppen von drei Aufgaben, jede in umgekehrter Reihenfolge ihrer Priorität. Die letzte Aufgabe hat die Standardpriorität. Bei Ausführung protokolliert jede Aufgabe einfach ihre erwartete Reihenfolge (wir warten nicht auf das Ergebnis, da wir dies nicht benötigen, um die Ausführungsreihenfolge zu zeigen).

// three tasks, in reverse order of priority
scheduler.postTask(() => console.log("bkg 1"), { priority: "background" });
scheduler.postTask(() => console.log("usr-vis 1"), {
  priority: "user-visible",
});
scheduler.postTask(() => console.log("usr-blk 1"), {
  priority: "user-blocking",
});

// three more tasks, in reverse order of priority
scheduler.postTask(() => console.log("bkg 2"), { priority: "background" });
scheduler.postTask(() => console.log("usr-vis 2"), {
  priority: "user-visible",
});
scheduler.postTask(() => console.log("usr-blk 2"), {
  priority: "user-blocking",
});

// Task with default priority: user-visible
scheduler.postTask(() => {
  console.log("usr-vis 3 (default)");
});

Die erwartete Ausgabe wird unten gezeigt: Aufgaben werden in Prioritätsreihenfolge und dann in Deklarationsreihenfolge ausgeführt.

usr-blk 1
usr-blk 2
usr-vis 1
usr-vis 2
usr-vis 3 (default)
bkg 1
bkg 2

Aufgabenprioritäten können auch ihren Anfangswert von einem TaskSignal erhalten, das im optionalen zweiten Argument an postTask() übergeben wird. Wenn auf diese Weise festgelegt, kann die Priorität der Aufgabe dann geändert werden durch den Controller, der mit dem Signal verbunden ist.

Der folgende Code zeigt zunächst, wie ein TaskController erstellt wird, wobei die ursprüngliche Priorität seines Signals im TaskController()-Konstruktor auf user-blocking gesetzt wird.

Wir verwenden dann addEventListener(), um einen Ereignis-Listener am Signal des Controllers hinzuzufügen (alternativ könnten wir die TaskSignal.onprioritychange-Eigenschaft verwenden, um einen Ereignis-Handler hinzuzufügen). Der Ereignis-Handler verwendet previousPriority auf dem Ereignis, um die ursprüngliche Priorität zu erhalten, und TaskSignal.priority auf dem Ereignisziel, um die neue/aktuelle Priorität zu erhalten.

// Create a TaskController, setting its signal priority to 'user-blocking'
const controller = new TaskController({ priority: "user-blocking" });

// Listen for 'prioritychange' events on the controller's signal.
controller.signal.addEventListener("prioritychange", (event) => {
  const previousPriority = event.previousPriority;
  const newPriority = event.target.priority;
  console.log(`Priority changed from ${previousPriority} to ${newPriority}.`);
});

Schließlich wird die Aufgabe gepostet, wobei das Signal übergeben wird, und dann ändern wir sofort die Priorität auf background, indem wir TaskController.setPriority() auf dem Controller aufrufen.

// Post task using the controller's signal.
// The signal priority sets the initial priority of the task
scheduler.postTask(() => console.log("Task 1"), { signal: controller.signal });

// Change the priority to 'background' using the controller
controller.setPriority("background");

Die erwartete Ausgabe wird unten gezeigt. Beachten Sie, dass in diesem Fall die Priorität geändert wird, bevor die Aufgabe ausgeführt wird, aber sie hätte genauso gut geändert werden können, während die Aufgabe lief.

// Expected output
// Priority changed from user-blocking to background.
// Task 1

Aufgaben können mit entweder TaskController und AbortController abgebrochen werden, auf genau die gleiche Weise. Der einzige Unterschied besteht darin, dass Sie TaskController verwenden müssen, wenn Sie auch die Aufgabenpriorität festlegen möchten.

Der folgende Code erstellt einen Controller und übergibt dessen Signal an die Aufgabe. Die Aufgabe wird dann sofort abgebrochen. Dies führt dazu, dass das Promise mit einem AbortError abgelehnt wird, der im catch-Block abgefangen und protokolliert wird. Beachten Sie, dass wir auch das abort-Ereignis abhören könnten, das am TaskSignal oder AbortSignal ausgelöst wird, und den Abbruch dort protokollieren könnten.

// Declare a TaskController with default priority
const abortTaskController = new TaskController();
// Post task passing the controller's signal
scheduler
  .postTask(() => console.log("Task executing"), {
    signal: abortTaskController.signal,
  })
  .then((taskResult) => console.log(`${taskResult}`)) // This won't run!
  .catch((error) => console.error("Error:", error)); // Log the error

// Abort the task
abortTaskController.abort();

Aufgaben können verzögert werden, indem eine ganze Zahl von Millisekunden im options.delay-Parameter an postTask() angegeben wird. Dies fügt die Aufgabe effektiv der priorisierten Warteschlange in einem Timeout hinzu, wie es durch setTimeout() erstellt werden könnte. Die delay ist die Mindestzeit, bevor die Aufgabe dem Planer hinzugefügt wird; sie kann länger sein.

Der folgende Code zeigt zwei Aufgaben (als Pfeilfunktionen) mit einer Verzögerung hinzugefügt.

// Post task as arrow function with delay of 2 seconds
scheduler
  .postTask(() => "Task delayed by 2000ms", { delay: 2000 })
  .then((taskResult) => console.log(`${taskResult}`));
scheduler
  .postTask(() => "Next task should complete in about 2000ms", { delay: 1 })
  .then((taskResult) => console.log(`${taskResult}`));