Scheduler: метод postTask()

Метод postTask() интерфейса Scheduler используется для добавления задач, которые должны быть планированы в соответствии с их приоритетом.

Метод позволяет пользователям необязательно указать минимальную задержку перед выполнением задачи, приоритет задачи и сигнал, который может использоваться для изменения приоритета задачи и/или прерывания задачи. Он возвращает промис, который разрешается с результатом функции обратного вызова задачи или отклоняется с причиной прерывания или ошибкой, выброшенной в задаче.

Приоритет задачи может быть изменяемым или неизменяемым. Если приоритет задачи никогда не нужно изменять, то он должен быть установлен с помощью параметра options.priority (любой приоритет, установленный через сигнал, будет игнорироваться). Вы все равно можете передать AbortSignal (у которого нет приоритета) или TaskSignal в параметр options.signal для прерывания задачи.

Если приоритет задачи может потребоваться изменить, параметр options.priority не должен быть установлен. Вместо этого должен быть создан TaskController, и его TaskSignal должен быть передан в options.signal. Приоритет задачи будет инициализирован из приоритета сигнала и впоследствии может быть изменен с помощью связанного с сигналом TaskController.

Если приоритет не установлен, то приоритет задачи по умолчанию равен "user-visible".

Если задана задержка и она больше 0, то выполнение задачи будет отложено как минимум на указанное количество миллисекунд. В противном случае задача немедленно планируется для приоритизации.

callback

Функция обратного вызова, которая реализует задачу. Значение возврата функции обратного вызова используется для разрешения промиса, возвращаемого этой функцией.

options Необязательно

Параметры задачи, включая:

priority Необязательно

Неизменяемый приоритет задачи. Один из: "user-blocking", "user-visible", "background". Если задан, этот приоритет используется на протяжении всего существования задачи, и приоритет, установленный в signal, игнорируется.

signal Необязательно

TaskSignal или AbortSignal, которые могут использоваться для прерывания задачи (из связанного контроллера).

Если параметр options.priority установлен, то приоритет задачи изменить нельзя, и любой приоритет в сигнале игнорируется. В противном случае, если сигнал — TaskSignal, его приоритет используется для установки начального приоритета задачи, и контроллер сигнала может впоследствии использовать его для изменения приоритета задачи.

delay Необязательно

Минимальное количество времени, после которого задача будет добавлена в очередь планировщика, в целых миллисекундах. Фактическая задержка может быть больше указанной, но не меньше. По умолчанию задержка составляет 0.

Возвращает Promise, который разрешается со значением возврата функции callback, или который может быть отклонен с причиной прерывания signal (AbortSignal.reason). Промис также может быть отклонен с ошибкой, брошенной функцией обратного вызова во время выполнения.

Следующие примеры — упрощенные версии реальных примеров, предоставленных в Планирование задач с приоритетами > Примеры.

Проверьте, поддерживается ли планирование задач с приоритетами, проверив свойство scheduler в глобальной области (например, Window.scheduler в области видимости окна или WorkerGlobalScope.scheduler в области видимости рабочего процесса).

Например, код ниже выводит «Функция: Поддерживается», если API поддерживается в этом браузере.

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

Задачи публикуются, указывая функцию обратного вызова (задача) в первом аргументе, и необязательный второй аргумент, который можно использовать для указания приоритета задачи, сигнала и/или задержки. Метод возвращает Promise, который разрешается со значением возврата функции обратного вызова или отклоняется с ошибкой прерывания или ошибкой, выброшенной в функции.

Поскольку он возвращает промис, postTask() может быть связан с другими промисами. Ниже показано, как ожидать разрешения промиса с помощью then или отклонения с помощью catch. Приоритет не указан, поэтому будет использоваться приоритет по умолчанию user-visible.

// 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

Метод также может использоваться с await внутри асинхронной функции. Код ниже демонстрирует, как можно использовать этот подход для ожидания задачи user-blocking.

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();

Приоритеты задач могут быть установлены с помощью параметра priority в необязательном втором аргументе. Приоритеты, установленные таким образом, изменить нельзя (они неизменяемы).

Ниже публикуются две группы из трех задач, каждая в обратном порядке приоритетов. Последняя задача имеет приоритет по умолчанию. При запуске каждая задача просто регистрирует ожидаемый порядок (мы не ждем результата, так как для показа порядка выполнения нам это не нужно).

// 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)");
});

Ожидаемый результат показан ниже: задачи выполняются в порядке приоритета, а затем в порядке объявления.

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

Приоритеты задач также могут получать начальное значение от TaskSignal, переданного в postTask() в необязательном втором аргументе. Если приоритет задан таким образом, приоритет задачи можно изменить с помощью контроллера, связанного с сигналом.

Код ниже сначала демонстрирует, как создать TaskController, установив начальный приоритет его сигнала на user-blocking в TaskController() конструкторе.

Затем мы используем addEventListener() для добавления обработчика событий в сигнал контроллера (мы могли бы альтернативно использовать свойство TaskSignal.onprioritychange для добавления обработчика событий). Обработчик событий использует previousPriority для получения исходного приоритета и TaskSignal.priority для получения нового/текущего приоритета.

// 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}.`);
});

Наконец, задача публикуется, передавая в нее сигнал, а затем мы немедленно изменяем приоритет на background вызовом TaskController.setPriority() для контроллера.

// 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");

Ожидаемый результат показан ниже. Обратите внимание, что в этом случае приоритет меняется до выполнения задачи, но его можно было бы изменить и во время выполнения задачи.

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

Задачи могут быть прерваны, используя либо TaskController, либо AbortController, точно так же. Единственное отличие состоит в том, что вы должны использовать TaskController, если также хотите установить приоритет задачи.

Код ниже создаёт контроллер и передаёт его сигнал задаче. Задача затем немедленно прерывается. Это приводит к тому, что обещание отклоняется с AbortError, которое перехватывается в блоке catch и регистрируется. Обратите внимание, что мы также могли бы прослушивать событие abort, генерируемое на TaskSignal или AbortSignal и регистрировать прерывание там.

// 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();

Задачи могут быть отложены, указав целое число миллисекунд в параметре options.delay для postTask(). Это фактически добавляет задачу в очередь с приоритетом с таймаутом, как может быть создано с помощью setTimeout(). delay — это минимальное количество времени, прежде чем задача добавляется в планировщик; оно может быть больше.

Код ниже демонстрирует две добавленные задачи (как стрелочные функции) с задержкой.

// 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}`));