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

Side by Side Diff: mojo/public/c/system/watcher.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
(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_
OLDNEW

Powered by Google App Engine
This is Rietveld 408576698