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 MOJO_SYSTEM_EXPORT MojoTimeTicks MojoGetTimeTicksNow(void); | 35 MOJO_SYSTEM_EXPORT MojoTimeTicks MojoGetTimeTicksNow(void); |
36 | 36 |
37 // Closes the given |handle|. | 37 // Closes the given |handle|. |
38 // | 38 // |
39 // Returns: | 39 // Returns: |
40 // |MOJO_RESULT_OK| on success. | 40 // |MOJO_RESULT_OK| on success. |
41 // |MOJO_RESULT_INVALID_ARGUMENT| if |handle| is not a valid handle. | 41 // |MOJO_RESULT_INVALID_ARGUMENT| if |handle| is not a valid handle. |
42 // | 42 // |
43 // Concurrent operations on |handle| may succeed (or fail as usual) if they | 43 // Concurrent operations on |handle| may succeed (or fail as usual) if they |
44 // happen before the close, be cancelled with result |MOJO_RESULT_CANCELLED| if | 44 // happen before the close, be cancelled with result |MOJO_RESULT_CANCELLED| if |
45 // they properly overlap (this is likely the case with |MojoWait()|, etc.), or | 45 // they properly overlap (this is likely the case with watchers), or fail with |
46 // fail with |MOJO_RESULT_INVALID_ARGUMENT| if they happen after. | 46 // |MOJO_RESULT_INVALID_ARGUMENT| if they happen after. |
47 MOJO_SYSTEM_EXPORT MojoResult MojoClose(MojoHandle handle); | 47 MOJO_SYSTEM_EXPORT MojoResult MojoClose(MojoHandle handle); |
48 | 48 |
49 // Queries the last known signals state of a handle. | 49 // Queries the last known signals state of a handle. |
50 // | 50 // |
51 // Note that no guarantees can be made about the accuracy of the returned | 51 // Note that no guarantees can be made about the accuracy of the returned |
52 // signals state by the time this returns, as other threads in the system may | 52 // signals state by the time this returns, as other threads in the system may |
53 // change the handle's state at any time. Use with appropriate discretion. | 53 // change the handle's state at any time. Use with appropriate discretion. |
54 // | 54 // |
55 // Returns: | 55 // Returns: |
56 // |MOJO_RESULT_OK| on success. |*signals_state| is populated with the | 56 // |MOJO_RESULT_OK| on success. |*signals_state| is populated with the |
57 // last known signals state of |handle|. | 57 // last known signals state of |handle|. |
58 // |MOJO_RESULT_INVALID_ARGUMENT| if |handle| is not a valid handle or | 58 // |MOJO_RESULT_INVALID_ARGUMENT| if |handle| is not a valid handle or |
59 // |signals_state| is null. | 59 // |signals_state| is null. |
60 MOJO_SYSTEM_EXPORT MojoResult | 60 MOJO_SYSTEM_EXPORT MojoResult |
61 MojoQueryHandleSignalsState(MojoHandle handle, | 61 MojoQueryHandleSignalsState(MojoHandle handle, |
62 struct MojoHandleSignalsState* signals_state); | 62 struct MojoHandleSignalsState* signals_state); |
63 | 63 |
64 // Waits on the given handle until one of the following happens: | |
65 // - A signal indicated by |signals| is satisfied. | |
66 // - It becomes known that no signal indicated by |signals| will ever be | |
67 // satisfied. (See the description of the |MOJO_RESULT_CANCELLED| and | |
68 // |MOJO_RESULT_FAILED_PRECONDITION| return values below.) | |
69 // - Until |deadline| has passed. | |
70 // | |
71 // If |deadline| is |MOJO_DEADLINE_INDEFINITE|, this will wait "forever" (until | |
72 // one of the other wait termination conditions is satisfied). If |deadline| is | |
73 // 0, this will return |MOJO_RESULT_DEADLINE_EXCEEDED| only if one of the other | |
74 // termination conditions (e.g., a signal is satisfied, or all signals are | |
75 // unsatisfiable) is not already satisfied. | |
76 // | |
77 // |signals_state| (optional): See documentation for |MojoHandleSignalsState|. | |
78 // | |
79 // Returns: | |
80 // |MOJO_RESULT_OK| if some signal in |signals| was satisfied (or is already | |
81 // satisfied). | |
82 // |MOJO_RESULT_CANCELLED| if |handle| was closed (necessarily from another | |
83 // thread) during the wait. | |
84 // |MOJO_RESULT_INVALID_ARGUMENT| if |handle| is not a valid handle (e.g., if | |
85 // it has already been closed). The |signals_state| value is unchanged. | |
86 // |MOJO_RESULT_DEADLINE_EXCEEDED| if the deadline has passed without any of | |
87 // the signals being satisfied. | |
88 // |MOJO_RESULT_FAILED_PRECONDITION| if it becomes known that none of the | |
89 // signals in |signals| can ever be satisfied (e.g., when waiting on one | |
90 // end of a message pipe and the other end is closed). | |
91 // | |
92 // If there are multiple waiters (on different threads, obviously) waiting on | |
93 // the same handle and signal, and that signal becomes satisfied, all waiters | |
94 // will be awoken. | |
95 MOJO_SYSTEM_EXPORT MojoResult | |
96 MojoWait(MojoHandle handle, | |
97 MojoHandleSignals signals, | |
98 MojoDeadline deadline, | |
99 struct MojoHandleSignalsState* signals_state); // Optional out. | |
100 | |
101 // Waits on |handles[0]|, ..., |handles[num_handles-1]| until: | |
102 // - (At least) one handle satisfies a signal indicated in its respective | |
103 // |signals[0]|, ..., |signals[num_handles-1]|. | |
104 // - It becomes known that no signal in some |signals[i]| will ever be | |
105 // satisfied. | |
106 // - |deadline| has passed. | |
107 // | |
108 // This means that |MojoWaitMany()| behaves as if |MojoWait()| were called on | |
109 // each handle/signals pair simultaneously, completing when the first | |
110 // |MojoWait()| would complete. | |
111 // | |
112 // See |MojoWait()| for more details about |deadline|. | |
113 // | |
114 // |result_index| (optional) is used to return the index of the handle that | |
115 // caused the call to return. For example, the index |i| (from 0 to | |
116 // |num_handles-1|) if |handle[i]| satisfies a signal from |signals[i]|. You | |
117 // must manually initialize this to a suitable sentinel value (e.g. -1) | |
118 // before you make this call because this value is not updated if there is | |
119 // no specific handle that causes the function to return. Pass null if you | |
120 // don't need this value to be returned. | |
121 // | |
122 // |signals_states| (optional) points to an array of size |num_handles| of | |
123 // MojoHandleSignalsState. See |MojoHandleSignalsState| for more details | |
124 // about the meaning of each array entry. This array is not an atomic | |
125 // snapshot. The array will be updated if the function does not return | |
126 // |MOJO_RESULT_INVALID_ARGUMENT| or |MOJO_RESULT_RESOURCE_EXHAUSTED|. | |
127 // | |
128 // Returns: | |
129 // |MOJO_RESULT_CANCELLED| if some |handle[i]| was closed (necessarily from | |
130 // another thread) during the wait. | |
131 // |MOJO_RESULT_RESOURCE_EXHAUSTED| if there are too many handles. The | |
132 // |signals_state| array is unchanged. | |
133 // |MOJO_RESULT_INVALID_ARGUMENT| if some |handle[i]| is not a valid handle | |
134 // (e.g., if it is zero or if it has already been closed). The | |
135 // |signals_state| array is unchanged. | |
136 // |MOJO_RESULT_DEADLINE_EXCEEDED| if the deadline has passed without any of | |
137 // handles satisfying any of its signals. | |
138 // |MOJO_RESULT_FAILED_PRECONDITION| if it is or becomes impossible that SOME | |
139 // |handle[i]| will ever satisfy any of the signals in |signals[i]|. | |
140 MOJO_SYSTEM_EXPORT MojoResult | |
141 MojoWaitMany(const MojoHandle* handles, | |
142 const MojoHandleSignals* signals, | |
143 uint32_t num_handles, | |
144 MojoDeadline deadline, | |
145 uint32_t* result_index, // Optional out | |
146 struct MojoHandleSignalsState* signals_states); // Optional out | |
147 | |
148 // Retrieves system properties. See the documentation for |MojoPropertyType| for | 64 // Retrieves system properties. See the documentation for |MojoPropertyType| for |
149 // supported property types and their corresponding output value type. | 65 // supported property types and their corresponding output value type. |
150 // | 66 // |
151 // Returns: | 67 // Returns: |
152 // |MOJO_RESULT_OK| on success. | 68 // |MOJO_RESULT_OK| on success. |
153 // |MOJO_RESULT_INVALID_ARGUMENT| if |type| is not recognized. In this case, | 69 // |MOJO_RESULT_INVALID_ARGUMENT| if |type| is not recognized. In this case, |
154 // |value| is untouched. | 70 // |value| is untouched. |
155 MOJO_SYSTEM_EXPORT MojoResult MojoGetProperty(MojoPropertyType type, | 71 MOJO_SYSTEM_EXPORT MojoResult MojoGetProperty(MojoPropertyType type, |
156 void* value); | 72 void* value); |
157 | 73 |
158 #ifdef __cplusplus | 74 #ifdef __cplusplus |
159 } // extern "C" | 75 } // extern "C" |
160 #endif | 76 #endif |
161 | 77 |
162 #endif // MOJO_PUBLIC_C_SYSTEM_FUNCTIONS_H_ | 78 #endif // MOJO_PUBLIC_C_SYSTEM_FUNCTIONS_H_ |
OLD | NEW |