| 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 // Note that notifications for a given watch context are guaranteed to be | |
| 58 // mutually exclusive in execution: the callback will never be entered for a | |
| 59 // given context while another invocation of the callback is still executing for | |
| 60 // the same context. As a result it is generally a good idea to ensure that | |
| 61 // callbacks do as little work as necessary in order to process the | |
| 62 // notification. | |
| 63 // | |
| 64 // Parameters: | |
| 65 // |watcher_handle|: The watcher to which |handle| is to be added. | |
| 66 // |handle|: The handle to add to the watcher. | |
| 67 // |signals|: The signals to watch for on |handle|. | |
| 68 // |context|: An arbitrary context value given to any invocation of the | |
| 69 // watcher's callback when invoked as a result of some state change | |
| 70 // relevant to this combination of |handle| and |signals|. Must be | |
| 71 // unique within any given watcher. | |
| 72 // | |
| 73 // Callback parameters (see |MojoWatcherNotificationCallback| above): | |
| 74 // When the watcher invokes its callback as a result of some notification | |
| 75 // relevant to this watch operation, |context| receives the value given here | |
| 76 // and |signals_state| receives the last known signals state of this handle. | |
| 77 // | |
| 78 // |result| is one of the following: | |
| 79 // |MOJO_RESULT_OK| if at least one of the watched signals is satisfied. The | |
| 80 // watcher must be armed for this notification to fire. | |
| 81 // |MOJO_RESULT_FAILED_PRECONDITION| if all of the watched signals are | |
| 82 // permanently unsatisfiable. The watcher must be armed for this | |
| 83 // notification to fire. | |
| 84 // |MOJO_RESULT_CANCELLED| if the watch has been cancelled. The may occur if | |
| 85 // the watcher has been closed, the watched handle has been closed, or | |
| 86 // the watch for |context| has been explicitly cancelled. This is always | |
| 87 // the last result received for any given context, and it is guaranteed | |
| 88 // to be received exactly once per watch, regardless of how the watch | |
| 89 // was cancelled. | |
| 90 // | |
| 91 // Returns: | |
| 92 // |MOJO_RESULT_OK| if the handle is now being watched by the watcher. | |
| 93 // |MOJO_RESULT_INVALID_ARGUMENT| if |watcher_handle| is not a watcher handle, | |
| 94 // |handle| is not a valid message pipe or data pipe handle. | |
| 95 // |MOJO_RESULT_ALREADY_EXISTS| if the watcher already has a watch registered | |
| 96 // for the given value of |context| or for the given |handle|. | |
| 97 MOJO_SYSTEM_EXPORT MojoResult MojoWatch(MojoHandle watcher_handle, | |
| 98 MojoHandle handle, | |
| 99 MojoHandleSignals signals, | |
| 100 uintptr_t context); | |
| 101 | |
| 102 // Removes a watch from a watcher. | |
| 103 // | |
| 104 // This ensures that the watch is cancelled as soon as possible. Cancellation | |
| 105 // may be deferred (or may even block) an aritrarily long time if the watch is | |
| 106 // already dispatching one or more notifications. | |
| 107 // | |
| 108 // When cancellation is complete, the watcher's callback is invoked one final | |
| 109 // time for |context|, with the result |MOJO_RESULT_CANCELLED|. | |
| 110 // | |
| 111 // The same behavior can be elicted by either closing the watched handle | |
| 112 // associated with this context, or by closing |watcher_handle| itself. In the | |
| 113 // lastter case, all registered contexts on the watcher are implicitly cancelled | |
| 114 // in a similar fashion. | |
| 115 // | |
| 116 // Parameters: | |
| 117 // |watcher_handle|: The handle of the watcher from which to remove a watch. | |
| 118 // |context|: The context of the watch to be removed. | |
| 119 // | |
| 120 // Returns: | |
| 121 // |MOJO_RESULT_OK| if the watch has been cancelled. | |
| 122 // |MOJO_RESULT_INVALID_ARGUMENT| if |watcher_handle| is not a watcher handle. | |
| 123 // |MOJO_RESULT_NOT_FOUND| if there is no watch registered on this watcher for | |
| 124 // the given value of |context|. | |
| 125 MOJO_SYSTEM_EXPORT MojoResult MojoCancelWatch(MojoHandle watcher_handle, | |
| 126 uintptr_t context); | |
| 127 | |
| 128 // Arms a watcher, enabling a single future event on one of the watched handles | |
| 129 // to trigger a single notification for each relevant watch context associated | |
| 130 // with that handle. | |
| 131 // | |
| 132 // Parameters: | |
| 133 // |watcher_handle|: The handle of the watcher. | |
| 134 // |num_ready_contexts|: An address pointing to the number of elements | |
| 135 // available for storage in the remaining output buffers. Optional and | |
| 136 // only used on failure. See |MOJO_RESULT_FAILED_PRECONDITION| below for | |
| 137 // more details. | |
| 138 // |ready_contexts|: An output buffer for contexts corresponding to the | |
| 139 // watches which would have notified if the watcher were armed. Optional | |
| 140 // and only uesd on failure. See |MOJO_RESULT_FAILED_PRECONDITION| below | |
| 141 // for more details. | |
| 142 // |ready_results|: An output buffer for MojoResult values corresponding to | |
| 143 // each context in |ready_contexts|. Optional and only used on failure. | |
| 144 // See |MOJO_RESULT_FAILED_PRECONDITION| below for more details. | |
| 145 // |ready_signals_states|: An output buffer for |MojoHandleSignalsState| | |
| 146 // structures corresponding to each context in |ready_contexts|. Optional | |
| 147 // and only used on failure. See |MOJO_RESULT_FAILED_PRECONDITION| below | |
| 148 // for more details. | |
| 149 // | |
| 150 // Returns: | |
| 151 // |MOJO_RESULT_OK| if the watcher has been successfully armed. All arguments | |
| 152 // other than |watcher_handle| are ignored in this case. | |
| 153 // |MOJO_RESULT_NOT_FOUND| if the watcher does not have any registered watch | |
| 154 // contexts. All arguments other than |watcher_handle| are ignored in this | |
| 155 // case. | |
| 156 // |MOJO_RESULT_INVALID_ARGUMENT| if |watcher_handle| is not a valid watcher | |
| 157 // handle, or if |num_ready_contexts| is non-null but any of the output | |
| 158 // buffer paramters is null. | |
| 159 // |MOJO_RESULT_FAILED_PRECONDITION| if one or more watches would have | |
| 160 // notified immediately upon arming the watcher. If |num_handles| is | |
| 161 // non-null, this assumes there is enough space for |*num_handles| entries | |
| 162 // in each of the subsequent output buffer arguments. | |
| 163 // | |
| 164 // At most that many entries are placed in the output buffers, | |
| 165 // corresponding to the watches which would have signalled if the watcher | |
| 166 // had been armed successfully. The actual number of entries placed in the | |
| 167 // output buffers is written to |*num_ready_contexts| before returning. | |
| 168 // | |
| 169 // If more than (input) |*num_ready_contexts| watch contexts were ready to | |
| 170 // notify, the subset presented in output buffers is arbitrary and | |
| 171 // implementation-defined. | |
| 172 MOJO_SYSTEM_EXPORT MojoResult | |
| 173 MojoArmWatcher(MojoHandle watcher_handle, | |
| 174 uint32_t* num_ready_contexts, | |
| 175 uintptr_t* ready_contexts, | |
| 176 MojoResult* ready_results, | |
| 177 struct MojoHandleSignalsState* ready_signals_states); | |
| 178 | |
| 179 #ifdef __cplusplus | |
| 180 } // extern "C" | |
| 181 #endif | |
| 182 | |
| 183 #endif // MOJO_PUBLIC_C_SYSTEM_WATCHER_H_ | |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 2750373002:
Revert of Mojo: Armed Watchers (Closed)
