OLD | NEW |
---|---|
1 // Copyright 2014 The Chromium Authors. All rights reserved. | 1 // Copyright 2014 The Chromium Authors. All rights reserved. |
2 // Use of this source code is governed by a BSD-style license that can be | 2 // Use of this source code is governed by a BSD-style license that can be |
3 // found in the LICENSE file. | 3 // found in the LICENSE file. |
4 | 4 |
5 // This file contains basic functions common to different Mojo system APIs. | 5 // This file contains basic functions common to different Mojo system APIs. |
6 // | 6 // |
7 // Note: This header should be compilable as C. | 7 // Note: This header should be compilable as C. |
8 | 8 |
9 #ifndef MOJO_PUBLIC_C_SYSTEM_FUNCTIONS_H_ | 9 #ifndef MOJO_PUBLIC_C_SYSTEM_FUNCTIONS_H_ |
10 #define MOJO_PUBLIC_C_SYSTEM_FUNCTIONS_H_ | 10 #define MOJO_PUBLIC_C_SYSTEM_FUNCTIONS_H_ |
11 | 11 |
12 #include <stddef.h> | 12 #include <stddef.h> |
13 #include <stdint.h> | 13 #include <stdint.h> |
14 | 14 |
15 #include "mojo/public/c/system/system_export.h" | 15 #include "mojo/public/c/system/system_export.h" |
16 #include "mojo/public/c/system/types.h" | 16 #include "mojo/public/c/system/types.h" |
17 | 17 |
18 #ifdef __cplusplus | 18 #ifdef __cplusplus |
19 extern "C" { | 19 extern "C" { |
20 #endif | 20 #endif |
21 | 21 |
22 // A callback used to notify watchers registered via |MojoWatch()|. Called when | 22 // A callback used to notify watchers registered via |MojoRegisterWatcher()|. |
23 // some watched signals are satisfied or become unsatisfiable. See the | 23 // Called when some watched signals are satisfied or become unsatisfiable. See |
24 // documentation for |MojoWatch()| for more details. | 24 // the documentation for |MojoRegisterWatcher()| for more details. |
25 typedef void (*MojoWatchCallback)(uintptr_t context, | 25 typedef void (*MojoWatchCallback)(uintptr_t context, |
26 MojoResult result, | 26 MojoResult result, |
27 struct MojoHandleSignalsState signals_state, | 27 struct MojoHandleSignalsState signals_state, |
28 MojoWatchNotificationFlags flags); | 28 MojoWatchNotificationFlags flags); |
29 | 29 |
30 // Note: Pointer parameters that are labelled "optional" may be null (at least | 30 // Note: Pointer parameters that are labelled "optional" may be null (at least |
31 // under some circumstances). Non-const pointer parameters are also labeled | 31 // under some circumstances). Non-const pointer parameters are also labeled |
32 // "in", "out", or "in/out", to indicate how they are used. (Note that how/if | 32 // "in", "out", or "in/out", to indicate how they are used. (Note that how/if |
33 // such a parameter is used may depend on other parameters or the requested | 33 // such a parameter is used may depend on other parameters or the requested |
34 // operation's success/failure. E.g., a separate |flags| parameter may control | 34 // operation's success/failure. E.g., a separate |flags| parameter may control |
(...skipping 96 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... | |
131 // |MOJO_RESULT_FAILED_PRECONDITION| if it is or becomes impossible that SOME | 131 // |MOJO_RESULT_FAILED_PRECONDITION| if it is or becomes impossible that SOME |
132 // |handle[i]| will ever satisfy any of the signals in |signals[i]|. | 132 // |handle[i]| will ever satisfy any of the signals in |signals[i]|. |
133 MOJO_SYSTEM_EXPORT MojoResult | 133 MOJO_SYSTEM_EXPORT MojoResult |
134 MojoWaitMany(const MojoHandle* handles, | 134 MojoWaitMany(const MojoHandle* handles, |
135 const MojoHandleSignals* signals, | 135 const MojoHandleSignals* signals, |
136 uint32_t num_handles, | 136 uint32_t num_handles, |
137 MojoDeadline deadline, | 137 MojoDeadline deadline, |
138 uint32_t* result_index, // Optional out | 138 uint32_t* result_index, // Optional out |
139 struct MojoHandleSignalsState* signals_states); // Optional out | 139 struct MojoHandleSignalsState* signals_states); // Optional out |
140 | 140 |
141 // Watches the given handle for one of the following events to happen: | 141 // Registers a watcher on the given handle. A watcher may be used to trigger |
142 // - A signal indicated by |signals| is satisfied. | 142 // arbitrary code execution when a handle's state changes to meet any of the |
143 // - It becomes known that no signal indicated by |signals| will ever be | 143 // following conditions: |
144 // satisfied. (See the description of the |MOJO_RESULT_CANCELLED| and | |
145 // |MOJO_RESULT_FAILED_PRECONDITION| return values below.) | |
146 // - The handle is closed. | |
147 // | 144 // |
148 // |handle|: The handle to watch. Must be an open message pipe or data pipe | 145 // - A signal in |signals| is satisfied on |handle|. |
146 // - No signal in |signals| can ever be satisfied on |handle| again. | |
147 // - |handle| is closed. | |
148 // | |
149 // A newly registered watcher is initially disarmed. Use |MojoArmWatcher()| to | |
150 // arm a registered watcher and |MojoUnregisterWatcher()| to unregister it. | |
151 // | |
152 // Watchers must be armed to trigger a notification for any event other than | |
153 // handle closure. | |
154 // | |
155 // Handle closure triggers a final notification on all of a handle's registered | |
156 // watchers to indicate that they have been implicitly unregistered. This | |
157 // notification is fired regardless of whether each watcher is armed at the | |
158 // time. | |
159 // | |
160 // A watcher is always disarmed immediately before any |callback| invocation. | |
161 // | |
162 // |handle|: The handle to watcher. Must be an open message pipe or data pipe | |
yzshen1
2017/03/03 00:03:50
watchter -> watch?
Ken Rockot(use gerrit already)
2017/03/03 00:37:05
done
| |
149 // handle. | 163 // handle. |
150 // |signals|: The signals to watch for. | 164 // |signals|: The signals to watch for. |
151 // |callback|: A function to be called any time one of the above events happens. | 165 // |callback|: A function to be called any time one of the above events happens. |
152 // The function must be safe to call from any thread at any time. | 166 // The function must be safe to call from any thread at any time. The |
167 // watcher is always disarmed immediately before any invocation of this | |
168 // callback. | |
153 // |context|: User-provided context passed to |callback| when called. |context| | 169 // |context|: User-provided context passed to |callback| when called. |context| |
154 // is used to uniquely identify a registered watch and can be used to cancel | 170 // is used to uniquely identify a registered watcher and can be used to arm |
155 // the watch later using |MojoCancelWatch()|. | 171 // or remove the watcher later using |MojoArmWatcher()| and |
172 // |MojoUnregisterWatcher()|. | |
156 // | 173 // |
157 // Returns: | 174 // Returns: |
158 // |MOJO_RESULT_OK| if the watch has been successfully registered. Note that | 175 // |MOJO_RESULT_OK| if the watcher has been successfully registered. |
159 // if the signals are already satisfied this may synchronously invoke | |
160 // |callback| before returning. | |
161 // |MOJO_RESULT_CANCELLED| if the watch was cancelled. In this case it is not | |
162 // necessary to explicitly call |MojoCancelWatch()|, and in fact it may be | |
163 // an error to do so as the handle may have been closed. | |
164 // |MOJO_RESULT_INVALID_ARGUMENT| if |handle| is not an open message pipe | 176 // |MOJO_RESULT_INVALID_ARGUMENT| if |handle| is not an open message pipe |
165 // handle. | 177 // handle. |
166 // |MOJO_RESULT_FAILED_PRECONDITION| if it is already known that |signals| can | 178 // |MOJO_RESULT_FAILED_PRECONDITION| if it is already known that |signals| can |
167 // never be satisfied. | 179 // never be satisfied on |handle|. The watcher is not registered. |
168 // |MOJO_RESULT_ALREADY_EXISTS| if there is already a watch registered for | 180 // |MOJO_RESULT_ALREADY_EXISTS| if there is already a watcher registered for |
169 // the same combination of |handle| and |context|. | 181 // the same combination of |handle| and |context|. |
170 // | 182 // |
171 // Callback result codes: | 183 // Callback result codes: |
172 // The callback may be called at any time on any thread with one of the | 184 // When the watcher is armed (see |MojoArmWatcher()| below), |callback| may be |
173 // following result codes to indicate various events: | 185 // called at any time on any thread with one of the following result codes: |
174 // | 186 // |
175 // |MOJO_RESULT_OK| indicates that some signal in |signals| has been | 187 // |MOJO_RESULT_OK| indicates that some signal in |signals| has become |
176 // satisfied. | 188 // satisfied. |
177 // |MOJO_RESULT_FAILED_PRECONDITION| indicates that no signals in |signals| | 189 // |MOJO_RESULT_FAILED_PRECONDITION| indicates that no signals in |signals| |
178 // can ever be satisfied again. | 190 // can ever be satisfied again. |
191 // | |
192 // The watcher may also invoke |callback| with the following result code even | |
193 // while disarmed: | |
194 // | |
179 // |MOJO_RESULT_CANCELLED| indicates that the handle has been closed. In this | 195 // |MOJO_RESULT_CANCELLED| indicates that the handle has been closed. In this |
180 // case the watch is implicitly cancelled and there is no need to call | 196 // case the watcher is implicitly unregistered and there is no need to |
181 // |MojoCancelWatch()|. | 197 // call |MojoUnregisterWatcher()|. |
182 MOJO_SYSTEM_EXPORT MojoResult | 198 MOJO_SYSTEM_EXPORT MojoResult MojoRegisterWatcher(MojoHandle handle, |
183 MojoWatch(MojoHandle handle, | 199 MojoHandleSignals signals, |
184 MojoHandleSignals signals, | 200 MojoWatchCallback callback, |
185 MojoWatchCallback callback, | 201 uintptr_t context); |
186 uintptr_t context); | |
187 | 202 |
188 // Cancels a handle watch corresponding to some prior call to |MojoWatch()|. | 203 // Arms a registered watcher, enabling a single notification to fire when a |
204 // relevant condition is met. See |MojoRegisterWatcher()| documentation for | |
205 // details. | |
189 // | 206 // |
190 // NOTE: If the watch callback corresponding to |context| is currently running | 207 // |handle|: The handle on which the watcher is registered. |
191 // this will block until the callback completes execution. It is therefore | 208 // |context|: The context with which the watcher is registered. |
192 // illegal to call |MojoCancelWatch()| on a given |handle| and |context| from | |
193 // within the associated callback itself, as this will always deadlock. | |
194 // | |
195 // After |MojoCancelWatch()| function returns, the watch's associated callback | |
196 // will NEVER be called again by Mojo. | |
197 // | |
198 // |context|: The same user-provided context given to some prior call to | |
199 // |MojoWatch()|. Only the watch corresponding to this context will be | |
200 // cancelled. | |
201 // | 209 // |
202 // Returns: | 210 // Returns: |
203 // |MOJO_RESULT_OK| if the watch corresponding to |context| was cancelled. | 211 // |MOJO_RESULT_OK| if the watcher has been successfully armed. |
204 // |MOJO_RESULT_INVALID_ARGUMENT| if no watch was registered with |context| | 212 // |MOJO_RESULT_INVALID_ARGUMENT| if |handle| is not a valid message pipe |
205 // for the given |handle|, or if |handle| is invalid. | 213 // or data pipe handle or a watcher is not registered on that handle with |
206 MOJO_SYSTEM_EXPORT MojoResult | 214 // the given |context|. |
207 MojoCancelWatch(MojoHandle handle, uintptr_t context); | 215 // |MOJO_RESULT_ALREADY_EXISTS| if one of the watched signals is already |
216 // satisfied. The watcher is not armed. | |
217 // |MOJO_RESULT_FAILED_PRECONDITION| if none of the watched signals can ever | |
218 // be satisfied again. The watcher is not armed. | |
219 MOJO_SYSTEM_EXPORT MojoResult MojoArmWatcher(MojoHandle handle, | |
220 uintptr_t context); | |
221 | |
222 // Unregisters the watcher associated with |context| on |handle|. | |
223 // | |
224 // NOTE: If the watcher's callback is currently running as a result of | |
225 // invocation by the watcher, this will block until the callback returns. It is | |
226 // therefore illegal to unregister a watcher from within its own callback, as | |
227 // that would always lead to deadlock. | |
228 // | |
229 // After |MojoUnregisterWatcher()| returns, the watcher's associated callback | |
230 // will will never be called again by Mojo. | |
231 // | |
232 // |handle|: The handle on which the watcher is registered. | |
233 // |context|: The same user-provided context given to some prior call to | |
234 // |MojoRegisterWatcher()|. Only the watcher corresponding to this context | |
235 // will be unregistered. | |
236 // | |
237 // Returns: | |
238 // |MOJO_RESULT_OK| if the watcher corresponding to |context| was | |
239 // unregistered. | |
240 // |MOJO_RESULT_INVALID_ARGUMENT| if no watcher was registered with | |
241 // |context| for the given |handle|, or if |handle| is invalid. | |
242 MOJO_SYSTEM_EXPORT MojoResult MojoUnregisterWatcher(MojoHandle handle, | |
243 uintptr_t context); | |
208 | 244 |
209 // Retrieves system properties. See the documentation for |MojoPropertyType| for | 245 // Retrieves system properties. See the documentation for |MojoPropertyType| for |
210 // supported property types and their corresponding output value type. | 246 // supported property types and their corresponding output value type. |
211 // | 247 // |
212 // Returns: | 248 // Returns: |
213 // |MOJO_RESULT_OK| on success. | 249 // |MOJO_RESULT_OK| on success. |
214 // |MOJO_RESULT_INVALID_ARGUMENT| if |type| is not recognized. In this case, | 250 // |MOJO_RESULT_INVALID_ARGUMENT| if |type| is not recognized. In this case, |
215 // |value| is untouched. | 251 // |value| is untouched. |
216 MOJO_SYSTEM_EXPORT MojoResult MojoGetProperty(MojoPropertyType type, | 252 MOJO_SYSTEM_EXPORT MojoResult MojoGetProperty(MojoPropertyType type, |
217 void* value); | 253 void* value); |
218 | 254 |
219 #ifdef __cplusplus | 255 #ifdef __cplusplus |
220 } // extern "C" | 256 } // extern "C" |
221 #endif | 257 #endif |
222 | 258 |
223 #endif // MOJO_PUBLIC_C_SYSTEM_FUNCTIONS_H_ | 259 #endif // MOJO_PUBLIC_C_SYSTEM_FUNCTIONS_H_ |
OLD | NEW |