[runtime] Clean up documentation of the swift_once() implementation.

Author: Greg Parker

lib/IRGen/SwiftTargetInfo.cpp

@@ -133,11 +133,12 @@ SwiftTargetInfo SwiftTargetInfo::get(IRGenModule &IGM) {
   // Prepare generic target information.
   SwiftTargetInfo target(triple.getObjectFormat(), pointerSize);
 
-  // On Apple platforms, we implement "once" using dispatch_once, which exposes
-  // -1 as ABI for the "done" value.
+  // On Apple platforms, we implement "once" using dispatch_once,
+  // which exposes a barrier-free inline path with -1 as the "done" value.
   if (triple.isOSDarwin())
     target.OnceDonePredicateValue = -1L;
-  // TODO: Do we know this for Linux?
+  // Other platforms use std::call_once() and we don't
+  // assume that they have a barrier-free inline fast path.
 
   switch (triple.getArch()) {
   case llvm::Triple::x86_64:

stdlib/public/runtime/Once.cpp

@@ -23,12 +23,20 @@ using namespace swift;
 
 #ifdef __APPLE__
 
-// On OS X and iOS, swift_once is implemented using GCD.
+// On macOS and iOS, swift_once is implemented using GCD.
+// The compiler emits an inline check matching the barrier-free inline fast
+// path of dispatch_once(). See SwiftTargetInfo.OnceDonePredicateValue.
 
 #include <dispatch/dispatch.h>
 static_assert(std::is_same<swift_once_t, dispatch_once_t>::value,
               "swift_once_t and dispatch_once_t must stay in sync");
+#else
+
+// On non-Darwin platforms we do not assume any barrier-free inline path
+// and SwiftTargetInfo.OnceDonePredicateValue is unset in the compiler.
+
 #endif
+
 // The compiler generates the swift_once_t values as word-sized zero-initialized
 // variables, so we want to make sure swift_once_t isn't larger than the
 // platform word or the function below might overwrite something it shouldn't.
@@ -44,14 +52,6 @@ void swift::swift_once(swift_once_t *predicate, void (*fn)(void *)) {
 #elif defined(__CYGWIN__)
   _swift_once_f(predicate, nullptr, fn);
 #else
-  // FIXME: We're relying here on the coincidence that libstdc++ uses pthread's
-  // pthread_once, and that on glibc pthread_once follows a compatible init
-  // process (the token is a word that is atomically incremented from 0 to
-  // 1 to 2 during initialization) to work. We should implement our own version
-  // that we can rely on to continue to work that way.
-  // The MSVC port also relies on this, because the std::call_once on MSVC
-  // follows the compatible init process.
-  // For more information, see rdar://problem/18499385
   std::call_once(*predicate, [fn]() { fn(nullptr); });
 #endif
 }