Skip to content

Update docs about emscripten_exit_with_live_runtime and pthreads #8167

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Feb 5, 2024
Merged

Update docs about emscripten_exit_with_live_runtime and pthreads #8167

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
444ca7a
update docs about emscripten_exit_with_live_runtime and pthreads
kripken Feb 23, 2019
6b1557c
Merge branch 'main' into doc-pthread
kripken Feb 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion site/source/docs/api_reference/emscripten.h.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -482,8 +482,9 @@ Functions

.. c:function:: void emscripten_exit_with_live_runtime(void)

Exits the program immediately, but leaves the runtime alive so that you can continue to run code later (so global destructors etc., are not run). Note that the runtime is kept alive automatically when you do an asynchronous operation like :c:func:`emscripten_async_call`, so you don't need to call this function for those cases.
Stops the current thread of execution, but leaves the runtime alive so that you can continue to run code later (so global destructors etc., are not run). Note that the runtime is kept alive automatically when you do an asynchronous operation like :c:func:`emscripten_async_call`, so you don't need to call this function for those cases.

In a multithreaded application, this just exits the current thread (and allows running code later in the Web Worker in which it runs).
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ops, sorry, this has slipped my attention.

Originally the design was indeed to do just like what happens with the main thread: the main/pthread_main yields/unwinds out, but remains alive for later event-based calls into it.

Now reading the docs wording, I find that the original function name emscripten_exit_with_live_runtime() is maybe a bit misleading: saying that it both "exits" and also keeps a "live runtime" seem to contradict each other.

Here In a multithreaded application, this just exits the current thread the word exit might be understood by the reader to mean the same as in quit, stop or terminate. But of course the thread (in web, thread == the Worker) is kept alive, and it will execute any events that are passed to it.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes we should probably replace "exits" here with something closer to "unwinds"

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We might want to draw a distinction between "thread" here and "worker". In the current models workers basically never exit and never stop responding to message, but they can stop hosting a pthread and be returned the pool. "emscripten_exit_with_live_runtime" means we continue to host a pthread on the worker.

I'm not sure if other types of worker (i.e. audio worklets) have this concept since IIRC they can already never die to be recycled? Perhaps emscripten_exit_with_live_runtime() should error if called from another type of worker or that is not hosting a pthread (including the main pthread that that set)

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The current implementation of emscripten_exit_with_live_runtime() is though compatible with Audio Worklets and Wasm Workers in that they can be used to achieve the unwind effect. So we might let users do that to be able to reuse/share code.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see. So under Audio Worklets or Wasm Workers this is exactly the same as emscripten_unwind_to_js_event_loop?

May be worth mentioning that here too.


.. c:function:: void emscripten_force_exit(int status)

Expand Down