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 |