API definition for WaitSet.

third_party/mojo/src/mojo/public/c/system/wait_set.h

Index: third_party/mojo/src/mojo/public/c/system/wait_set.h
diff --git a/third_party/mojo/src/mojo/public/c/system/wait_set.h b/third_party/mojo/src/mojo/public/c/system/wait_set.h
new file mode 100644
index 0000000000000000000000000000000000000000..818c9084eb8fff43616e58e927c2c6e84152d8e5
--- /dev/null
+++ b/third_party/mojo/src/mojo/public/c/system/wait_set.h
@@ -0,0 +1,112 @@
+// 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 "third_party/mojo/src/mojo/public/c/system/system_export.h"
+#include "third_party/mojo/src/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.
+
+// Add 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
+// thread.
+MOJO_SYSTEM_EXPORT MojoResult MojoAddWaiter(
+    MojoHandle wait_set_handle,
+    MojoHandle handle,
+    MojoHandleSignals signals);
+
+// Remove |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
+// another thread.
+MOJO_SYSTEM_EXPORT MojoResult MojoRemoveWaiter(
+    MojoHandle wait_set_handle,
+    MojoHandle handle);
+
+// Retreive a ready from |wait_set_handle|. A handle is ready if:
+//   - Its signals are satisfied.
+//   - It becomes known that no signal for the handle will ever be satisfied.
+//   - 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.
+//
+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_