| OLD | NEW |
|---|
| (Empty) |
| 1 // Copyright 2016 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 functions for waiting on multiple handles using wait sets. | |
| 6 // | |
| 7 // Note: This header should be compilable as C. | |
| 8 | |
| 9 #ifndef MOJO_PUBLIC_C_INCLUDE_MOJO_SYSTEM_WAIT_SET_H_ | |
| 10 #define MOJO_PUBLIC_C_INCLUDE_MOJO_SYSTEM_WAIT_SET_H_ | |
| 11 | |
| 12 #include <mojo/macros.h> | |
| 13 #include <mojo/result.h> | |
| 14 #include <mojo/system/handle.h> | |
| 15 #include <mojo/system/time.h> | |
| 16 #include <stdint.h> | |
| 17 | |
| 18 // |MojoCreateWaitSetOptions|: Used to specify creation parameters for a wait | |
| 19 // set to |MojoCreateWaitSet()|. | |
| 20 // |uint32_t struct_size|: Set to the size of the |MojoCreateWaitSetOptions| | |
| 21 // struct. (Used to allow for future extensions.) | |
| 22 // |MojoCreateWaitSetOptionsFlags flags|: Reserved for future use | |
| 23 // |MOJO_CREATE_WAIT_SET_OPTIONS_FLAGS_NONE|: No flags, default mode. | |
| 24 | |
| 25 typedef uint32_t MojoCreateWaitSetOptionsFlags; | |
| 26 | |
| 27 #define MOJO_CREATE_WAIT_SET_OPTIONS_FLAG_NONE \ | |
| 28 ((MojoCreateWaitSetOptionsFlags)0) | |
| 29 | |
| 30 struct MOJO_ALIGNAS(8) MojoCreateWaitSetOptions { | |
| 31 uint32_t struct_size; | |
| 32 MojoCreateWaitSetOptionsFlags flags; | |
| 33 }; | |
| 34 MOJO_STATIC_ASSERT(sizeof(struct MojoCreateWaitSetOptions) == 8, | |
| 35 "MojoCreateWaitSetOptions has wrong size"); | |
| 36 | |
| 37 // |MojoWaitSetAddOptions|: Used to specify parameters in adding an entry to a | |
| 38 // wait set with |MojoWaitSetAdd()|. | |
| 39 // |uint32_t struct_size|: Set to the size of the |MojoWaitSetAddOptions| | |
| 40 // struct. (Used to allow for future extensions.) | |
| 41 // |MojoWaitSetAddOptionsFlags flags|: Reserved for future use. | |
| 42 // |MOJO_WAIT_SET_ADD_OPTIONS_FLAGS_NONE|: No flags, default mode. | |
| 43 | |
| 44 typedef uint32_t MojoWaitSetAddOptionsFlags; | |
| 45 | |
| 46 #define MOJO_WAIT_SET_ADD_OPTIONS_FLAG_NONE ((MojoWaitSetAddOptionsFlags)0) | |
| 47 | |
| 48 struct MOJO_ALIGNAS(8) MojoWaitSetAddOptions { | |
| 49 uint32_t struct_size; | |
| 50 MojoWaitSetAddOptionsFlags flags; | |
| 51 }; | |
| 52 MOJO_STATIC_ASSERT(sizeof(struct MojoWaitSetAddOptions) == 8, | |
| 53 "MojoWaitSetAddOptions has wrong size"); | |
| 54 | |
| 55 // |MojoWaitSetResult|: Returned by |MojoWaitSetWait()| to indicate the state of | |
| 56 // entries. See |MojoWaitSetWait()| for the values of these fields. | |
| 57 | |
| 58 struct MOJO_ALIGNAS(8) MojoWaitSetResult { | |
| 59 uint64_t cookie; | |
| 60 MojoResult wait_result; | |
| 61 uint32_t reserved; | |
| 62 struct MojoHandleSignalsState signals_state; | |
| 63 }; | |
| 64 MOJO_STATIC_ASSERT(sizeof(struct MojoWaitSetResult) == 24, | |
| 65 "MojoWaitSetResult has wrong size"); | |
| 66 | |
| 67 MOJO_BEGIN_EXTERN_C | |
| 68 | |
| 69 // |MojoCreateWaitSet()|: Creates a new wait set. | |
| 70 // | |
| 71 // A wait set is an object that can be used to wait for a set of handles to | |
| 72 // satisfy some set of signals simultaneously. | |
| 73 // | |
| 74 // If |options| is null, the default options will be used. | |
| 75 // | |
| 76 // Returns: | |
| 77 // |MOJO_RESULT_OK| if a wait set was successfully created. On success, | |
| 78 // |*handle| will be the handle of the wait set. | |
| 79 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., | |
| 80 // |options| is non null and |*options| is invalid). | |
| 81 // |MOJO_RESULT_RESOURCE_EXHAUSTED| if a process/system/quota/etc. limit has | |
| 82 // been reached. | |
| 83 // |MOJO_RESULT_UNIMPLEMENTED| if an unsupported flag was set in |*options|. | |
| 84 MojoResult MojoCreateWaitSet(const struct MojoCreateWaitSetOptions* | |
| 85 MOJO_RESTRICT options, // Optional in. | |
| 86 MojoHandle* handle); // Out. | |
| 87 | |
| 88 // |MojoWaitSetAdd()|: Adds an entry to watch for to the wait set specified by | |
| 89 // |wait_set_handle| (which must have the |MOJO_HANDLE_RIGHT_WRITE| right). | |
| 90 // | |
| 91 // An entry in a wait set is composed of a handle, a signal set, and a | |
| 92 // caller-specified cookie value. The cookie value must be unique across all | |
| 93 // entries in a particular wait set but is otherwise opaque and can be any value | |
| 94 // that is useful to the caller. If |options| is null the default options will | |
| 95 // be used. | |
| 96 // | |
| 97 // In all failure cases the wait set is unchanged. | |
| 98 // | |
| 99 // Returns: | |
| 100 // |MOJO_RESULT_OK| if the handle was added to the wait set. | |
| 101 // |MOJO_RESULT_INVALID_ARGUMENT| if |wait_set_handle| or |handle| do not | |
| 102 // refer to valid handles, |wait_set_handle| is not a handle to a wait | |
| 103 // set, or |options| is not null and |*options| is not a valid options | |
| 104 // structure. | |
| 105 // |MOJO_RESULT_ALREADY_EXISTS| if there is already an entry in the wait set | |
| 106 // with the same |cookie| value. | |
| 107 // |MOJO_RESULT_BUSY| if |wait_set_handle| or |handle| are currently in use in | |
| 108 // some transaction. | |
| 109 // |MOJO_RESULT_RESOURCE_EXHAUSTED| if the handle could not be added due to | |
| 110 // hitting a system or quota limitation. | |
| 111 // |MOJO_ERROR_CODE_UNIMPLEMENTED| if some unknown/unsupported option has been | |
| 112 // specified in |*options|. | |
| 113 MojoResult MojoWaitSetAdd(MojoHandle wait_set_handle, // In. | |
| 114 MojoHandle handle, // In. | |
| 115 MojoHandleSignals signals, // In. | |
| 116 uint64_t cookie, // In. | |
| 117 const struct MojoWaitSetAddOptions* MOJO_RESTRICT | |
| 118 options); // Optional in. | |
| 119 | |
| 120 // |MojoWaitSetRemove()|: Removes an entry from the wait set specified by | |
| 121 // |wait_set_handle| (which must have the |MOJO_HANDLE_RIGHT_WRITE| right). | |
| 122 // | |
| 123 // Returns: | |
| 124 // |MOJO_RESULT_OK| if the entry was successfully removed. | |
| 125 // |MOJO_RESULT_INVALID_ARGUMENT| if |wait_set_handle| does not refer to a | |
| 126 // valid wait set. | |
| 127 // |MOJO_RESULT_NOT_FOUND| if |cookie| does not identify an entry within the | |
| 128 // wait set. | |
| 129 MojoResult MojoWaitSetRemove(MojoHandle wait_set_handle, // In. | |
| 130 uint64_t cookie); // In. | |
| 131 | |
| 132 // |MojoWaitSetWait()|: Waits on all entries in the wait set specified by | |
| 133 // |wait_set_handle| (which must have the |MOJO_HANDLE_RIGHT_READ| right) for at | |
| 134 // least one of the following: | |
| 135 // - At least one entry's handle satisfies a signal in that entry's signal | |
| 136 // set. | |
| 137 // - At least one entry's handle can never satisfy a signal in that entry's | |
| 138 // signal set. | |
| 139 // - |deadline| expires. | |
| 140 // - The wait set is closed. | |
| 141 // | |
| 142 // On success, sets |*max_results| to the total number of possible results at | |
| 143 // the time of the call. Also returns information for up to |*num_results| | |
| 144 // entries in |*results| and sets |*num_results| to the number of entries the | |
| 145 // system populated. In particular, |results[0]|, ..., |results[*num_results-1]| | |
| 146 // will be populated as follows: | |
| 147 // - |cookie| is the cookie value specified when the entry was added | |
| 148 // - |wait_result| is set to one of the following: | |
| 149 // - |MOJO_RESULT_OK| if the handle referred to by the entry satisfies one | |
| 150 // or more of the signals in the entry | |
| 151 // - |MOJO_RESULT_CANCELLED| if the handle referred to by the entry was | |
| 152 // closed | |
| 153 // - |MOJO_RESULT_BUSY| if the handle referred to by the entry is currently | |
| 154 // in use in some transaction | |
| 155 // - |MOJO_RESULT_FAILED_PRECONDITION| if it becomes impossible that the | |
| 156 // handle referred to by the entry will ever satisfy any of entry's | |
| 157 // signals | |
| 158 // - |reserved| is set to 0 | |
| 159 // | |
| 160 // When |wait_result| is |MOJO_RESULT_OK| or |MOJO_RESULT_FAILED_PRECONDITION| | |
| 161 // |signals_state| is set to the handle's current signal state; otherwise, it | |
| 162 // is set to a zeroed |MojoHandleSignalsState| (in particular, both fields | |
| 163 // will then be |MOJO_HANDLE_SIGNALS_NONE|). | |
| 164 // | |
| 165 // On any result other than |MOJO_RESULT_OK|, |*num_results|, |*results| and | |
| 166 // |*max_results| are not modified. | |
| 167 // | |
| 168 // Returns: | |
| 169 // |MOJO_RESULT_OK| if one or more entries in the wait set become satisfied or | |
| 170 // unsatisfiable. | |
| 171 // |MOJO_RESULT_INVALID_ARGUMENT| if |wait_set_handle| does not refer to a | |
| 172 // valid wait set handle. | |
| 173 // |MOJO_RESULT_CANCELLED| if |wait_set_handle| is closed during the wait. | |
| 174 // |MOJO_RESULT_RESOURCE_EXHAUSTED| if a system/quota/etc. limit was reached. | |
| 175 // |MOJO_RESULT_BUSY| if |wait_set_handle| is in use in some transaction. Note | |
| 176 // that waiting on a wait set handle does not count as a transaction. It | |
| 177 // is valid to call |MojoWaitSetWait()| on the same wait set handle | |
| 178 // concurrently from different threads. | |
| 179 // |MOJO_RESULT_DEADLINE_EXCEEDED| if the deadline is passed without any | |
| 180 // entries in the wait set becoming satisfied or unsatisfiable. | |
| 181 MojoResult MojoWaitSetWait( | |
| 182 MojoHandle wait_set_handle, // In. | |
| 183 MojoDeadline deadline, // In. | |
| 184 uint32_t* MOJO_RESTRICT num_results, // In/out. | |
| 185 struct MojoWaitSetResult* MOJO_RESTRICT results, // Out. | |
| 186 uint32_t* MOJO_RESTRICT max_results); // Optional out. | |
| 187 | |
| 188 MOJO_END_EXTERN_C | |
| 189 | |
| 190 #endif // MOJO_PUBLIC_C_INCLUDE_MOJO_SYSTEM_WAIT_SET_H_ | |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 2250183003:
Make the fuchsia mojo/public repo the source of truth. (Closed)
Base URL: https://github.com/domokit/mojo.git@master