[NFC] Add more comments to pthread mailbox infrastructure (#20511)

Also make a tiny simplification to a use of `callUserCallback`.

Author: tlively

src/library_pthread.js

@@ -1226,16 +1226,21 @@ var LibraryPThread = {
     // pthread_self to return 0 if there is no live runtime.
     var pthread_ptr = _pthread_self();
     if (pthread_ptr) {
-      // If we are using Atomics.waitAsync as our notification mechanism, wait for
-      // a notification before processing the mailbox to avoid missing any work.
+      // If we are using Atomics.waitAsync as our notification mechanism, wait
+      // for a notification before processing the mailbox to avoid missing any
+      // work that could otherwise arrive after we've finished processing the
+      // mailbox and before we're ready for the next notification.
       __emscripten_thread_mailbox_await(pthread_ptr);
-      callUserCallback(() => __emscripten_check_mailbox());
+      callUserCallback(__emscripten_check_mailbox);
     }
   },
 
   _emscripten_thread_mailbox_await__deps: ['$checkMailbox'],
   _emscripten_thread_mailbox_await: (pthread_ptr) => {
     if (typeof Atomics.waitAsync === 'function') {
+      // Wait on the pthread's initial self-pointer field because it is easy and
+      // safe to access from sending threads that need to notify the waiting
+      // thread.
       // TODO: How to make this work with wasm64?
       var wait = Atomics.waitAsync(HEAP32, {{{ getHeapOffset('pthread_ptr', 'i32') }}}, pthread_ptr);
 #if ASSERTIONS
@@ -1245,8 +1250,14 @@ var LibraryPThread = {
       var waitingAsync = pthread_ptr + {{{ C_STRUCTS.pthread.waiting_async }}};
       Atomics.store(HEAP32, {{{ getHeapOffset('waitingAsync', 'i32') }}}, 1);
     }
+    // If `Atomics.waitAsync` is not implemented, then we will always fall back
+    // to postMessage and there is no need to do anything here.
   },
 
+  // PostMessage is used to notify threads instead of Atomics.notify whenever
+  // the environment does not implement Atomics.waitAsync or when messaging a
+  // new thread that has not had a chance to initialize itself and execute
+  // Atomics.waitAsync to prepare for the notification.
   _emscripten_notify_mailbox_postmessage__deps: ['$checkMailbox'],
   _emscripten_notify_mailbox_postmessage: (targetThreadId, currThreadId, mainThreadId) => {
     if (targetThreadId == currThreadId) {

system/lib/libc/musl/src/internal/pthread_impl.h

@@ -97,9 +97,13 @@ struct pthread {
 	// wait until it reaches 0, at which point the mailbox is considered
 	// closed and no further messages will be enqueued.
 	_Atomic int mailbox_refcount;
-	// Whether the thread has executed a `waitAsync` on this pthread struct
-	// and can be notified of new mailbox messages via `Atomics.notify`.
-	// Otherwise the notification has to fall back to the postMessage path.
+	// Whether the thread has executed an `Atomics.waitAsync` on this
+	// pthread struct and can be notified of new mailbox messages via
+	// `Atomics.notify`. Otherwise, such as when the environment does not
+	// implement `Atomics.waitAsync` or when the thread has not had a chance
+	// to initialize itself yet, the notification has to fall back to the
+	// postMessage path. Once this becomes true, it remains true so we never
+	// fall back to postMessage unnecessarily.
 	_Atomic int waiting_async;
 #endif
 #ifdef EMSCRIPTEN_DYNAMIC_LINKING