Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(338)

Side by Side Diff: mojo/public/c/system/functions.h

Issue 2725133002: Mojo: Armed Watchers (Closed)
Patch Set: . Created 3 years, 9 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View unified diff | Download patch
OLDNEW
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
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_
OLDNEW

Powered by Google App Engine
This is Rietveld 408576698