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 | |
23 // some watched signals are satisfied or become unsatisfiable. See the | |
24 // documentation for |MojoWatch()| for more details. | |
25 typedef void (*MojoWatchCallback)(uintptr_t context, | |
26 MojoResult result, | |
27 struct MojoHandleSignalsState signals_state, | |
28 MojoWatchNotificationFlags flags); | |
29 | |
30 // Note: Pointer parameters that are labelled "optional" may be null (at least | 22 // Note: Pointer parameters that are labelled "optional" may be null (at least |
31 // under some circumstances). Non-const pointer parameters are also labeled | 23 // 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 | 24 // "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 | 25 // 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 | 26 // operation's success/failure. E.g., a separate |flags| parameter may control |
35 // whether a given "in/out" parameter is used for input, output, or both.) | 27 // whether a given "in/out" parameter is used for input, output, or both.) |
36 | 28 |
37 // Returns the time, in microseconds, since some undefined point in the past. | 29 // Returns the time, in microseconds, since some undefined point in the past. |
38 // The values are only meaningful relative to other values that were obtained | 30 // The values are only meaningful relative to other values that were obtained |
39 // from the same device without an intervening system restart. Such values are | 31 // from the same device without an intervening system restart. Such values are |
(...skipping 91 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
131 // |MOJO_RESULT_FAILED_PRECONDITION| if it is or becomes impossible that SOME | 123 // |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]|. | 124 // |handle[i]| will ever satisfy any of the signals in |signals[i]|. |
133 MOJO_SYSTEM_EXPORT MojoResult | 125 MOJO_SYSTEM_EXPORT MojoResult |
134 MojoWaitMany(const MojoHandle* handles, | 126 MojoWaitMany(const MojoHandle* handles, |
135 const MojoHandleSignals* signals, | 127 const MojoHandleSignals* signals, |
136 uint32_t num_handles, | 128 uint32_t num_handles, |
137 MojoDeadline deadline, | 129 MojoDeadline deadline, |
138 uint32_t* result_index, // Optional out | 130 uint32_t* result_index, // Optional out |
139 struct MojoHandleSignalsState* signals_states); // Optional out | 131 struct MojoHandleSignalsState* signals_states); // Optional out |
140 | 132 |
141 // Watches the given handle for one of the following events to happen: | |
142 // - A signal indicated by |signals| is satisfied. | |
143 // - It becomes known that no signal indicated by |signals| will ever be | |
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 // | |
148 // |handle|: The handle to watch. Must be an open message pipe or data pipe | |
149 // handle. | |
150 // |signals|: The signals to watch for. | |
151 // |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. | |
153 // |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 | |
155 // the watch later using |MojoCancelWatch()|. | |
156 // | |
157 // Returns: | |
158 // |MOJO_RESULT_OK| if the watch has been successfully registered. Note that | |
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 | |
165 // handle. | |
166 // |MOJO_RESULT_FAILED_PRECONDITION| if it is already known that |signals| can | |
167 // never be satisfied. | |
168 // |MOJO_RESULT_ALREADY_EXISTS| if there is already a watch registered for | |
169 // the same combination of |handle| and |context|. | |
170 // | |
171 // Callback result codes: | |
172 // The callback may be called at any time on any thread with one of the | |
173 // following result codes to indicate various events: | |
174 // | |
175 // |MOJO_RESULT_OK| indicates that some signal in |signals| has been | |
176 // satisfied. | |
177 // |MOJO_RESULT_FAILED_PRECONDITION| indicates that no signals in |signals| | |
178 // can ever be satisfied again. | |
179 // |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 | |
181 // |MojoCancelWatch()|. | |
182 MOJO_SYSTEM_EXPORT MojoResult | |
183 MojoWatch(MojoHandle handle, | |
184 MojoHandleSignals signals, | |
185 MojoWatchCallback callback, | |
186 uintptr_t context); | |
187 | |
188 // Cancels a handle watch corresponding to some prior call to |MojoWatch()|. | |
189 // | |
190 // NOTE: If the watch callback corresponding to |context| is currently running | |
191 // this will block until the callback completes execution. It is therefore | |
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 // | |
202 // Returns: | |
203 // |MOJO_RESULT_OK| if the watch corresponding to |context| was cancelled. | |
204 // |MOJO_RESULT_INVALID_ARGUMENT| if no watch was registered with |context| | |
205 // for the given |handle|, or if |handle| is invalid. | |
206 MOJO_SYSTEM_EXPORT MojoResult | |
207 MojoCancelWatch(MojoHandle handle, uintptr_t context); | |
208 | |
209 // Retrieves system properties. See the documentation for |MojoPropertyType| for | 133 // Retrieves system properties. See the documentation for |MojoPropertyType| for |
210 // supported property types and their corresponding output value type. | 134 // supported property types and their corresponding output value type. |
211 // | 135 // |
212 // Returns: | 136 // Returns: |
213 // |MOJO_RESULT_OK| on success. | 137 // |MOJO_RESULT_OK| on success. |
214 // |MOJO_RESULT_INVALID_ARGUMENT| if |type| is not recognized. In this case, | 138 // |MOJO_RESULT_INVALID_ARGUMENT| if |type| is not recognized. In this case, |
215 // |value| is untouched. | 139 // |value| is untouched. |
216 MOJO_SYSTEM_EXPORT MojoResult MojoGetProperty(MojoPropertyType type, | 140 MOJO_SYSTEM_EXPORT MojoResult MojoGetProperty(MojoPropertyType type, |
217 void* value); | 141 void* value); |
218 | 142 |
219 #ifdef __cplusplus | 143 #ifdef __cplusplus |
220 } // extern "C" | 144 } // extern "C" |
221 #endif | 145 #endif |
222 | 146 |
223 #endif // MOJO_PUBLIC_C_SYSTEM_FUNCTIONS_H_ | 147 #endif // MOJO_PUBLIC_C_SYSTEM_FUNCTIONS_H_ |
OLD | NEW |