WaitableEvent: allow TimedWait to synchronise its own destruction.

base/synchronization/waitable_event.h

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef BASE_SYNCHRONIZATION_WAITABLE_EVENT_H_
 #define BASE_SYNCHRONIZATION_WAITABLE_EVENT_H_
 
 #include "base/base_export.h"
 #include "base/basictypes.h"
 
@@ skipping 54 matching lines @@
   void Reset();
 
   // Put the event in the signaled state.  Causing any thread blocked on Wait
   // to be woken up.
   void Signal();
 
   // Returns true if the event is in the signaled state, else false.  If this
   // is not a manual reset event, then this test will cause a reset.
   bool IsSignaled();
 
-  // Wait indefinitely for the event to be signaled.
+  // Wait indefinitely for the event to be signaled. Wait's return "happens
+  // after" |Signal| has completed. This means that it's safe for a
+  // WaitableEvent to synchronise its own destruction, like this:
+  //
+  //   WaitableEvent *e = new WaitableEvent;
+  //   SendToOtherThread(e);
+  //   e.Wait();

[yhirano, 2014/08/01 01:12:47]

e->

+  //   delete e;
   void Wait();
 
   // Wait up until max_time has passed for the event to be signaled.  Returns
   // true if the event was signaled.  If this method returns false, then it
   // does not necessarily mean that max_time was exceeded.
+  //
+  // TimedWait can synchronise its own destruction like |Wait|.
   bool TimedWait(const TimeDelta& max_time);
 
 #if defined(OS_WIN)
   HANDLE handle() const { return handle_; }
 #endif
 
   // Wait, synchronously, on multiple events.
   //   waitables: an array of WaitableEvent pointers
   //   count: the number of elements in @waitables
   //
   // returns: the index of a WaitableEvent which has been signaled.
   //
   // You MUST NOT delete any of the WaitableEvent objects while this wait is
-  // happening.
+  // happening, however WaitMany's return "happens after" the |Signal| call
+  // that caused it has completed, like |Wait|.
   static size_t WaitMany(WaitableEvent** waitables, size_t count);
 
   // For asynchronous waiting, see WaitableEventWatcher
 
   // This is a private helper class. It's here because it's used by friends of
   // this class (such as WaitableEventWatcher) to be able to enqueue elements
   // of the wait-list
   class Waiter {
    public:
     // Signal the waiter to wake up.
@@ skipping 68 matching lines @@
 
   scoped_refptr<WaitableEventKernel> kernel_;
 #endif
 
   DISALLOW_COPY_AND_ASSIGN(WaitableEvent);
 };
 
 }  // namespace base
 
 #endif  // BASE_SYNCHRONIZATION_WAITABLE_EVENT_H_