fiber.h

Fasern sind leichte, kooperative Ausführungsthreads. Der fiber.h Header definiert eine Low-Level-API zur Manipulation von Fasern in Emscripten. Fasern werden mit Asynchronem Code implementiert, daher müssen Sie Ihr Programm mit ASYNCIFY verknüpfen, wenn Sie diese verwenden möchten.

Fasern sind als Bausteine für asynchrone Kontrollflusskonstrukte, wie z.B. Coroutinen, gedacht. Sie ersetzen die veraltete Coroutine-API, die im Fastcomp-Backend verfügbar war. Diese API ist ähnlich, aber verschieden von POSIX ucontext.

Inhaltsverzeichnis

API-Referenz

Typen

emscripten_fiber_t

Diese Struktur repräsentiert eine Faser-Kontext-Fortsetzung. Die Laufzeit hält keine Referenzen auf diese Objekte; sie enthalten nur Informationen, die für die Kontextumschaltung benötigt werden. Die Switch-Operation aktualisiert jedoch einige der Inhalte.

void *stack_base

Obere Grenze des C-Stack-Bereichs. Der Stack wächst nach unten, daher ist dies die Anfangsposition des Stack-Pointers. Muss mindestens 16-Byte-aligned sein.

void *stack_limit

Untergrenze des C-Stack-Bereichs. Muss unter emscripten_fiber_t.stack_base liegen.

void *stack_ptr

Aktuelle Position des Stack-Pointers. Muss zwischen emscripten_fiber_t.stack_base und emscripten_fiber_t.stack_limit liegen.

em_arg_callback_func entry

Einstiegspunkt. Wenn nicht NULL, wird diese Funktion aufgerufen, wenn die Faser gewechselt wird. Andernfalls wird emscripten_fiber_t.asyncify_data verwendet, um den Aufrufstack zurückzuspulen.

void *user_data

Opaquer Zeiger, unverändert an emscripten_fiber_t.entry übergeben.

asyncify_data_t asyncify_data

Asyncify-Datenstruktur. Wird zum Ent- und Zurückspulen des Call Stacks beim Wechsel von Fasern verwendet.

asyncify_data_t
void *stack_ptr

Aktuelle Position des Asyncify-Stack-Pointers.

Der Asyncify-Stack ist vom C-Stack getrennt. Er enthält den Call-Stack sowie den Zustand der WASM-Locals. Im Gegensatz zum C-Stack wächst er nach oben.

void *stack_limit

Obere Grenze des Asyncify-Stack-Bereichs.

int rewind_id

Opaques Handle auf die Funktion, die aufgerufen werden muss, um den Call-Stack zurückzuspulen. Dieser Wert ist nur für die Laufzeit von Bedeutung.

Warnung

Rewind-IDs sind derzeit threadspezifisch. Dies macht es unmöglich, eine Faser fortzusetzen, die von einem anderen Thread gestartet wurde.

Funktionen

void emscripten_fiber_init(emscripten_fiber_t *fiber, em_arg_callback_func entry_func, void *entry_func_arg, void *c_stack, size_t c_stack_size, void *asyncify_stack, size_t asyncify_stack_size)

Initialisiert einen Faser-Kontext. Dieser kann dann durch Aufruf von emscripten_fiber_swap() betreten werden.

Parameter

  • fiber (emscripten_fiber_t*) – Zeiger auf die Faserstruktur.

  • entry_func (em_arg_callback_func) – Einstiegsfunktion, wird aufgerufen, wenn die Faser zum ersten Mal betreten wird.

  • entry_func_arg (void*) – Opaquer Zeiger, der an entry_func übergeben wird.

  • c_stack (void*) – Zeiger auf den Speicherbereich, der für den C-Stack verwendet werden soll. Muss mindestens 16-Byte-aligned sein. Dieser zeigt auf die untere Grenze des Stacks, unabhängig von der Wachstumsrichtung.

  • c_stack_size (size_t) – Größe des C-Stack-Speicherbereichs, in Bytes.

  • asyncify_stack (void*) – Zeiger auf den Speicherbereich, der für den Asyncify-Stack verwendet werden soll. Keine besonderen Ausrichtungsanforderungen.

  • asyncify_stack_size (size_t) – Größe des Asyncify-Stack-Speicherbereichs, in Bytes.

Hinweis

Gibt entry_func zurück, wird das gesamte Programm beendet, als ob main zurückgegeben hätte. Um dies zu vermeiden, können Sie emscripten_fiber_swap() verwenden, um zu einer anderen Faser zu springen.

void emscripten_fiber_init_from_current_context(emscripten_fiber_t *fiber, void *asyncify_stack, size_t asyncify_stack_size)

Initialisiert eine Faser basierend auf dem aktuell aktiven Kontext teilweise. Dies ist erforderlich, um von einer Faser zurück in den ursprünglichen Kontext des Threads zu wechseln.

Diese Funktion setzt emscripten_fiber_t.stack_base und emscripten_fiber_t.stack_limit so, dass sie auf die aktuellen Stack-Grenzen verweisen, setzt emscripten_fiber_t.entry auf NULL und lässt emscripten_fiber_t.asyncify_data auf den bereitgestellten Asyncify-Stack-Speicher verweisen. Andere Felder werden nicht geändert.

Durch diese Funktion initialisierte Fasern sind nicht vollständig. Sie sind nur geeignet, als erstes Argument an emscripten_fiber_swap() übergeben zu werden. Dies vervollständigt die Fortsetzung und ermöglicht es, mit einem weiteren emscripten_fiber_swap() zum ursprünglichen Kontext zurückzukehren, wie bei einer normalen Faser.

Parameter

  • fiber (emscripten_fiber_t*) – Zeiger auf die Faserstruktur.

  • asyncify_stack (void*) – Zeiger auf den Speicherbereich, der für den Asyncify-Stack verwendet werden soll. Keine besonderen Ausrichtungsanforderungen.

  • asyncify_stack_size (size_t) – Größe des Asyncify-Stack-Speicherbereichs, in Bytes.

void emscripten_fiber_swap(emscripten_fiber_t *old_fiber, emscripten_fiber_t *new_fiber)

Führt einen Faser-Kontextwechsel durch.

Parameter

  • old_fiber (emscripten_fiber_t*) – Faser, die den aktuellen Kontext darstellt. Sie wird teilweise aktualisiert, so dass ein Zurückwechseln über einen weiteren Aufruf von emscripten_fiber_swap() so aussieht, als würde es von dem ursprünglichen Aufruf zurückkehren.

  • new_fiber (emscripten_fiber_t*) – Faser, die den Zielkontext darstellt. Wenn die Faser einen Einstiegspunkt hat, wird dieser im neuen Kontext aufgerufen und auf NULL gesetzt. Andernfalls wird emscripten_fiber_t.asyncify_data verwendet, um den Call-Stack zurückzuspulen. Wenn die Faser ungültig oder unvollständig ist, ist das Verhalten undefiniert.