Mojo: Move waiting APIs to public library

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 <stdint.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.
-//
-// If a handle is closed while still in the wait set, it is implicitly removed
-// from the set after being returned from |MojoGetReadyHandles()| with the
-// result |MOJO_RESULT_CANCELLED|.
-//
-// 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
-// |MojoGetReadyHandles()| 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| for more details about the meaning of each array
-// entry. The array will always be updated for every returned handle.
-//
-// 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 |MojoGetReadyHandles()| 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_