1 // Copyright 2015 The Chromium Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 // This file contains types/constants and functions specific to wait sets. 6 // 7 // Note: This header should be compilable as C. 8 9 #ifndef MOJO_PUBLIC_C_SYSTEM_WAIT_SET_H_ 10 #define MOJO_PUBLIC_C_SYSTEM_WAIT_SET_H_ 11 12 #include <stdint.h> 13 14 #include "mojo/public/c/system/system_export.h" 15 #include "mojo/public/c/system/types.h" 16 17 #ifdef __cplusplus 18 extern "C" { 19 #endif 20 21 // Note: See the comment in functions.h about the meaning of the "optional" 22 // label for pointer parameters. 23 24 // Creates a wait set. A wait set is a way to efficiently wait on multiple 25 // handles. 26 // 27 // On success, |*wait_set_handle| will contain a handle to a wait set. 28 // 29 // Returns: 30 // |MOJO_RESULT_OK| on success. 31 // |MOJO_RESULT_INVALID_ARGUMENT| if |wait_set_handle| is null. 32 // |MOJO_RESULT_RESOURCE_EXHAUSTED| if a process/system/quota/etc. limit has 33 // been reached. 34 MOJO_SYSTEM_EXPORT MojoResult MojoCreateWaitSet( 35 MojoHandle* wait_set_handle); // Out. 36 37 // Adds a wait on |handle| to |wait_set_handle|. 38 // 39 // A handle can only be added to any given wait set once, but may be added to 40 // any number of different wait sets. To modify the signals being waited for, 41 // the handle must first be removed, and then added with the new signals. 42 // 43 // If a handle is closed while still in the wait set, it is implicitly removed 44 // from the set after being returned from |MojoGetReadyHandles()| with the 45 // result |MOJO_RESULT_CANCELLED|. 46 // 47 // It is safe to add a handle to a wait set while performing a wait on another 48 // thread. If the added handle already has its signals satisfied, the waiting 49 // thread will be woken. 50 // 51 // Returns: 52 // |MOJO_RESULT_OK| if |handle| was successfully added to |wait_set_handle|. 53 // |MOJO_RESULT_INVALID_ARGUMENT| if |handle| is not a valid handle, or 54 // |wait_set_handle| is not a valid wait set. 55 // |MOJO_RESULT_ALREADY_EXISTS| if |handle| already exists in 56 // |wait_set_handle|. 57 MOJO_SYSTEM_EXPORT MojoResult MojoAddHandle( 58 MojoHandle wait_set_handle, 59 MojoHandle handle, 60 MojoHandleSignals signals); 61 62 // Removes |handle| from |wait_set_handle|. 63 // 64 // It is safe to remove a handle from a wait set while performing a wait on 65 // another thread. If handle has its signals satisfied while it is being 66 // removed, the waiting thread may be woken up, but no handle may be available 67 // when |MojoGetReadyHandles()| is called. 68 // 69 // Returns: 70 // |MOJO_RESULT_OK| if |handle| was successfully removed from 71 // |wait_set_handle|. 72 // |MOJO_RESULT_INVALID_ARGUMENT| if |handle| is not a valid handle, or 73 // |wait_set_handle| is not a valid wait set. 74 // |MOJO_RESULT_NOT_FOUND| if |handle| does not exist in |wait_set_handle|. 75 MOJO_SYSTEM_EXPORT MojoResult MojoRemoveHandle( 76 MojoHandle wait_set_handle, 77 MojoHandle handle); 78 79 // Retrieves a set of ready handles from |wait_set_handle|. A handle is ready if 80 // at least of of the following is true: 81 // - The handle's signals are satisfied. 82 // - It becomes known that no signal for the handle will ever be satisfied. 83 // - The handle is closed. 84 // 85 // A wait set may have ready handles when it satisfies the 86 // |MOJO_HANDLE_SIGNAL_READABLE| signal. Since handles may be added and removed 87 // from a wait set concurrently, it is possible for a wait set to satisfy 88 // |MOJO_HANDLE_SIGNAL_READABLE|, but not have any ready handles when 89 // |MojoGetReadyHandles()| is called. These spurious wake-ups must be gracefully 90 // handled. 91 // 92 // |*count| on input, must contain the maximum number of ready handles to be 93 // returned. On output, it will contain the number of ready handles returned. 94 // 95 // |handles| must point to an array of size |*count| of |MojoHandle|. It will be 96 // populated with handles that are considered ready. The number of handles 97 // returned will be in |*count|. 98 // 99 // |results| must point to an array of size |*count| of |MojoResult|. It will be 100 // populated with the wait result of the corresponding handle in |*handles|. 101 // Care should be taken that if a handle is closed on another thread, the handle 102 // would be invalid, but the result may not be |MOJO_RESULT_CANCELLED|. See 103 // documentation for |MojoWait()| for possible results. 104 // 105 // |signals_state| (optional) if non-null, must point to an array of size 106 // |*count| of |MojoHandleSignalsState|. It will be populated with the signals 107 // state of the corresponding handle in |*handles|. See documentation for 108 // |MojoHandleSignalsState| for more details about the meaning of each array 109 // entry. The array will always be updated for every returned handle. 110 // 111 // Mojo signals and satisfiability are logically 'level-triggered'. Therefore, 112 // if a signal continues to be satisfied and is not removed from the wait set, 113 // subsequent calls to |MojoGetReadyHandles()| will return the same handle. 114 // 115 // If multiple handles have their signals satisfied, the order in which handles 116 // are returned is undefined. The same handle, if not removed, may be returned 117 // in consecutive calls. Callers must not rely on any fairness and handles 118 // could be starved if not acted on. 119 // 120 // Returns: 121 // |MOJO_RESULT_OK| if ready handles are available. 122 // |MOJO_RESULT_INVALID_ARGUMENT| if |wait_set_handle| is not a valid wait 123 // set, if |*count| is 0, or if either |count|, |handles|, or |results| is 124 // null. 125 // |MOJO_RESULT_SHOULD_WAIT| if there are no ready handles. 126 MOJO_SYSTEM_EXPORT MojoResult MojoGetReadyHandles( 127 MojoHandle wait_set_handle, 128 uint32_t* count, // In/out. 129 MojoHandle* handles, // Out. 130 MojoResult* results, // Out. 131 struct MojoHandleSignalsState *signals_states); // Optional out. 132 133 #ifdef __cplusplus 134 } // extern "C" 135 #endif 136 137 #endif // MOJO_PUBLIC_C_SYSTEM_WAIT_SET_H_ 138
