Mark USE_PTHREADS as legacy. NFC (emscripten-core#18923)

Create a new internal setting called just `PTHREADS` and use that
everywhere internally.

This allows the old setting to be marked as legacy, but still supported
in case existing use JS library code uses it.

ChangeLog.md

@@ -20,6 +20,9 @@ See docs/process.md for more on how version tagging works.
 
 3.1.33 (in development)
 -----------------------
+- The prefered way to enable pthread is now to just the the standard `-pthread`
+  flag.  The `-sUSE_PTHREADS` setting still works but is marked as legacy and
+  will generate a warning in `-sSTRICT` mode.
 - Initial support for C++20 modules.  We have added a very simple test in form
   of `other.test_cpp_module`. (#)
 - Removed `sys/sysctl.h` compatibility header.  We don't implement the function

emcc.py

@@ -380,7 +380,7 @@ def setup_environment_settings():
   settings.ENVIRONMENT_MAY_BE_WORKER = \
       not settings.ENVIRONMENT or \
       'worker' in environments or \
-      (settings.ENVIRONMENT_MAY_BE_NODE and settings.USE_PTHREADS)
+      (settings.ENVIRONMENT_MAY_BE_NODE and settings.PTHREADS)
 
   if not settings.ENVIRONMENT_MAY_BE_WORKER and settings.PROXY_TO_WORKER:
     exit_with_error('If you specify --proxy-to-worker and specify a "-sENVIRONMENT=" directive, it must include "worker" as a target! (Try e.g. -sENVIRONMENT=web,worker)')
@@ -1595,11 +1595,14 @@ def phase_setup(options, state, newargs):
   if settings.MAIN_MODULE or settings.SIDE_MODULE:
     settings.RELOCATABLE = 1
 
+  if 'USE_PTHREADS' in user_settings:
+    settings.PTHREADS = settings.USE_PTHREADS
+
   # Pthreads and Wasm Workers require targeting shared Wasm memory (SAB).
-  if settings.USE_PTHREADS or settings.WASM_WORKERS:
+  if settings.PTHREADS or settings.WASM_WORKERS:
     settings.SHARED_MEMORY = 1
 
-  if settings.USE_PTHREADS and '-pthread' not in newargs:
+  if settings.PTHREADS and '-pthread' not in newargs:
     newargs += ['-pthread']
   elif settings.SHARED_MEMORY:
     if '-matomics' not in newargs:
@@ -1751,7 +1754,7 @@ def include_and_export(name):
     if not settings.EXPORT_ES6 and settings.EXPORT_NAME == 'Module':
       exit_with_error('pthreads + MODULARIZE currently require you to set -sEXPORT_NAME=Something (see settings.js) to Something != Module, so that the .worker.js file can work')
 
-    # MODULARIZE+USE_PTHREADS mode requires extra exports out to Module so that worker.js
+    # MODULARIZE+PTHREADS mode requires extra exports out to Module so that worker.js
     # can access them:
 
     # general threading variables:
@@ -2099,7 +2102,7 @@ def phase_linker_setup(options, state, newargs):
       '$mergeLibSymbols',
     ]
 
-  if settings.USE_PTHREADS:
+  if settings.PTHREADS:
     settings.DEFAULT_LIBRARY_FUNCS_TO_INCLUDE += [
       '$registerTLSInit',
     ]
@@ -2210,7 +2213,7 @@ def phase_linker_setup(options, state, newargs):
     # HTML output creates a singleton instance, and it does so without the
     # Promise. However, in Pthreads mode the Promise is used for worker
     # creation.
-    if settings.MINIMAL_RUNTIME and options.oformat == OFormat.HTML and not settings.USE_PTHREADS:
+    if settings.MINIMAL_RUNTIME and options.oformat == OFormat.HTML and not settings.PTHREADS:
       settings.EXPORT_READY_PROMISE = 0
 
   if settings.LEGACY_VM_SUPPORT:
@@ -2328,7 +2331,7 @@ def phase_linker_setup(options, state, newargs):
   if settings.FETCH and final_suffix in EXECUTABLE_ENDINGS:
     state.forced_stdlibs.append('libfetch')
     settings.JS_LIBRARIES.append((0, 'library_fetch.js'))
-    if settings.USE_PTHREADS:
+    if settings.PTHREADS:
       settings.FETCH_WORKER_FILE = unsuffixed_basename(target) + '.fetch.js'
 
   if settings.DEMANGLE_SUPPORT:
@@ -2398,7 +2401,7 @@ def phase_linker_setup(options, state, newargs):
     # overrides that.
     default_setting('ABORTING_MALLOC', 0)
 
-  if settings.USE_PTHREADS:
+  if settings.PTHREADS:
     setup_pthreads(target)
     settings.JS_LIBRARIES.append((0, 'library_pthread.js'))
     if settings.PROXY_TO_PTHREAD:
@@ -2630,7 +2633,7 @@ def check_memory_setting(setting):
     # are based on experimentation with different tests/programs under asan and
     # lsan.
     settings.INITIAL_MEMORY += 50 * 1024 * 1024
-    if settings.USE_PTHREADS:
+    if settings.PTHREADS:
       settings.INITIAL_MEMORY += 50 * 1024 * 1024
 
   if settings.USE_OFFSET_CONVERTER and settings.WASM2JS:
@@ -3176,7 +3179,7 @@ def phase_final_emitting(options, state, target, wasm_target, memfile):
   # write_file(final_js, src)
 
   target_dir = os.path.dirname(os.path.abspath(target))
-  if settings.USE_PTHREADS:
+  if settings.PTHREADS:
     worker_output = os.path.join(target_dir, settings.PTHREAD_WORKER_FILE)
     contents = shared.read_and_preprocess(utils.path_from_root('src/worker.js'), expand_macros=True)
     write_file(worker_output, contents)
@@ -3577,9 +3580,11 @@ def consume_arg_file():
         options.output_eol = '\n'
       else:
         exit_with_error(f'Invalid value "{style}" to --output_eol!')
-    # Record USE_PTHREADS setting because it controls whether --shared-memory is passed to lld
+    # Record PTHREADS setting because it controls whether --shared-memory is passed to lld
     elif arg == '-pthread':
-      settings_changes.append('USE_PTHREADS=1')
+      settings.PTHREADS = 1
+      # Also set the legacy setting name, in case use JS code depends on it.
+      settings.USE_PTHREADS = 1
     elif arg == '-pthreads':
       exit_with_error('unrecognized command-line option ‘-pthreads’; did you mean ‘-pthread’?')
     elif arg in ('-fno-diagnostics-color', '-fdiagnostics-color=never'):
@@ -3707,7 +3712,7 @@ def phase_binaryen(target, options, wasm_target):
     # adds some >>> 0 things, while growth will replace a HEAP8 with a call to
     # a method to get the heap, and that call would not be recognized by the
     # unsigning pass
-    if settings.USE_PTHREADS and settings.ALLOW_MEMORY_GROWTH:
+    if settings.PTHREADS and settings.ALLOW_MEMORY_GROWTH:
       with ToolchainProfiler.profile_block('apply_wasm_memory_growth'):
         final_js = building.apply_wasm_memory_growth(final_js)
 
@@ -3881,15 +3886,15 @@ def modularize():
     'capture_module_function_for_audio_worklet': 'globalThis.AudioWorkletModule = Module;' if settings.AUDIO_WORKLET and settings.MODULARIZE else ''
   }
 
