OLD | NEW |
| (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_ | |
OLD | NEW |