API definition for WaitSet.

mojo/public/c/system/wait_set.h

+// Copyright 2015 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.
+
+// This file contains types/constants and functions specific to wait sets.
+//
+// Note: This header should be compilable as C.
+
+#ifndef MOJO_PUBLIC_C_SYSTEM_WAIT_SET_H_
+#define MOJO_PUBLIC_C_SYSTEM_WAIT_SET_H_
+
+#include "mojo/public/c/system/system_export.h"
+#include "mojo/public/c/system/types.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// Note: See the comment in functions.h about the meaning of the "optional"
+// label for pointer parameters.
+
+// Creates a wait set. A wait set is a way to efficiently wait on multiple
+// handles.
+//
+// On success, |*wait_set_handle| will contain a handle to a wait set.
+//
+// Returns:
+//   |MOJO_RESULT_OK| on success.
+//   |MOJO_RESULT_INVALID_ARGUMENT| if |wait_set_handle| is null.
+//   |MOJO_RESULT_RESOURCE_EXHAUSTED| if a process/system/quota/etc. limit has
+//       been reached.
+MOJO_SYSTEM_EXPORT MojoResult MojoCreateWaitSet(
+    MojoHandle* wait_set_handle);  // Out.
+
+// Adds a wait on |handle| to |wait_set_handle|.
+//
+// A handle can only be added to any given wait set once, but may be added to
+// any number of different wait sets. To modify the signals being waited for,
+// the handle must first be removed, and then added with the new signals.
+//
+// Returns:
+//   |MOJO_RESULT_OK| if |handle| was successfully added to |wait_set_handle|.
+//   |MOJO_RESULT_INVALID_ARGUMENT| if |handle| is not a valid handle, or
+//       |wait_set_handle| is not a valid wait set.
+//   |MOJO_RESULT_ALREADY_EXISTS| if |handle| already exists in
+//       |wait_set_handle|.
+//
+// It is safe to add a handle to a wait set while performing a wait on another

[Sam McNally, 2015/11/23 06:51:57]

Is it specified what happens when this is done?

It seems a bit weird to have this after Returns.

[Anand Mistry (off Chromium), 2015/12/03 00:47:13]

I thought that would be obvious. If the other thread is waiting and the handle
is ready, it would wake up that other thread. Otherwise, it would just get added
to the set and when woken, would terminate the wait.
It seemed to be the convention to put clarifying notes after the returns. But
other than TODOs, only the MojoWait() definition does this, so I've moved it to
before.

+// thread.
+MOJO_SYSTEM_EXPORT MojoResult MojoAddWaiter(

[darin (slow to review), 2015/11/23 22:19:01]

naming nit (bikeshedding): I'm not sure the term "Waiter" makes that much sense
here. A handle is not a waiter. MojoAddHandleToWaitSet would be clearer, but
since we have MojoGetReadyHandle maybe we should just go with MojoAddHandle. We
don't have an object-oriented naming convention for Mojo API since we don't
expect a large API.

[Anand Mistry (off Chromium), 2015/12/03 00:47:13]

Done.

+    MojoHandle wait_set_handle,
+    MojoHandle handle,
+    MojoHandleSignals signals);
+
+// Removes |handle| from |wait_set_handle|.
+//
+// Returns:
+//   |MOJO_RESULT_OK| if |handle| was successfully removed from
+//       |wait_set_handle|.
+//   |MOJO_RESULT_INVALID_ARGUMENT| if |handle| is not a valid handle, or
+//       |wait_set_handle| is not a valid wait set.
+//   |MOJO_RESULT_NOT_FOUND| if |handle| does not exist in |wait_set_handle|.
+//
+// It is safe to remove a handle from a wait set while performing a wait on

[Sam McNally, 2015/11/23 06:51:56]

Ditto.

[Anand Mistry (off Chromium), 2015/12/03 00:47:13]

Done.

+// another thread.
+MOJO_SYSTEM_EXPORT MojoResult MojoRemoveWaiter(
+    MojoHandle wait_set_handle,
+    MojoHandle handle);
+
+// Retreives a ready from |wait_set_handle|. A handle is ready if:

[Sam McNally, 2015/11/23 06:51:56]

Retrieves a ready handle from |wait_set_handle|.

Please make it clear that any of the three items below being true causes a
handle to be ready. It isn't immediately obvious.

[Anand Mistry (off Chromium), 2015/12/03 00:47:13]

Done.

+//   - Its signals are satisfied.
+//   - It becomes known that no signal for the handle will ever be satisfied.

[Sam McNally, 2015/11/23 06:51:57]

"It" refers to something different here compared to the other two items.

[Anand Mistry (off Chromium), 2015/12/03 00:47:13]

Done... I think...

+//   - It is closed.
+//
+// A wait set may have ready handles when it satisfies the
+// |MOJO_HANDLE_SIGNAL_READABLE| signal. Since handles may be added and removed
+// from a wait set concurrently, it is possible for a wait set to satisfy
+// |MOJO_HANDLE_SIGNAL_READABLE|, but not have any ready handles when
+// |MojoGetReadyHandle()| is called. These spurious wake-ups must be gracefully
+// handled.
+//
+// |*handle| will contain a handle whose signal has been satisfied, or can not
+// ever be satisfied. Care should be taken that if a handle is closed on another
+// thread, |*handle| would be invalid, but the return value may not be
+// |MOJO_RESULT_CANCELLED|.
+//
+// |signals_state| (optional): See documentation for |MojoHandleSignalsState|.
+//
+// Returns:
+//   |MOJO_RESULT_OK| if |*handle| has its signals satisfied.
+//   |MOJO_RESULT_CANCELLED| if |*handle| was closed (necessarily from another
+//       thread) during the wait.
+//   |MOJO_RESULT_INVALID_ARGUMENT| if |wait_set_handle| is not a valid wait
+//       set.
+//   |MOJO_RESULT_FAILED_PRECONDITION| if it is or becomes impossible that
+//       |*handle| will ever satisfy any of its signals.
+//   |MOJO_RESULT_SHOULD_WAIT| if there are no ready handles.
+//
+// Mojo signals and satisfiability are logically 'level-triggered'. Therefore,
+// if a signal continues to be satisfied and is not removed from the wait set,
+// subsequent calls to |MojoGetReadyHandle()| will return the same handle.
+//
+// If multiple handles have their signals satisfied, the order in which handles
+// are returned is undefined. The same handle, if not removed, may be returned
+// in consecutive calls. Callers should not rely on any fairness and handles
+// could be starved if not acted on.
+MOJO_SYSTEM_EXPORT MojoResult MojoGetReadyHandle(
+    MojoHandle wait_set_handle,
+    MojoHandle* handle,                             // Out.
+    struct MojoHandleSignalsState *signals_state);  // Optional out.
+
+#ifdef __cplusplus
+}  // extern "C"
+#endif
+
+#endif  // MOJO_PUBLIC_C_SYSTEM_WAIT_SET_H_