OLD | NEW |
1 // Copyright 2014 The Chromium Authors. All rights reserved. | 1 // Copyright 2014 The Chromium Authors. All rights reserved. |
2 // Use of this source code is governed by a BSD-style license that can be | 2 // Use of this source code is governed by a BSD-style license that can be |
3 // found in the LICENSE file. | 3 // found in the LICENSE file. |
4 | 4 |
5 // This file contains basic functions common to different Mojo system APIs. | 5 // This file contains basic functions common to different Mojo system APIs. |
6 // | 6 // |
7 // Note: This header should be compilable as C. | 7 // Note: This header should be compilable as C. |
8 | 8 |
9 #ifndef MOJO_PUBLIC_C_SYSTEM_FUNCTIONS_H_ | 9 #ifndef MOJO_PUBLIC_C_SYSTEM_FUNCTIONS_H_ |
10 #define MOJO_PUBLIC_C_SYSTEM_FUNCTIONS_H_ | 10 #define MOJO_PUBLIC_C_SYSTEM_FUNCTIONS_H_ |
(...skipping 24 matching lines...) Expand all Loading... |
35 // Returns: | 35 // Returns: |
36 // |MOJO_RESULT_OK| on success. | 36 // |MOJO_RESULT_OK| on success. |
37 // |MOJO_RESULT_INVALID_ARGUMENT| if |handle| is not a valid handle. | 37 // |MOJO_RESULT_INVALID_ARGUMENT| if |handle| is not a valid handle. |
38 // | 38 // |
39 // Concurrent operations on |handle| may succeed (or fail as usual) if they | 39 // Concurrent operations on |handle| may succeed (or fail as usual) if they |
40 // happen before the close, be cancelled with result |MOJO_RESULT_CANCELLED| if | 40 // happen before the close, be cancelled with result |MOJO_RESULT_CANCELLED| if |
41 // they properly overlap (this is likely the case with |MojoWait()|, etc.), or | 41 // they properly overlap (this is likely the case with |MojoWait()|, etc.), or |
42 // fail with |MOJO_RESULT_INVALID_ARGUMENT| if they happen after. | 42 // fail with |MOJO_RESULT_INVALID_ARGUMENT| if they happen after. |
43 MOJO_SYSTEM_EXPORT MojoResult MojoClose(MojoHandle handle); | 43 MOJO_SYSTEM_EXPORT MojoResult MojoClose(MojoHandle handle); |
44 | 44 |
45 // Waits on the given handle until a signal indicated by |signals| is satisfied, | |
46 // it becomes known that no signal indicated by |signals| will ever be satisfied | |
47 // (see the description of the |MOJO_RESULT_CANCELLED| and | |
48 // |MOJO_RESULT_FAILED_PRECONDITION| return values below), or until |deadline| | |
49 // has passed. | |
50 // | |
51 // If |deadline| is |MOJO_DEADLINE_INDEFINITE|, this will wait "forever" (until | |
52 // one of the other wait termination conditions is satisfied). If |deadline| is | |
53 // 0, this will return |MOJO_RESULT_DEADLINE_EXCEEDED| only if one of the other | |
54 // termination conditions (e.g., a signal is satisfied, or all signals are | |
55 // unsatisfiable) is not already satisfied. | |
56 // | |
57 // Returns: | |
58 // |MOJO_RESULT_OK| if some signal in |signals| was satisfied (or is already | |
59 // satisfied). | |
60 // |MOJO_RESULT_CANCELLED| if |handle| was closed (necessarily from another | |
61 // thread) during the wait. | |
62 // |MOJO_RESULT_INVALID_ARGUMENT| if |handle| is not a valid handle (e.g., if | |
63 // it has already been closed). | |
64 // |MOJO_RESULT_DEADLINE_EXCEEDED| if the deadline has passed without any of | |
65 // the signals being satisfied. | |
66 // |MOJO_RESULT_FAILED_PRECONDITION| if it becomes known that none of the | |
67 // signals in |signals| can ever be satisfied (e.g., when waiting on one | |
68 // end of a message pipe and the other end is closed). | |
69 // | |
70 // If there are multiple waiters (on different threads, obviously) waiting on | |
71 // the same handle and signal, and that signal becomes is satisfied, all waiters | |
72 // will be awoken. | |
73 MOJO_SYSTEM_EXPORT MojoResult MojoWait(MojoHandle handle, | |
74 MojoHandleSignals signals, | |
75 MojoDeadline deadline); | |
76 | |
77 // Waits on |handles[0]|, ..., |handles[num_handles-1]| until (at least) one | |
78 // satisfies a signal indicated in its respective |signals[0]|, ..., | |
79 // |signals[num_handles-1]|, it becomes known that no signal in some | |
80 // |signals[i]| will ever be satisfied, or until |deadline| has passed. | |
81 // | |
82 // This means that |MojoWaitMany()| behaves as if |MojoWait()| were called on | |
83 // each handle/signals pair simultaneously, completing when the first | |
84 // |MojoWait()| would complete. | |
85 // | |
86 // See |MojoWait()| for more details about |deadline|. | |
87 // | |
88 // Returns: | |
89 // The index |i| (from 0 to |num_handles-1|) if |handle[i]| satisfies a signal | |
90 // from |signals[i]|. | |
91 // |MOJO_RESULT_CANCELLED| if some |handle[i]| was closed (necessarily from | |
92 // another thread) during the wait. | |
93 // |MOJO_RESULT_INVALID_ARGUMENT| if some |handle[i]| is not a valid handle | |
94 // (e.g., if it has already been closed). | |
95 // |MOJO_RESULT_DEADLINE_EXCEEDED| if the deadline has passed without any of | |
96 // handles satisfying any of its signals. | |
97 // |MOJO_RESULT_FAILED_PRECONDITION| if it is or becomes impossible that SOME | |
98 // |handle[i]| will ever satisfy any of the signals in |signals[i]|. | |
99 MOJO_SYSTEM_EXPORT MojoResult MojoWaitMany(const MojoHandle* handles, | |
100 const MojoHandleSignals* signals, | |
101 uint32_t num_handles, | |
102 MojoDeadline deadline); | |
103 | |
104 // Waits on the given handle until one of the following happens: | 45 // Waits on the given handle until one of the following happens: |
105 // - A signal indicated by |signals| is satisfied. | 46 // - A signal indicated by |signals| is satisfied. |
106 // - It becomes known that no signal indicated by |signals| will ever be | 47 // - It becomes known that no signal indicated by |signals| will ever be |
107 // satisfied. (See the description of the |MOJO_RESULT_CANCELLED| and | 48 // satisfied. (See the description of the |MOJO_RESULT_CANCELLED| and |
108 // |MOJO_RESULT_FAILED_PRECONDITION| return values below.) | 49 // |MOJO_RESULT_FAILED_PRECONDITION| return values below.) |
109 // - Until |deadline| has passed. | 50 // - Until |deadline| has passed. |
110 // | 51 // |
111 // If |deadline| is |MOJO_DEADLINE_INDEFINITE|, this will wait "forever" (until | 52 // If |deadline| is |MOJO_DEADLINE_INDEFINITE|, this will wait "forever" (until |
112 // one of the other wait termination conditions is satisfied). If |deadline| is | 53 // one of the other wait termination conditions is satisfied). If |deadline| is |
113 // 0, this will return |MOJO_RESULT_DEADLINE_EXCEEDED| only if one of the other | 54 // 0, this will return |MOJO_RESULT_DEADLINE_EXCEEDED| only if one of the other |
(...skipping 12 matching lines...) Expand all Loading... |
126 // |MOJO_RESULT_DEADLINE_EXCEEDED| if the deadline has passed without any of | 67 // |MOJO_RESULT_DEADLINE_EXCEEDED| if the deadline has passed without any of |
127 // the signals being satisfied. | 68 // the signals being satisfied. |
128 // |MOJO_RESULT_FAILED_PRECONDITION| if it becomes known that none of the | 69 // |MOJO_RESULT_FAILED_PRECONDITION| if it becomes known that none of the |
129 // signals in |signals| can ever be satisfied (e.g., when waiting on one | 70 // signals in |signals| can ever be satisfied (e.g., when waiting on one |
130 // end of a message pipe and the other end is closed). | 71 // end of a message pipe and the other end is closed). |
131 // | 72 // |
132 // If there are multiple waiters (on different threads, obviously) waiting on | 73 // If there are multiple waiters (on different threads, obviously) waiting on |
133 // the same handle and signal, and that signal becomes is satisfied, all waiters | 74 // the same handle and signal, and that signal becomes is satisfied, all waiters |
134 // will be awoken. | 75 // will be awoken. |
135 MOJO_SYSTEM_EXPORT MojoResult | 76 MOJO_SYSTEM_EXPORT MojoResult |
136 MojoNewWait(MojoHandle handle, | 77 MojoWait(MojoHandle handle, |
137 MojoHandleSignals signals, | 78 MojoHandleSignals signals, |
138 MojoDeadline deadline, | 79 MojoDeadline deadline, |
139 struct MojoHandleSignalsState* signals_state); // Optional out. | 80 struct MojoHandleSignalsState* signals_state); // Optional out. |
140 | 81 |
141 // Waits on |handles[0]|, ..., |handles[num_handles-1]| until: | 82 // Waits on |handles[0]|, ..., |handles[num_handles-1]| until: |
142 // - (At least) one handle satisfies a signal indicated in its respective | 83 // - (At least) one handle satisfies a signal indicated in its respective |
143 // |signals[0]|, ..., |signals[num_handles-1]|. | 84 // |signals[0]|, ..., |signals[num_handles-1]|. |
144 // - It becomes known that no signal in some |signals[i]| will ever be | 85 // - It becomes known that no signal in some |signals[i]| will ever be |
145 // satisfied. | 86 // satisfied. |
146 // - |deadline| has passed. | 87 // - |deadline| has passed. |
147 // | 88 // |
148 // This means that |MojoWaitMany()| behaves as if |MojoWait()| were called on | 89 // This means that |MojoWaitMany()| behaves as if |MojoWait()| were called on |
149 // each handle/signals pair simultaneously, completing when the first | 90 // each handle/signals pair simultaneously, completing when the first |
(...skipping 21 matching lines...) Expand all Loading... |
171 // |MOJO_RESULT_RESOURCE_EXHAUSTED| if there are too many handles. The | 112 // |MOJO_RESULT_RESOURCE_EXHAUSTED| if there are too many handles. The |
172 // |signals_state| array is unchanged. | 113 // |signals_state| array is unchanged. |
173 // |MOJO_RESULT_INVALID_ARGUMENT| if some |handle[i]| is not a valid handle | 114 // |MOJO_RESULT_INVALID_ARGUMENT| if some |handle[i]| is not a valid handle |
174 // (e.g., if it is zero or if it has already been closed). The | 115 // (e.g., if it is zero or if it has already been closed). The |
175 // |signals_state| array is unchanged. | 116 // |signals_state| array is unchanged. |
176 // |MOJO_RESULT_DEADLINE_EXCEEDED| if the deadline has passed without any of | 117 // |MOJO_RESULT_DEADLINE_EXCEEDED| if the deadline has passed without any of |
177 // handles satisfying any of its signals. | 118 // handles satisfying any of its signals. |
178 // |MOJO_RESULT_FAILED_PRECONDITION| if it is or becomes impossible that SOME | 119 // |MOJO_RESULT_FAILED_PRECONDITION| if it is or becomes impossible that SOME |
179 // |handle[i]| will ever satisfy any of the signals in |signals[i]|. | 120 // |handle[i]| will ever satisfy any of the signals in |signals[i]|. |
180 MOJO_SYSTEM_EXPORT MojoResult | 121 MOJO_SYSTEM_EXPORT MojoResult |
181 MojoNewWaitMany(const MojoHandle* handles, | 122 MojoWaitMany(const MojoHandle* handles, |
182 const MojoHandleSignals* signals, | 123 const MojoHandleSignals* signals, |
183 uint32_t num_handles, | 124 uint32_t num_handles, |
184 MojoDeadline deadline, | 125 MojoDeadline deadline, |
185 uint32_t* result_index, // Optional out | 126 uint32_t* result_index, // Optional out |
186 struct MojoHandleSignalsState* signals_states); // Optional out | 127 struct MojoHandleSignalsState* signals_states); // Optional out |
187 | 128 |
188 #ifdef __cplusplus | 129 #ifdef __cplusplus |
189 } // extern "C" | 130 } // extern "C" |
190 #endif | 131 #endif |
191 | 132 |
192 #endif // MOJO_PUBLIC_C_SYSTEM_FUNCTIONS_H_ | 133 #endif // MOJO_PUBLIC_C_SYSTEM_FUNCTIONS_H_ |
OLD | NEW |