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.
+//
+// It is safe to add a handle to a wait set while performing a wait on another
+// thread. If the added handle already has its signals satisfied, the waiting
+// thread will be woken.
+//
+// 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|.
+MOJO_SYSTEM_EXPORT MojoResult MojoAddHandle(
+    MojoHandle wait_set_handle,
+    MojoHandle handle,
+    MojoHandleSignals signals);
+
+// Removes |handle| from |wait_set_handle|.
+//
+// It is safe to remove a handle from a wait set while performing a wait on
+// another thread. If handle has its signals satisfied while it is being
+// removed, the waiting thread may be woken up, but no handle may be available
+// when |MojoGetReadyHandles()| is called.
+//
+// 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|.
+MOJO_SYSTEM_EXPORT MojoResult MojoRemoveHandle(
+    MojoHandle wait_set_handle,
+    MojoHandle handle);
+
+// Retrieves a set of ready handles from |wait_set_handle|. A handle is ready if
+// at least of of the following is true:
+//   - The handle's signals are satisfied.
+//   - It becomes known that no signal for the handle will ever be satisfied.
+//   - The handle 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.
+//
+// |*count| on input, must contain the maximum number of ready handles to be
+// returned. On output, it will contain the number of ready handles returned.
+//
+// |handles| must point to an array of size |*count| of |MojoHandle|. It will be
+// populated with handles that are considered ready. The number of handles
+// returned will be in |*count|.
+//
+// |results| must point to an array of size |*count| of |MojoResult|. It will be
+// populated with the wait result of the corresponding handle in |*handles|.
+// Care should be taken that if a handle is closed on another thread, the handle
+// would be invalid, but the result may not be |MOJO_RESULT_CANCELLED|. See
+// documentation for |MojoWait()| for possible results.
+//
+// |signals_state| (optional) if non-null, must point to an array of size
+// |*count| of |MojoHandleSignalsState|. It will be populated with the signals
+// state of the corresponding handle in |*handles|. See documentation for
+// |MojoHandleSignalsState|.
+//
+// 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 must not rely on any fairness and handles
+// could be starved if not acted on.
+//
+// Returns:
+//   |MOJO_RESULT_OK| if ready handles are available.
+//   |MOJO_RESULT_INVALID_ARGUMENT| if |wait_set_handle| is not a valid wait
+//       set, if |*count| is 0, or if either |count|, |handles|, or |results| is
+//       null.
+//   |MOJO_RESULT_SHOULD_WAIT| if there are no ready handles.
+MOJO_SYSTEM_EXPORT MojoResult MojoGetReadyHandles(
+    MojoHandle wait_set_handle,
+    uint32_t* count,                                 // In/out.
+    MojoHandle* handles,                             // Out.
+    MojoResult* results,                             // Out.
+    struct MojoHandleSignalsState *signals_states);  // Optional out.
+
+#ifdef __cplusplus
+}  // extern "C"
+#endif
+
+#endif  // MOJO_PUBLIC_C_SYSTEM_WAIT_SET_H_