cautionary comment in futexWake

Summary:
Add a description of the fault-after-unlock problem that can
occur when a synchronization object is used to guard its own
destruction.

Test Plan: comment change only

Reviewed By: alikhtarov@fb.com

Subscribers: trunkagent, folly-diffs@

FB internal diff: D1808446

Signature: t1:1808446:1422481173:83c0369e2277cd5b8cf6377fcd92b132019611a7

diff --git a/folly/detail/Futex.h b/folly/detail/Futex.h
index a38b4423e057f1ee94e0cddb792417d807832fb6..a6a5a06b2f6389ddcd034df20eada6e4beeb0d94 100644 (file)
--- a/folly/detail/Futex.h
+++ b/folly/detail/Futex.h
@@ -102,8 +102,14 @@ struct Futex : Atom<uint32_t>, boost::noncopyable {
     }
   }
 
-  /** Wakens up to count waiters where (waitMask & wakeMask) != 0,
-   *  returning the number of awoken threads. */
+  /** Wakens up to count waiters where (waitMask & wakeMask) !=
+   *  0, returning the number of awoken threads, or -1 if an error
+   *  occurred.  Note that when constructing a concurrency primitive
+   *  that can guard its own destruction, it is likely that you will
+   *  want to ignore EINVAL here (as well as making sure that you
+   *  never touch the object after performing the memory store that
+   *  is the linearization point for unlock or control handoff).
+   *  See https://sourceware.org/bugzilla/show_bug.cgi?id=13690 */
   int futexWake(int count = std::numeric_limits<int>::max(),
                 uint32_t wakeMask = -1);