Mojo EDK: Circulate MojoArmWatcher outputs to avoid starvation

mojo/public/c/system/watcher.h

 // Copyright 2017 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 MOJO_PUBLIC_C_SYSTEM_WATCHER_H_
 #define MOJO_PUBLIC_C_SYSTEM_WATCHER_H_
 
 #include <stdint.h>
 
 #include "mojo/public/c/system/system_export.h"
@@ skipping 149 matching lines @@
 //       notified immediately upon arming the watcher. If |num_handles| is
 //       non-null, this assumes there is enough space for |*num_handles| entries
 //       in each of the subsequent output buffer arguments.
 //
 //       At most that many entries are placed in the output buffers,
 //       corresponding to the watches which would have signalled if the watcher
 //       had been armed successfully. The actual number of entries placed in the
 //       output buffers is written to |*num_ready_contexts| before returning.
 //
 //       If more than (input) |*num_ready_contexts| watch contexts were ready to
-//       notify, the subset presented in output buffers is arbitrary and
-//       implementation-defined.
+//       notify, the subset presented in output buffers is arbitrary, but the
+//       implementation makes a best effort to circulate the outputs across
+//       consecutive calls so that callers may reliably avoid handle starvation.
 MOJO_SYSTEM_EXPORT MojoResult
 MojoArmWatcher(MojoHandle watcher_handle,
                uint32_t* num_ready_contexts,
                uintptr_t* ready_contexts,
                MojoResult* ready_results,
                struct MojoHandleSignalsState* ready_signals_states);
 
 #ifdef __cplusplus
 }  // extern "C"
 #endif
 
 #endif  // MOJO_PUBLIC_C_SYSTEM_WATCHER_H_