OLD | NEW |
| (Empty) |
1 // Copyright 2016 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 functions for waiting on handles (directly). | |
6 // | |
7 // Note: This header should be compilable as C. | |
8 | |
9 #ifndef MOJO_PUBLIC_C_INCLUDE_MOJO_SYSTEM_WAIT_H_ | |
10 #define MOJO_PUBLIC_C_INCLUDE_MOJO_SYSTEM_WAIT_H_ | |
11 | |
12 #include <mojo/macros.h> | |
13 #include <mojo/result.h> | |
14 #include <mojo/system/handle.h> | |
15 #include <mojo/system/time.h> | |
16 | |
17 MOJO_BEGIN_EXTERN_C | |
18 | |
19 // |MojoWait()|: Waits on the given handle until one of the following happens: | |
20 // - A signal indicated by |signals| is satisfied. | |
21 // - It becomes known that no signal indicated by |signals| will ever be | |
22 // satisfied. (See the description of the |MOJO_RESULT_CANCELLED| and | |
23 // |MOJO_RESULT_FAILED_PRECONDITION| return values below.) | |
24 // - Until |deadline| has passed. | |
25 // | |
26 // If |deadline| is |MOJO_DEADLINE_INDEFINITE|, this will wait "forever" (until | |
27 // one of the other wait termination conditions is satisfied). If |deadline| is | |
28 // 0, this will return |MOJO_RESULT_DEADLINE_EXCEEDED| only if one of the other | |
29 // termination conditions (e.g., a signal is satisfied, or all signals are | |
30 // unsatisfiable) is not already satisfied. | |
31 // | |
32 // |signals_state| (optional): See documentation for |MojoHandleSignalsState|. | |
33 // | |
34 // Returns: | |
35 // |MOJO_RESULT_OK| if some signal in |signals| was satisfied (or is already | |
36 // satisfied). | |
37 // |MOJO_RESULT_CANCELLED| if |handle| was closed (necessarily from another | |
38 // thread) during the wait. | |
39 // |MOJO_RESULT_INVALID_ARGUMENT| if |handle| is not a valid handle (e.g., if | |
40 // it has already been closed). The |signals_state| value is unchanged. | |
41 // |MOJO_RESULT_DEADLINE_EXCEEDED| if the deadline has passed without any of | |
42 // the signals being satisfied. | |
43 // |MOJO_RESULT_FAILED_PRECONDITION| if it becomes known that none of the | |
44 // signals in |signals| can ever be satisfied (e.g., when waiting on one | |
45 // end of a message pipe and the other end is closed), at least not | |
46 // without performing some action on |handle| (see, e.g., |struct | |
47 // MojoDataPipeConsumerOptions|). | |
48 // |MOJO_RESULT_BUSY| if |handle| is currently in use in some transaction | |
49 // (that, e.g., may result in it being invalidated, such as being sent in | |
50 // a message). | |
51 // | |
52 // If there are multiple waiters (on different threads, obviously) waiting on | |
53 // the same handle and signal, and that signal becomes satisfied, all waiters | |
54 // will be awoken. | |
55 MojoResult MojoWait( | |
56 MojoHandle handle, // In. | |
57 MojoHandleSignals signals, // In. | |
58 MojoDeadline deadline, // In. | |
59 struct MojoHandleSignalsState* signals_state); // Optional out. | |
60 | |
61 // |MojoWaitMany()|: Waits on |handles[0]|, ..., |handles[num_handles-1]| until: | |
62 // - (At least) one handle satisfies a signal indicated in its respective | |
63 // |signals[0]|, ..., |signals[num_handles-1]|. | |
64 // - It becomes known that no signal in some |signals[i]| will ever be | |
65 // satisfied. | |
66 // - |deadline| has passed. | |
67 // | |
68 // This means that |MojoWaitMany()| behaves as if |MojoWait()| were called on | |
69 // each handle/signals pair simultaneously, completing when the first | |
70 // |MojoWait()| would complete. | |
71 // | |
72 // See |MojoWait()| for more details about |deadline|. | |
73 // | |
74 // Note that if |num_handles| is 0, this will wait until |deadline| has passed | |
75 // (possibly forever if it is |MOJO_DEADLINE_INDEFINITE|), and handles|, | |
76 // |signals|, |result_index|, and |signals_states| will all be ignored (so they | |
77 // may be null or invalid pointers). | |
78 // | |
79 // |result_index| (optional) is used to return the index of the handle that | |
80 // caused the call to return. For example, the index |i| (from 0 to | |
81 // |num_handles-1|) if |handle[i]| satisfies a signal from |signals[i]|. You | |
82 // must manually initialize this to a suitable sentinel value (e.g. -1) | |
83 // before you make this call because this value is not updated if there is | |
84 // no specific handle that causes the function to return. Pass null if you | |
85 // don't need this value to be returned. | |
86 // | |
87 // |signals_states| (optional) points to an array of size |num_handles| of | |
88 // MojoHandleSignalsState. See |MojoHandleSignalsState| for more details | |
89 // about the meaning of each array entry. This array is not an atomic | |
90 // snapshot. The array will be updated if the function does not return | |
91 // |MOJO_RESULT_INVALID_ARGUMENT| or |MOJO_RESULT_RESOURCE_EXHAUSTED|. | |
92 // | |
93 // Returns: | |
94 // |MOJO_RESULT_CANCELLED| if some |handle[i]| was closed (necessarily from | |
95 // another thread) during the wait. | |
96 // |MOJO_RESULT_RESOURCE_EXHAUSTED| if there are too many handles. The | |
97 // |signals_state| array is unchanged. | |
98 // |MOJO_RESULT_INVALID_ARGUMENT| if some |handle[i]| is not a valid handle | |
99 // (e.g., if it is zero or if it has already been closed). The | |
100 // |signals_state| array is unchanged. | |
101 // |MOJO_RESULT_DEADLINE_EXCEEDED| if the deadline has passed without any of | |
102 // handles satisfying any of its signals. | |
103 // |MOJO_RESULT_FAILED_PRECONDITION| if it is or becomes impossible that SOME | |
104 // |handle[i]| will ever satisfy any of the signals in |signals[i]|, at | |
105 // least not without some action on |handle[i]| (see, e.g., |struct | |
106 // MojoDataPipeConsumerOptions|). | |
107 // |MOJO_RESULT_BUSY| if some |handle[i]| is currently in use in some | |
108 // transaction (that, e.g., may result in it being invalidated, such as | |
109 // being sent in a message). | |
110 MojoResult MojoWaitMany(const MojoHandle* MOJO_RESTRICT handles, // In. | |
111 const MojoHandleSignals* MOJO_RESTRICT signals, // In. | |
112 uint32_t num_handles, // In. | |
113 MojoDeadline deadline, // In. | |
114 uint32_t* MOJO_RESTRICT result_index, // Optional out. | |
115 struct MojoHandleSignalsState* MOJO_RESTRICT | |
116 signals_states); // Optional out. | |
117 | |
118 MOJO_END_EXTERN_C | |
119 | |
120 #endif // MOJO_PUBLIC_C_INCLUDE_MOJO_SYSTEM_WAIT_H_ | |
OLD | NEW |