OLD | NEW |
---|---|
(Empty) | |
1 // Copyright 2017 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 #ifndef MOJO_PUBLIC_C_SYSTEM_WATCHER_H_ | |
6 #define MOJO_PUBLIC_C_SYSTEM_WATCHER_H_ | |
7 | |
8 #include <stdint.h> | |
9 | |
10 #include "mojo/public/c/system/system_export.h" | |
11 #include "mojo/public/c/system/types.h" | |
12 | |
13 #ifdef __cplusplus | |
14 extern "C" { | |
15 #endif | |
16 | |
17 // A callback used to notify watchers about events on their watched handles. | |
18 // | |
19 // See documentation for |MojoWatcherNotificationFlags| for details regarding | |
20 // the possible values of |flags|. | |
21 // | |
22 // See documentation for |MojoWatch()| for details regarding the other arguments | |
23 // this callback receives when called. | |
24 typedef void (*MojoWatcherCallback)(uintptr_t context, | |
25 MojoResult result, | |
26 struct MojoHandleSignalsState signals_state, | |
27 MojoWatcherNotificationFlags flags); | |
28 | |
29 // Creates a new watcher. | |
30 // | |
31 // Watchers are used to trigger arbitrary code execution when one or more | |
32 // handles change state to meet certain conditions. | |
33 // | |
34 // A newly registered watcher is initially disarmed and may be armed using | |
35 // |MojoArmWatcher()|. A watcher is also always disarmed immediately before any | |
36 // invocation of one or more notification callbacks in response to a single | |
37 // handle's state changing in some relevant way. | |
38 // | |
39 // Parameters: | |
40 // |callback|: The |MojoWatcherCallback| to invoke any time the watcher is | |
41 // notified of an event. See |MojoWatch()| for details regarding arguments | |
42 // passed to the callback. Note that this may be called from any arbitrary | |
43 // thread. | |
44 // |watcher_handle|: The address at which to store the MojoHandle | |
45 // corresponding to the new watcher if successfully created. | |
46 // | |
47 // Returns: | |
48 // |MOJO_RESULT_OK| if the watcher has been successfully created. | |
49 // |MOJO_RESULT_RESOURCE_EXHAUSTED| if a handle could not be allocated for | |
50 // this watcher. | |
51 MOJO_SYSTEM_EXPORT MojoResult MojoCreateWatcher(MojoWatcherCallback callback, | |
52 MojoHandle* watcher_handle); | |
53 | |
54 // Adds a watch to a watcher. This allows the watcher to fire notifications | |
55 // regarding state changes on the handle corresponding to the arguments given. | |
56 // | |
57 // The same handle may be watched multiple times by the same watcher (e.g. to | |
58 // watch different signals) as long as a different |context| is provided for | |
yzshen1
2017/03/11 00:44:58
Are there use cases where we need to watch a handl
Ken Rockot(use gerrit already)
2017/03/12 22:24:13
Good point. I was trying to keep the API as flexib
| |
59 // each |MojoWatch()| call. | |
60 // | |
61 // If multiple registered watches are affected by the same handle state change | |
62 // while the watcher is armed, one invocation of the callback will occur for | |
63 // each of the affected watches, in unspecified order. | |
64 // | |
65 // Note that notifications for a given watch context are guaranteed to be | |
66 // mutually exclusive in execution: the callback will never be entered for a | |
67 // given context while another invocation of the callback is still executing for | |
68 // the same context. As a result it is generally a good idea to ensure that | |
69 // callbacks do as little work as necessary in order to process the | |
70 // notification. | |
71 // | |
72 // Parameters: | |
73 // |watcher_handle|: The watcher to which |handle| is to be added. | |
74 // |handle|: The handle to add to the watcher. | |
75 // |signals|: The signals to watch for on |handle|. | |
76 // |context|: An arbitrary context value given to any invocation of the | |
77 // watcher's callback when invoked as a result of some state change | |
78 // relevant to this combination of |handle| and |signals|. Must be | |
79 // unique within any given watcher. | |
80 // | |
81 // Callback parameters (see |MojoWatcherNotificationCallback| above): | |
82 // When the watcher invokes its callback as a result of some notification | |
83 // relevant to this watch operation, |context| receives the value given here | |
84 // and |signals_state| receives the last known signals state of this handle. | |
85 // | |
86 // |result| is one of the following: | |
87 // |MOJO_RESULT_OK| if at least one of the watched signals is satisfied. The | |
88 // watcher must be armed for this notification to fire. | |
89 // |MOJO_RESULT_FAILED_PRECONDITION| if all of the watched signals are | |
90 // permanently unsatisfiable. The watcher must be armed for this | |
91 // notification to fire. | |
92 // |MOJO_RESULT_CANCELLED| if the watch has been cancelled. The may occur if | |
93 // the watcher has been closed, the watched handle has been closed, or | |
94 // the watch for |context| has been explicitly cancelled. This is always | |
95 // the last result received for any given context, and it is guaranteed | |
96 // to be received exactly once per watch, regardless of how the watch | |
97 // was cancelled. | |
98 // | |
99 // Returns: | |
100 // |MOJO_RESULT_OK| if the handle is now being watched by the watcher. | |
101 // |MOJO_RESULT_INVALID_ARGUMENT| if |watcher_handle| is not a watcher handle, | |
102 // |handle| is not a valid message pipe or data pipe handle. | |
103 // |MOJO_RESULT_ALREADY_EXISTS| if the watcher already has a watch registered | |
104 // for the given value of |context|. | |
105 MOJO_SYSTEM_EXPORT MojoResult MojoWatch(MojoHandle watcher_handle, | |
106 MojoHandle handle, | |
107 MojoHandleSignals signals, | |
108 uintptr_t context); | |
109 | |
110 // Removes a watch from a watcher. | |
111 // | |
112 // This ensures that the watch is cancelled as soon as possible. Cancellation | |
113 // may be deferred (or may even block) an aritrarily long time if the watch is | |
114 // already dispatching one or more notifications. | |
115 // | |
116 // When cancellation is complete, the watcher's callback is invoked one final | |
117 // time for |context|, with the result |MOJO_RESULT_CANCELLED|. | |
118 // | |
119 // The same behavior can be elicted by either closing the watched handle | |
120 // associated with this context, or by closing |watcher_handle| itself. In the | |
121 // lastter case, all registered contexts no the watcher are implicitly cancelled | |
yzshen1
2017/03/11 00:44:58
no -> on
Ken Rockot(use gerrit already)
2017/03/12 22:24:13
Done
| |
122 // in a similar fashion. | |
123 // | |
124 // Parameters: | |
125 // |watcher_handle|: The handle of the watcher from which to remove a watch. | |
126 // |context|: The context of the watch to be removed. | |
127 // | |
128 // Returns: | |
129 // |MOJO_RESULT_OK| if the watch has been cancelled. | |
130 // |MOJO_RESULT_INVALID_ARGUMENT| if |watcher_handle| is not a watcher handle. | |
131 // |MOJO_RESULT_NOT_FOUND| if there is no watch registered on this watcher for | |
132 // the given value of |context|. | |
133 MOJO_SYSTEM_EXPORT MojoResult MojoCancelWatch(MojoHandle watcher_handle, | |
134 uintptr_t context); | |
135 | |
136 // Arms a watcher, enabling a single future event on one of the watched handles | |
137 // to trigger a single notification for each relevant watch context associated | |
138 // with that handle. | |
139 // | |
140 // Parameters: | |
141 // |watcher_handle|: The handle of the watcher. | |
142 // |num_ready_contexts|: An address pointing to the number of elements | |
143 // available for storage in the remaining output buffers. Optional and | |
144 // only used on failure. See |MOJO_RESULT_FAILED_PRECONDITION| below for | |
145 // more details. | |
146 // |ready_contexts|: An output buffer for contexts corresponding to the | |
147 // watches which would have notified if the watcher were armed. Optional | |
148 // and only uesd on failure. See |MOJO_RESULT_FAILED_PRECONDITION| below | |
149 // for more details. | |
150 // |ready_results|: An output buffer for MojoResult values corresponding to | |
151 // each context in |ready_contexts|. Optional and only used on failure. | |
152 // See |MOJO_RESULT_FAILED_PRECONDITION| below for more details. | |
153 // |ready_signals_states|: An output buffer for |MojoHandleSignalsState| | |
154 // structures corresponding to each context in |ready_contexts|. Optional | |
155 // and only used on failure. See |MOJO_RESULT_FAILED_PRECONDITION| below | |
156 // for more details. | |
157 // | |
158 // Returns: | |
159 // |MOJO_RESULT_OK| if the watcher has been successfully armed. All arguments | |
160 // other than |watcher_handle| are ignored in this case. | |
161 // |MOJO_RESULT_NOT_FOUND| if the watcher does not have any registered watch | |
162 // contexts. All arguments other than |watcher_handle| are ignored in this | |
163 // case. | |
164 // |MOJO_RESULT_INVALID_ARGUMENT| if |watcher_handle| is not a valid watcher | |
165 // handle, or if |num_ready_contexts| is non-null but any of the output | |
166 // buffer paramters is null. | |
167 // |MOJO_RESULT_FAILED_PRECONDITION| if one or more watches would have | |
168 // notified immediately upon arming the watcher. If |num_handles| is | |
169 // non-null, this assumes there is enough space for |*num_handles| entries | |
170 // in each of the subsequent output buffer arguments. | |
171 // | |
172 // At most that many entries are placed in the output buffers, | |
173 // corresponding to the watches which would have signalled if the watcher | |
174 // had been armed successfully. The actual number of entries placed in the | |
175 // output buffers is written to |*num_ready_contexts| before returning. | |
176 // | |
177 // If more than (input) |*num_ready_contexts| watch contexts were ready to | |
178 // notify, the subset presented in output buffers is arbitrary and | |
179 // implementation-defined. | |
180 MOJO_SYSTEM_EXPORT MojoResult | |
181 MojoArmWatcher(MojoHandle watcher_handle, | |
182 uint32_t* num_ready_contexts, | |
183 uintptr_t* ready_contexts, | |
184 MojoResult* ready_results, | |
185 struct MojoHandleSignalsState* ready_signals_states); | |
186 | |
187 #ifdef __cplusplus | |
188 } // extern "C" | |
189 #endif | |
190 | |
191 #endif // MOJO_PUBLIC_C_SYSTEM_WATCHER_H_ | |
OLD | NEW |