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 3 // found in the LICENSE file. 4 5 // This file contains basic functions common to different Mojo system APIs. 6 // 7 // Note: This header should be compilable as C. 8 9 #ifndef MOJO_PUBLIC_C_SYSTEM_FUNCTIONS_H_ 10 #define MOJO_PUBLIC_C_SYSTEM_FUNCTIONS_H_ 11 12 #include <stddef.h> 13 #include <stdint.h> 14 15 #include "mojo/public/c/system/system_export.h" 16 #include "mojo/public/c/system/types.h" 17 18 #ifdef __cplusplus 19 extern "C" { 20 #endif 21 22 // A callback used to notify watchers registered via |MojoWatch()|. Called when 23 // some watched signals are satisfied or become unsatisfiable. See the 24 // documentation for |MojoWatch()| for more details. 25 typedef void (*MojoWatchCallback)(uintptr_t context, 26 MojoResult result, 27 struct MojoHandleSignalsState signals_state, 28 MojoWatchNotificationFlags flags); 29 30 // Note: Pointer parameters that are labelled "optional" may be null (at least 31 // under some circumstances). Non-const pointer parameters are also labeled 32 // "in", "out", or "in/out", to indicate how they are used. (Note that how/if 33 // such a parameter is used may depend on other parameters or the requested 34 // operation's success/failure. E.g., a separate |flags| parameter may control 35 // whether a given "in/out" parameter is used for input, output, or both.) 36 37 // Returns the time, in microseconds, since some undefined point in the past. 38 // The values are only meaningful relative to other values that were obtained 39 // from the same device without an intervening system restart. Such values are 40 // guaranteed to be monotonically non-decreasing with the passage of real time. 41 // Although the units are microseconds, the resolution of the clock may vary and 42 // is typically in the range of ~1-15 ms. 43 MOJO_SYSTEM_EXPORT MojoTimeTicks MojoGetTimeTicksNow(void); 44 45 // Closes the given |handle|. 46 // 47 // Returns: 48 // |MOJO_RESULT_OK| on success. 49 // |MOJO_RESULT_INVALID_ARGUMENT| if |handle| is not a valid handle. 50 // 51 // Concurrent operations on |handle| may succeed (or fail as usual) if they 52 // happen before the close, be cancelled with result |MOJO_RESULT_CANCELLED| if 53 // they properly overlap (this is likely the case with |MojoWait()|, etc.), or 54 // fail with |MOJO_RESULT_INVALID_ARGUMENT| if they happen after. 55 MOJO_SYSTEM_EXPORT MojoResult MojoClose(MojoHandle handle); 56 57 // Waits on the given handle until one of the following happens: 58 // - A signal indicated by |signals| is satisfied. 59 // - It becomes known that no signal indicated by |signals| will ever be 60 // satisfied. (See the description of the |MOJO_RESULT_CANCELLED| and 61 // |MOJO_RESULT_FAILED_PRECONDITION| return values below.) 62 // - Until |deadline| has passed. 63 // 64 // If |deadline| is |MOJO_DEADLINE_INDEFINITE|, this will wait "forever" (until 65 // one of the other wait termination conditions is satisfied). If |deadline| is 66 // 0, this will return |MOJO_RESULT_DEADLINE_EXCEEDED| only if one of the other 67 // termination conditions (e.g., a signal is satisfied, or all signals are 68 // unsatisfiable) is not already satisfied. 69 // 70 // |signals_state| (optional): See documentation for |MojoHandleSignalsState|. 71 // 72 // Returns: 73 // |MOJO_RESULT_OK| if some signal in |signals| was satisfied (or is already 74 // satisfied). 75 // |MOJO_RESULT_CANCELLED| if |handle| was closed (necessarily from another 76 // thread) during the wait. 77 // |MOJO_RESULT_INVALID_ARGUMENT| if |handle| is not a valid handle (e.g., if 78 // it has already been closed). The |signals_state| value is unchanged. 79 // |MOJO_RESULT_DEADLINE_EXCEEDED| if the deadline has passed without any of 80 // the signals being satisfied. 81 // |MOJO_RESULT_FAILED_PRECONDITION| if it becomes known that none of the 82 // signals in |signals| can ever be satisfied (e.g., when waiting on one 83 // end of a message pipe and the other end is closed). 84 // 85 // If there are multiple waiters (on different threads, obviously) waiting on 86 // the same handle and signal, and that signal becomes satisfied, all waiters 87 // will be awoken. 88 MOJO_SYSTEM_EXPORT MojoResult 89 MojoWait(MojoHandle handle, 90 MojoHandleSignals signals, 91 MojoDeadline deadline, 92 struct MojoHandleSignalsState* signals_state); // Optional out. 93 94 // Waits on |handles[0]|, ..., |handles[num_handles-1]| until: 95 // - (At least) one handle satisfies a signal indicated in its respective 96 // |signals[0]|, ..., |signals[num_handles-1]|. 97 // - It becomes known that no signal in some |signals[i]| will ever be 98 // satisfied. 99 // - |deadline| has passed. 100 // 101 // This means that |MojoWaitMany()| behaves as if |MojoWait()| were called on 102 // each handle/signals pair simultaneously, completing when the first 103 // |MojoWait()| would complete. 104 // 105 // See |MojoWait()| for more details about |deadline|. 106 // 107 // |result_index| (optional) is used to return the index of the handle that 108 // caused the call to return. For example, the index |i| (from 0 to 109 // |num_handles-1|) if |handle[i]| satisfies a signal from |signals[i]|. You 110 // must manually initialize this to a suitable sentinel value (e.g. -1) 111 // before you make this call because this value is not updated if there is 112 // no specific handle that causes the function to return. Pass null if you 113 // don't need this value to be returned. 114 // 115 // |signals_states| (optional) points to an array of size |num_handles| of 116 // MojoHandleSignalsState. See |MojoHandleSignalsState| for more details 117 // about the meaning of each array entry. This array is not an atomic 118 // snapshot. The array will be updated if the function does not return 119 // |MOJO_RESULT_INVALID_ARGUMENT| or |MOJO_RESULT_RESOURCE_EXHAUSTED|. 120 // 121 // Returns: 122 // |MOJO_RESULT_CANCELLED| if some |handle[i]| was closed (necessarily from 123 // another thread) during the wait. 124 // |MOJO_RESULT_RESOURCE_EXHAUSTED| if there are too many handles. The 125 // |signals_state| array is unchanged. 126 // |MOJO_RESULT_INVALID_ARGUMENT| if some |handle[i]| is not a valid handle 127 // (e.g., if it is zero or if it has already been closed). The 128 // |signals_state| array is unchanged. 129 // |MOJO_RESULT_DEADLINE_EXCEEDED| if the deadline has passed without any of 130 // handles satisfying any of its signals. 131 // |MOJO_RESULT_FAILED_PRECONDITION| if it is or becomes impossible that SOME 132 // |handle[i]| will ever satisfy any of the signals in |signals[i]|. 133 MOJO_SYSTEM_EXPORT MojoResult 134 MojoWaitMany(const MojoHandle* handles, 135 const MojoHandleSignals* signals, 136 uint32_t num_handles, 137 MojoDeadline deadline, 138 uint32_t* result_index, // Optional out 139 struct MojoHandleSignalsState* signals_states); // Optional out 140 141 // Watches the given handle for one of the following events to happen: 142 // - A signal indicated by |signals| is satisfied. 143 // - It becomes known that no signal indicated by |signals| will ever be 144 // satisfied. (See the description of the |MOJO_RESULT_CANCELLED| and 145 // |MOJO_RESULT_FAILED_PRECONDITION| return values below.) 146 // - The handle is closed. 147 // 148 // |handle|: The handle to watch. Must be an open message pipe or data pipe 149 // handle. 150 // |signals|: The signals to watch for. 151 // |callback|: A function to be called any time one of the above events happens. 152 // The function must be safe to call from any thread at any time. 153 // |context|: User-provided context passed to |callback| when called. |context| 154 // is used to uniquely identify a registered watch and can be used to cancel 155 // the watch later using |MojoCancelWatch()|. 156 // 157 // Returns: 158 // |MOJO_RESULT_OK| if the watch has been successfully registered. Note that 159 // if the signals are already satisfied this may synchronously invoke 160 // |callback| before returning. 161 // |MOJO_RESULT_CANCELLED| if the watch was cancelled. In this case it is not 162 // necessary to explicitly call |MojoCancelWatch()|, and in fact it may be 163 // an error to do so as the handle may have been closed. 164 // |MOJO_RESULT_INVALID_ARGUMENT| if |handle| is not an open message pipe 165 // handle. 166 // |MOJO_RESULT_FAILED_PRECONDITION| if it is already known that |signals| can 167 // never be satisfied. 168 // |MOJO_RESULT_ALREADY_EXISTS| if there is already a watch registered for 169 // the same combination of |handle| and |context|. 170 // 171 // Callback result codes: 172 // The callback may be called at any time on any thread with one of the 173 // following result codes to indicate various events: 174 // 175 // |MOJO_RESULT_OK| indicates that some signal in |signals| has been 176 // satisfied. 177 // |MOJO_RESULT_FAILED_PRECONDITION| indicates that no signals in |signals| 178 // can ever be satisfied again. 179 // |MOJO_RESULT_CANCELLED| indicates that the handle has been closed. In this 180 // case the watch is implicitly cancelled and there is no need to call 181 // |MojoCancelWatch()|. 182 MOJO_SYSTEM_EXPORT MojoResult 183 MojoWatch(MojoHandle handle, 184 MojoHandleSignals signals, 185 MojoWatchCallback callback, 186 uintptr_t context); 187 188 // Cancels a handle watch corresponding to some prior call to |MojoWatch()|. 189 // 190 // NOTE: If the watch callback corresponding to |context| is currently running 191 // this will block until the callback completes execution. It is therefore 192 // illegal to call |MojoCancelWatch()| on a given |handle| and |context| from 193 // within the associated callback itself, as this will always deadlock. 194 // 195 // After |MojoCancelWatch()| function returns, the watch's associated callback 196 // will NEVER be called again by Mojo. 197 // 198 // |context|: The same user-provided context given to some prior call to 199 // |MojoWatch()|. Only the watch corresponding to this context will be 200 // cancelled. 201 // 202 // Returns: 203 // |MOJO_RESULT_OK| if the watch corresponding to |context| was cancelled. 204 // |MOJO_RESULT_INVALID_ARGUMENT| if no watch was registered with |context| 205 // for the given |handle|, or if |handle| is invalid. 206 MOJO_SYSTEM_EXPORT MojoResult 207 MojoCancelWatch(MojoHandle handle, uintptr_t context); 208 209 // Retrieves system properties. See the documentation for |MojoPropertyType| for 210 // supported property types and their corresponding output value type. 211 // 212 // Returns: 213 // |MOJO_RESULT_OK| on success. 214 // |MOJO_RESULT_INVALID_ARGUMENT| if |type| is not recognized. In this case, 215 // |value| is untouched. 216 MOJO_SYSTEM_EXPORT MojoResult MojoGetProperty(MojoPropertyType type, 217 void* value); 218 219 #ifdef __cplusplus 220 } // extern "C" 221 #endif 222 223 #endif // MOJO_PUBLIC_C_SYSTEM_FUNCTIONS_H_ 224
