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