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

Unified Diff: mojo/public/c/system/watcher.h

Issue 2725133002: Mojo: Armed Watchers (Closed)
Patch Set: rebase 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 side-by-side diff with in-line comments
Download patch
Index: mojo/public/c/system/watcher.h
diff --git a/mojo/public/c/system/watcher.h b/mojo/public/c/system/watcher.h
new file mode 100644
index 0000000000000000000000000000000000000000..f152c50a11cf91578d08a1bcd6649f8d0769410b
--- /dev/null
+++ b/mojo/public/c/system/watcher.h
@@ -0,0 +1,183 @@
+// Copyright 2017 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef MOJO_PUBLIC_C_SYSTEM_WATCHER_H_
+#define MOJO_PUBLIC_C_SYSTEM_WATCHER_H_
+
+#include <stdint.h>
+
+#include "mojo/public/c/system/system_export.h"
+#include "mojo/public/c/system/types.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// A callback used to notify watchers about events on their watched handles.
+//
+// See documentation for |MojoWatcherNotificationFlags| for details regarding
+// the possible values of |flags|.
+//
+// See documentation for |MojoWatch()| for details regarding the other arguments
+// this callback receives when called.
+typedef void (*MojoWatcherCallback)(uintptr_t context,
+ MojoResult result,
+ struct MojoHandleSignalsState signals_state,
+ MojoWatcherNotificationFlags flags);
+
+// Creates a new watcher.
+//
+// Watchers are used to trigger arbitrary code execution when one or more
+// handles change state to meet certain conditions.
+//
+// A newly registered watcher is initially disarmed and may be armed using
+// |MojoArmWatcher()|. A watcher is also always disarmed immediately before any
+// invocation of one or more notification callbacks in response to a single
+// handle's state changing in some relevant way.
+//
+// Parameters:
+// |callback|: The |MojoWatcherCallback| to invoke any time the watcher is
+// notified of an event. See |MojoWatch()| for details regarding arguments
+// passed to the callback. Note that this may be called from any arbitrary
+// thread.
+// |watcher_handle|: The address at which to store the MojoHandle
+// corresponding to the new watcher if successfully created.
+//
+// Returns:
+// |MOJO_RESULT_OK| if the watcher has been successfully created.
+// |MOJO_RESULT_RESOURCE_EXHAUSTED| if a handle could not be allocated for
+// this watcher.
+MOJO_SYSTEM_EXPORT MojoResult MojoCreateWatcher(MojoWatcherCallback callback,
+ MojoHandle* watcher_handle);
+
+// Adds a watch to a watcher. This allows the watcher to fire notifications
+// regarding state changes on the handle corresponding to the arguments given.
+//
+// Note that notifications for a given watch context are guaranteed to be
+// mutually exclusive in execution: the callback will never be entered for a
+// given context while another invocation of the callback is still executing for
+// the same context. As a result it is generally a good idea to ensure that
+// callbacks do as little work as necessary in order to process the
+// notification.
+//
+// Parameters:
+// |watcher_handle|: The watcher to which |handle| is to be added.
+// |handle|: The handle to add to the watcher.
+// |signals|: The signals to watch for on |handle|.
+// |context|: An arbitrary context value given to any invocation of the
+// watcher's callback when invoked as a result of some state change
+// relevant to this combination of |handle| and |signals|. Must be
+// unique within any given watcher.
+//
+// Callback parameters (see |MojoWatcherNotificationCallback| above):
+// When the watcher invokes its callback as a result of some notification
+// relevant to this watch operation, |context| receives the value given here
+// and |signals_state| receives the last known signals state of this handle.
+//
+// |result| is one of the following:
+// |MOJO_RESULT_OK| if at least one of the watched signals is satisfied. The
+// watcher must be armed for this notification to fire.
+// |MOJO_RESULT_FAILED_PRECONDITION| if all of the watched signals are
+// permanently unsatisfiable. The watcher must be armed for this
+// notification to fire.
+// |MOJO_RESULT_CANCELLED| if the watch has been cancelled. The may occur if
+// the watcher has been closed, the watched handle has been closed, or
+// the watch for |context| has been explicitly cancelled. This is always
+// the last result received for any given context, and it is guaranteed
+// to be received exactly once per watch, regardless of how the watch
+// was cancelled.
+//
+// Returns:
+// |MOJO_RESULT_OK| if the handle is now being watched by the watcher.
+// |MOJO_RESULT_INVALID_ARGUMENT| if |watcher_handle| is not a watcher handle,
+// |handle| is not a valid message pipe or data pipe handle.
+// |MOJO_RESULT_ALREADY_EXISTS| if the watcher already has a watch registered
+// for the given value of |context| or for the given |handle|.
+MOJO_SYSTEM_EXPORT MojoResult MojoWatch(MojoHandle watcher_handle,
+ MojoHandle handle,
+ MojoHandleSignals signals,
+ uintptr_t context);
+
+// Removes a watch from a watcher.
+//
+// This ensures that the watch is cancelled as soon as possible. Cancellation
+// may be deferred (or may even block) an aritrarily long time if the watch is
+// already dispatching one or more notifications.
+//
+// When cancellation is complete, the watcher's callback is invoked one final
+// time for |context|, with the result |MOJO_RESULT_CANCELLED|.
+//
+// The same behavior can be elicted by either closing the watched handle
+// associated with this context, or by closing |watcher_handle| itself. In the
+// lastter case, all registered contexts on the watcher are implicitly cancelled
+// in a similar fashion.
+//
+// Parameters:
+// |watcher_handle|: The handle of the watcher from which to remove a watch.
+// |context|: The context of the watch to be removed.
+//
+// Returns:
+// |MOJO_RESULT_OK| if the watch has been cancelled.
+// |MOJO_RESULT_INVALID_ARGUMENT| if |watcher_handle| is not a watcher handle.
+// |MOJO_RESULT_NOT_FOUND| if there is no watch registered on this watcher for
+// the given value of |context|.
+MOJO_SYSTEM_EXPORT MojoResult MojoCancelWatch(MojoHandle watcher_handle,
+ uintptr_t context);
+
+// Arms a watcher, enabling a single future event on one of the watched handles
+// to trigger a single notification for each relevant watch context associated
+// with that handle.
+//
+// Parameters:
+// |watcher_handle|: The handle of the watcher.
+// |num_ready_contexts|: An address pointing to the number of elements
+// available for storage in the remaining output buffers. Optional and
+// only used on failure. See |MOJO_RESULT_FAILED_PRECONDITION| below for
+// more details.
+// |ready_contexts|: An output buffer for contexts corresponding to the
+// watches which would have notified if the watcher were armed. Optional
+// and only uesd on failure. See |MOJO_RESULT_FAILED_PRECONDITION| below
+// for more details.
+// |ready_results|: An output buffer for MojoResult values corresponding to
+// each context in |ready_contexts|. Optional and only used on failure.
+// See |MOJO_RESULT_FAILED_PRECONDITION| below for more details.
+// |ready_signals_states|: An output buffer for |MojoHandleSignalsState|
+// structures corresponding to each context in |ready_contexts|. Optional
+// and only used on failure. See |MOJO_RESULT_FAILED_PRECONDITION| below
+// for more details.
+//
+// Returns:
+// |MOJO_RESULT_OK| if the watcher has been successfully armed. All arguments
+// other than |watcher_handle| are ignored in this case.
+// |MOJO_RESULT_NOT_FOUND| if the watcher does not have any registered watch
+// contexts. All arguments other than |watcher_handle| are ignored in this
+// case.
+// |MOJO_RESULT_INVALID_ARGUMENT| if |watcher_handle| is not a valid watcher
+// handle, or if |num_ready_contexts| is non-null but any of the output
+// buffer paramters is null.
+// |MOJO_RESULT_FAILED_PRECONDITION| if one or more watches would have
+// notified immediately upon arming the watcher. If |num_handles| is
+// non-null, this assumes there is enough space for |*num_handles| entries
+// in each of the subsequent output buffer arguments.
+//
+// At most that many entries are placed in the output buffers,
+// corresponding to the watches which would have signalled if the watcher
+// had been armed successfully. The actual number of entries placed in the
+// output buffers is written to |*num_ready_contexts| before returning.
+//
+// If more than (input) |*num_ready_contexts| watch contexts were ready to
+// notify, the subset presented in output buffers is arbitrary and
+// implementation-defined.
+MOJO_SYSTEM_EXPORT MojoResult
+MojoArmWatcher(MojoHandle watcher_handle,
+ uint32_t* num_ready_contexts,
+ uintptr_t* ready_contexts,
+ MojoResult* ready_results,
+ struct MojoHandleSignalsState* ready_signals_states);
+
+#ifdef __cplusplus
+} // extern "C"
+#endif
+
+#endif // MOJO_PUBLIC_C_SYSTEM_WATCHER_H_

Powered by Google App Engine
This is Rietveld 408576698