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

Side by Side Diff: mojo/public/c/system/wait_set.h

Issue 2744943002: Mojo: Move waiting APIs to public library (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
« no previous file with comments | « mojo/public/c/system/types.h ('k') | mojo/public/cpp/bindings/lib/connector.cc » ('j') | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
(Empty)
1 // Copyright 2015 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 // This file contains types/constants and functions specific to wait sets.
6 //
7 // Note: This header should be compilable as C.
8
9 #ifndef MOJO_PUBLIC_C_SYSTEM_WAIT_SET_H_
10 #define MOJO_PUBLIC_C_SYSTEM_WAIT_SET_H_
11
12 #include <stdint.h>
13
14 #include "mojo/public/c/system/system_export.h"
15 #include "mojo/public/c/system/types.h"
16
17 #ifdef __cplusplus
18 extern "C" {
19 #endif
20
21 // Note: See the comment in functions.h about the meaning of the "optional"
22 // label for pointer parameters.
23
24 // Creates a wait set. A wait set is a way to efficiently wait on multiple
25 // handles.
26 //
27 // On success, |*wait_set_handle| will contain a handle to a wait set.
28 //
29 // Returns:
30 // |MOJO_RESULT_OK| on success.
31 // |MOJO_RESULT_INVALID_ARGUMENT| if |wait_set_handle| is null.
32 // |MOJO_RESULT_RESOURCE_EXHAUSTED| if a process/system/quota/etc. limit has
33 // been reached.
34 MOJO_SYSTEM_EXPORT MojoResult MojoCreateWaitSet(
35 MojoHandle* wait_set_handle); // Out.
36
37 // Adds a wait on |handle| to |wait_set_handle|.
38 //
39 // A handle can only be added to any given wait set once, but may be added to
40 // any number of different wait sets. To modify the signals being waited for,
41 // the handle must first be removed, and then added with the new signals.
42 //
43 // If a handle is closed while still in the wait set, it is implicitly removed
44 // from the set after being returned from |MojoGetReadyHandles()| with the
45 // result |MOJO_RESULT_CANCELLED|.
46 //
47 // It is safe to add a handle to a wait set while performing a wait on another
48 // thread. If the added handle already has its signals satisfied, the waiting
49 // thread will be woken.
50 //
51 // Returns:
52 // |MOJO_RESULT_OK| if |handle| was successfully added to |wait_set_handle|.
53 // |MOJO_RESULT_INVALID_ARGUMENT| if |handle| is not a valid handle, or
54 // |wait_set_handle| is not a valid wait set.
55 // |MOJO_RESULT_ALREADY_EXISTS| if |handle| already exists in
56 // |wait_set_handle|.
57 MOJO_SYSTEM_EXPORT MojoResult MojoAddHandle(
58 MojoHandle wait_set_handle,
59 MojoHandle handle,
60 MojoHandleSignals signals);
61
62 // Removes |handle| from |wait_set_handle|.
63 //
64 // It is safe to remove a handle from a wait set while performing a wait on
65 // another thread. If handle has its signals satisfied while it is being
66 // removed, the waiting thread may be woken up, but no handle may be available
67 // when |MojoGetReadyHandles()| is called.
68 //
69 // Returns:
70 // |MOJO_RESULT_OK| if |handle| was successfully removed from
71 // |wait_set_handle|.
72 // |MOJO_RESULT_INVALID_ARGUMENT| if |handle| is not a valid handle, or
73 // |wait_set_handle| is not a valid wait set.
74 // |MOJO_RESULT_NOT_FOUND| if |handle| does not exist in |wait_set_handle|.
75 MOJO_SYSTEM_EXPORT MojoResult MojoRemoveHandle(
76 MojoHandle wait_set_handle,
77 MojoHandle handle);
78
79 // Retrieves a set of ready handles from |wait_set_handle|. A handle is ready if
80 // at least of of the following is true:
81 // - The handle's signals are satisfied.
82 // - It becomes known that no signal for the handle will ever be satisfied.
83 // - The handle is closed.
84 //
85 // A wait set may have ready handles when it satisfies the
86 // |MOJO_HANDLE_SIGNAL_READABLE| signal. Since handles may be added and removed
87 // from a wait set concurrently, it is possible for a wait set to satisfy
88 // |MOJO_HANDLE_SIGNAL_READABLE|, but not have any ready handles when
89 // |MojoGetReadyHandles()| is called. These spurious wake-ups must be gracefully
90 // handled.
91 //
92 // |*count| on input, must contain the maximum number of ready handles to be
93 // returned. On output, it will contain the number of ready handles returned.
94 //
95 // |handles| must point to an array of size |*count| of |MojoHandle|. It will be
96 // populated with handles that are considered ready. The number of handles
97 // returned will be in |*count|.
98 //
99 // |results| must point to an array of size |*count| of |MojoResult|. It will be
100 // populated with the wait result of the corresponding handle in |*handles|.
101 // Care should be taken that if a handle is closed on another thread, the handle
102 // would be invalid, but the result may not be |MOJO_RESULT_CANCELLED|. See
103 // documentation for |MojoWait()| for possible results.
104 //
105 // |signals_state| (optional) if non-null, must point to an array of size
106 // |*count| of |MojoHandleSignalsState|. It will be populated with the signals
107 // state of the corresponding handle in |*handles|. See documentation for
108 // |MojoHandleSignalsState| for more details about the meaning of each array
109 // entry. The array will always be updated for every returned handle.
110 //
111 // Mojo signals and satisfiability are logically 'level-triggered'. Therefore,
112 // if a signal continues to be satisfied and is not removed from the wait set,
113 // subsequent calls to |MojoGetReadyHandles()| will return the same handle.
114 //
115 // If multiple handles have their signals satisfied, the order in which handles
116 // are returned is undefined. The same handle, if not removed, may be returned
117 // in consecutive calls. Callers must not rely on any fairness and handles
118 // could be starved if not acted on.
119 //
120 // Returns:
121 // |MOJO_RESULT_OK| if ready handles are available.
122 // |MOJO_RESULT_INVALID_ARGUMENT| if |wait_set_handle| is not a valid wait
123 // set, if |*count| is 0, or if either |count|, |handles|, or |results| is
124 // null.
125 // |MOJO_RESULT_SHOULD_WAIT| if there are no ready handles.
126 MOJO_SYSTEM_EXPORT MojoResult MojoGetReadyHandles(
127 MojoHandle wait_set_handle,
128 uint32_t* count, // In/out.
129 MojoHandle* handles, // Out.
130 MojoResult* results, // Out.
131 struct MojoHandleSignalsState *signals_states); // Optional out.
132
133 #ifdef __cplusplus
134 } // extern "C"
135 #endif
136
137 #endif // MOJO_PUBLIC_C_SYSTEM_WAIT_SET_H_
OLDNEW
« no previous file with comments | « mojo/public/c/system/types.h ('k') | mojo/public/cpp/bindings/lib/connector.cc » ('j') | no next file with comments »

Powered by Google App Engine
This is Rietveld 408576698