-  if settings.MINIMAL_RUNTIME and not settings.USE_PTHREADS:
+  if settings.MINIMAL_RUNTIME and not settings.PTHREADS:
     # Single threaded MINIMAL_RUNTIME programs do not need access to
     # document.currentScript, so a simple export declaration is enough.
     src = 'var %s=%s' % (settings.EXPORT_NAME, src)
   else:
     script_url_node = ''
     # When MODULARIZE this JS may be executed later,
     # after document.currentScript is gone, so we save it.
-    # In EXPORT_ES6 + USE_PTHREADS the 'thread' is actually an ES6 module webworker running in strict mode,
+    # In EXPORT_ES6 + PTHREADS the 'thread' is actually an ES6 module webworker running in strict mode,
     # so doesn't have access to 'document'. In this case use 'import.meta' instead.
     if settings.EXPORT_ES6 and settings.USE_ES6_IMPORT_META:
       script_url = 'import.meta.url'

emscripten.py

@@ -144,7 +144,7 @@ def update_settings_glue(wasm_file, metadata):
   if settings.ASYNCIFY == 2:
     settings.BINARYEN_FEATURES += ['--enable-reference-types']
 
-  if settings.USE_PTHREADS:
+  if settings.PTHREADS:
     assert '--enable-threads' in settings.BINARYEN_FEATURES
   if settings.MEMORY64:
     assert '--enable-memory64' in settings.BINARYEN_FEATURES
