Reland of Ensure consistent return ordering in base::WaitableEvent::WaitMany

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 <stddef.h>
 
 #include "base/base_export.h"
@@ skipping 94 matching lines @@
 
   // 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, however WaitMany's return "happens after" the |Signal| call
   // that caused it has completed, like |Wait|.
+  //
+  // If more than one WaitableEvent is signaled to unblock WaitMany, the lowest
+  // index among them is returned.
   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_