Mark USE_PTHREADS as legacy. NFC

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.

Author: sbc100

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 a legacy and
+ will generte 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:
@@ -2327,7 +2330,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:
@@ -2397,7 +2400,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:
@@ -2629,7 +2632,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:
@@ -3175,7 +3178,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)
@@ -3576,9 +3579,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'):
@@ -3706,7 +3711,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)
 
@@ -3880,15 +3885,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();',