@@ -625,7 +625,7 @@ def add_standard_wasm_imports(send_items_map):
 
   if settings.IMPORTED_MEMORY:
     memory_import = 'wasmMemory'
-    if settings.MODULARIZE and settings.USE_PTHREADS:
+    if settings.MODULARIZE and settings.PTHREADS:
       # Pthreads assign wasmMemory in their worker startup. In MODULARIZE mode, they cannot assign inside the
       # Module scope, so lookup via Module as well.
       memory_import += " || Module['wasmMemory']"

src/jsifier.js

@@ -159,7 +159,7 @@ function ${name}(${args}) {
           throw new Error(`Invalid proxyingMode ${symbol}__proxy: '${proxyingMode}' specified!`);
         }
         const sync = proxyingMode === 'sync';
-        if (USE_PTHREADS) {
+        if (PTHREADS) {
           snippet = modifyFunction(snippet, (name, args, body) => `
 function ${name}(${args}) {
 if (ENVIRONMENT_IS_PTHREAD)
@@ -489,7 +489,7 @@ function ${name}(${args}) {
       print(indentify(item.JS || '', 2));
     }
 
-    if (USE_PTHREADS) {
+    if (PTHREADS) {
       print('\n // proxiedFunctionTable specifies the list of functions that can be called either synchronously or asynchronously from other threads in postMessage()d or internally queued events. This way a pthread in a Worker can synchronously access e.g. the DOM on the main thread.');
       print('\nvar proxiedFunctionTable = [' + proxiedFunctionTable.join() + '];\n');
     }

src/library.js

@@ -70,7 +70,7 @@ mergeInto(LibraryManager.library, {
     checkUnflushedContent();
 #endif // ASSERTIONS && !EXIT_RUNTIME
 
-#if USE_PTHREADS
+#if PTHREADS
     if (ENVIRONMENT_IS_PTHREAD) {
       // implict exit can never happen on a pthread
 #if ASSERTIONS
@@ -89,7 +89,7 @@ mergeInto(LibraryManager.library, {
 #if PTHREADS_DEBUG
     err('main thread called exit: keepRuntimeAlive=' + keepRuntimeAlive() + ' (counter=' + runtimeKeepaliveCounter + ')');
 #endif // PTHREADS_DEBUG
-#endif // USE_PTHREADS
+#endif // PTHREADS
 
 #if EXIT_RUNTIME
     if (!keepRuntimeAlive()) {
@@ -2357,7 +2357,7 @@ mergeInto(LibraryManager.library, {
                                "  };\n" +
                                "} else " +
 #endif
-#if USE_PTHREADS && !AUDIO_WORKLET
+#if PTHREADS && !AUDIO_WORKLET
 // Pthreads need their clocks synchronized to the execution of the main thread, so, when using them,
 // make sure to adjust all timings to the respective time origins.
                                "_emscripten_get_now = () => performance.timeOrigin + performance.now();\n",
@@ -2371,7 +2371,7 @@ mergeInto(LibraryManager.library, {
 // AudioWorkletGlobalScope does not have performance.now() (https://github.com/WebAudio/web-audio-api/issues/2527), so if building with
 // Audio Worklets enabled, do a dynamic check for its presence.
                                "if (typeof performance != 'undefined' && performance.now) {\n" +
-#if USE_PTHREADS
+#if PTHREADS
                                "  _emscripten_get_now = () => performance.timeOrigin + performance.now();\n" +
 #else
                                "  _emscripten_get_now = () => performance.now();\n" +
@@ -3044,7 +3044,7 @@ mergeInto(LibraryManager.library, {
   $runMainThreadEmAsm__sig: 'iippi',
   $runMainThreadEmAsm: function(code, sigPtr, argbuf, sync) {
     var args = readEmAsmArgs(sigPtr, argbuf);
-#if USE_PTHREADS
+#if PTHREADS
     if (ENVIRONMENT_IS_PTHREAD) {
       // EM_ASM functions are variadic, receiving the actual arguments as a buffer
       // in memory. the last parameter (argBuf) points to that data. We need to
@@ -3564,7 +3564,7 @@ mergeInto(LibraryManager.library, {
   },
 
   $maybeExit__deps: ['exit', '$handleException',
-#if USE_PTHREADS
+#if PTHREADS
     '_emscripten_thread_exit',
 #endif
   ],
@@ -3582,7 +3582,7 @@ mergeInto(LibraryManager.library, {
       dbg('maybeExit: calling exit() implicitly after user callback completed: ' + EXITSTATUS);
 #endif
       try {
-#if USE_PTHREADS
+#if PTHREADS
         if (ENVIRONMENT_IS_PTHREAD) __emscripten_thread_exit(EXITSTATUS);
         else
 #endif

src/library_browser.js

@@ -846,7 +846,7 @@ var LibraryBrowser = {
     onload = {{{ makeDynCall('v', 'onload') }}};
     onerror = {{{ makeDynCall('v', 'onerror') }}};
 
-#if USE_PTHREADS
+#if PTHREADS
     if (ENVIRONMENT_IS_PTHREAD) {
       err('emscripten_async_load_script("' + UTF8ToString(url) + '") failed, emscripten_async_load_script is currently not available in pthreads!');
       return onerror ? onerror() : undefined;
@@ -1049,7 +1049,7 @@ var LibraryBrowser = {
       GL.newRenderingFrameStarted();
 #endif
 
-#if USE_PTHREADS && OFFSCREEN_FRAMEBUFFER && GL_SUPPORT_EXPLICIT_SWAP_CONTROL
+#if PTHREADS && OFFSCREEN_FRAMEBUFFER && GL_SUPPORT_EXPLICIT_SWAP_CONTROL
       // If the current GL context is a proxied regular WebGL context, and was initialized with implicit swap mode on the main thread, and we are on the parent thread,
       // perform the swap on behalf of the user.
       if (typeof GL != 'undefined' && GL.currentContext && GL.currentContextIsProxied) {

src/library_dylink.js

@@ -719,7 +719,7 @@ var LibraryDylink = {
         }
 #if STACK_OVERFLOW_CHECK >= 2
         if (moduleExports['__set_stack_limits']) {
-#if USE_PTHREADS
+#if PTHREADS
           // When we are on an uninitialized pthread we delay calling
           // __set_stack_limits until $setDylinkStackLimits.
           if (!ENVIRONMENT_IS_PTHREAD || runtimeInitialized)
@@ -762,7 +762,7 @@ var LibraryDylink = {
 #endif
 
         // initialize the module
-#if USE_PTHREADS
+#if PTHREADS
         // Only one thread should call __wasm_call_ctors, but all threads need
         // to call _emscripten_tls_init
         registerTLSInit(moduleExports['_emscripten_tls_init'], instance.exports, metadata)
@@ -788,7 +788,7 @@ var LibraryDylink = {
               __ATINIT__.push(init);
             }
           }
-#if USE_PTHREADS
+#if PTHREADS
         }
 #endif
         return moduleExports;
@@ -826,8 +826,8 @@ var LibraryDylink = {
     return loadModule();
   },
 
-#if STACK_OVERFLOW_CHECK >= 2 && USE_PTHREADS
-  // With USE_PTHREADS we load libraries before we are running a pthread and
+#if STACK_OVERFLOW_CHECK >= 2 && PTHREADS
+  // With PTHREADS we load libraries before we are running a pthread and
   // therefore before we have a stack.  Instead we delay calling
   // `__set_stack_limits` until we start running a thread.  We also need to call
   // this again for each new thread that the runs on a worker (since each thread

src/library_fetch.js

@@ -7,7 +7,7 @@
 #include Fetch.js
 
 var LibraryFetch = {
-#if USE_PTHREADS
+#if PTHREADS
   $Fetch__postset: 'if (!ENVIRONMENT_IS_PTHREAD) Fetch.staticInit();',
 #else
   $Fetch__postset: 'Fetch.staticInit();',