Window.setImmediate() — Methode · JavaScript-Referenz

Signatur

window.setImmediate(func, ...args)

Beschreibung

setImmediate() stellt eine Funktion als eigene Makrotask in die Warteschlange. Sie läuft, sobald der aktuelle Code und die bereits anstehenden Ereignisse (Eingaben, Rendering) erledigt sind. Damit kann man lang laufende, CPU-intensive Arbeit in kleine Teile zerlegen, ohne die Oberfläche zu blockieren. Anders als setTimeout(fn, 0) gibt es dabei keine Mindestverzögerung: Browser drosseln verschachtelte Timer nach einigen Aufrufen auf mindestens 4 ms, setImmediate() nicht.

Microsoft hat die Methode vorgeschlagen, und nur Internet Explorer 10/11 sowie der alte, auf EdgeHTML basierende Edge haben sie umgesetzt. Chrome, Firefox, Safari und der heutige Chromium-Edge unterstützen sie nicht. Der Standardisierungsvorschlag ist eingestellt, im Web gilt die Methode daher als veraltet.

In Node.js ist setImmediate() dagegen eine feste, global verfügbare Funktion. Dort läuft sie in der „check“-Phase der Ereignisschleife, also direkt nach der I/O-Abfrage. Ihr Gegenstück ist clearImmediate(). Node.js gibt außerdem ein Immediate-Objekt zurück und keine Zahl.

Für Browser-Code gibt es heute bessere Alternativen: scheduler.postTask() und scheduler.yield() (Prioritized Task Scheduling API), MessageChannel als schnelle Makrotask, requestIdleCallback() für Arbeit mit niedriger Priorität und queueMicrotask(), wenn der Code noch vor dem nächsten Rendern laufen soll.

Parameter

Name	Typ	Default	Beschreibung
$func Pflicht	Function		Die Funktion, die ausgeführt werden soll, sobald anstehende Ereignisse und Anzeige-Aktualisierungen erledigt sind.
$...args	any		Beliebig viele zusätzliche Argumente, die beim Aufruf an `func` übergeben werden.

Rückgabewert

Typ

number (Browser) | Immediate (Node.js)

Beschreibung

Eine Kennung für den geplanten Aufruf. Übergibt man sie an clearImmediate(), wird der Aufruf abgebrochen, sofern er noch nicht gelaufen ist.

Beispiele

Browser-taugliche Alternative mit Feature-Erkennung

// Nutzt setImmediate, wenn vorhanden – sonst MessageChannel als schnelle Makrotask
const runImmediate = (() => {
  if (typeof globalThis.setImmediate === 'function') {
    return (fn, ...args) => globalThis.setImmediate(fn, ...args);
  }
  const channel = new MessageChannel();
  const queue = [];
  channel.port1.onmessage = () => {
    const { fn, args } = queue.shift();
    fn(...args);
  };
  return (fn, ...args) => {
    queue.push({ fn, args });
    channel.port2.postMessage(null);
  };
})();

console.log('Start');
runImmediate((name) => console.log(`Hallo ${name}`), 'Welt');
Promise.resolve().then(() => console.log('Mikrotask'));
console.log('Ende');

Start Ende Mikrotask Hallo Welt

Lange Berechnung in Teile zerlegen (Node.js oder IE/Legacy-Edge)

const processInChunks = (items, handleItem, chunkSize = 1000) =>
  new Promise((resolve) => {
    let index = 0;
    const step = () => {
      const end = Math.min(index + chunkSize, items.length);
      for (; index < end; index++) handleItem(items[index]);
      if (index < items.length) {
        setImmediate(step); // Ereignisschleife kurz freigeben
      } else {
        resolve();
      }
    };
    step();
  });

const data = Array.from({ length: 10_000 }, (_, i) => i);
let sum = 0;
await processInChunks(data, (n) => { sum += n; });
console.log('Summe:', sum);

Summe: 49995000

Geplanten Aufruf mit clearImmediate() abbrechen

const id = setImmediate(() => console.log('Wird nie ausgegeben'));
clearImmediate(id);

setImmediate((a, b) => console.log('Ergebnis:', a + b), 2, 3);

Ergebnis: 5

Ausführungsreihenfolge in Node.js innerhalb eines I/O-Callbacks

import { readFile } from 'node:fs';

readFile(import.meta.filename ?? process.argv[1], () => {
  setTimeout(() => console.log('setTimeout'), 0);
  setImmediate(() => console.log('setImmediate'));
  process.nextTick(() => console.log('nextTick'));
});

nextTick setImmediate setTimeout

// Wichtig · Fallstricke

Nicht standardisiert: Im Browser gibt es die Methode nur in IE10/11 und Legacy-Edge. Wer sie ungeprüft aufruft, bekommt in Chrome, Firefox und Safari einen ReferenceError. Deshalb immer mit typeof setImmediate === 'function' prüfen oder eine Alternative verwenden.
Reihenfolge in Node.js: Im Hauptmodul ist nicht vorhersagbar, ob setTimeout(fn, 0) oder setImmediate(fn) zuerst läuft. Innerhalb eines I/O-Callbacks läuft setImmediate immer zuerst. process.nextTick() und Promise-Mikrotasks laufen vor beiden.
Keine Mikrotask: Zwischen zwei setImmediate-Aufrufen kann der Browser rendern und Ereignisse verarbeiten. Das ist so gewollt. Wer Code vor dem nächsten Rendern braucht, nimmt queueMicrotask().
Rekursion: Wenn sich setImmediate ständig selbst neu plant, blockiert das zwar nicht die Oberfläche, belastet die CPU aber voll. Deshalb eine Abbruchbedingung vorsehen.
Polyfills: Bibliotheken wie setimmediate (npm) bilden das Verhalten über MessageChannel oder postMessage nach. Bei postMessage-basierten Polyfills sollte man die Nachrichtenquelle prüfen, damit fremde Frames keine Callbacks auslösen.

Siehe auch

Window.clearImmediate() Window.matchMedia() Window.setInterval() Window.setTimeout() Window.setResizable()