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 types and constants/macros common to different Mojo system 6 // APIs. 7 // 8 // Note: This header should be compilable as C. 9 10 #ifndef MOJO_PUBLIC_C_SYSTEM_TYPES_H_ 11 #define MOJO_PUBLIC_C_SYSTEM_TYPES_H_ 12 13 #include <stdint.h> 14 15 #include "mojo/public/c/system/macros.h" 16 17 // |MojoTimeTicks|: A time delta, in microseconds, the meaning of which is 18 // source-dependent. 19 20 typedef int64_t MojoTimeTicks; 21 22 // |MojoHandle|: Handles to Mojo objects. 23 // |MOJO_HANDLE_INVALID| - A value that is never a valid handle. 24 25 typedef uint32_t MojoHandle; 26 27 #ifdef __cplusplus 28 const MojoHandle MOJO_HANDLE_INVALID = 0; 29 #else 30 #define MOJO_HANDLE_INVALID ((MojoHandle)0) 31 #endif 32 33 // |MojoResult|: Result codes for Mojo operations. The only success code is zero 34 // (|MOJO_RESULT_OK|); all non-zero values should be considered as error/failure 35 // codes (even if the value is not recognized). 36 // |MOJO_RESULT_OK| - Not an error; returned on success. 37 // |MOJO_RESULT_CANCELLED| - Operation was cancelled, typically by the caller. 38 // |MOJO_RESULT_UNKNOWN| - Unknown error (e.g., if not enough information is 39 // available for a more specific error). 40 // |MOJO_RESULT_INVALID_ARGUMENT| - Caller specified an invalid argument. This 41 // differs from |MOJO_RESULT_FAILED_PRECONDITION| in that the former 42 // indicates arguments that are invalid regardless of the state of the 43 // system. 44 // |MOJO_RESULT_DEADLINE_EXCEEDED| - Deadline expired before the operation 45 // could complete. 46 // |MOJO_RESULT_NOT_FOUND| - Some requested entity was not found (i.e., does 47 // not exist). 48 // |MOJO_RESULT_ALREADY_EXISTS| - Some entity or condition that we attempted 49 // to create already exists. 50 // |MOJO_RESULT_PERMISSION_DENIED| - The caller does not have permission to 51 // for the operation (use |MOJO_RESULT_RESOURCE_EXHAUSTED| for rejections 52 // caused by exhausting some resource instead). 53 // |MOJO_RESULT_RESOURCE_EXHAUSTED| - Some resource required for the call 54 // (possibly some quota) has been exhausted. 55 // |MOJO_RESULT_FAILED_PRECONDITION| - The system is not in a state required 56 // for the operation (use this if the caller must do something to rectify 57 // the state before retrying). 58 // |MOJO_RESULT_ABORTED| - The operation was aborted by the system, possibly 59 // due to a concurrency issue (use this if the caller may retry at a 60 // higher level). 61 // |MOJO_RESULT_OUT_OF_RANGE| - The operation was attempted past the valid 62 // range. Unlike |MOJO_RESULT_INVALID_ARGUMENT|, this indicates that the 63 // operation may be/become valid depending on the system state. (This 64 // error is similar to |MOJO_RESULT_FAILED_PRECONDITION|, but is more 65 // specific.) 66 // |MOJO_RESULT_UNIMPLEMENTED| - The operation is not implemented, supported, 67 // or enabled. 68 // |MOJO_RESULT_INTERNAL| - Internal error: this should never happen and 69 // indicates that some invariant expected by the system has been broken. 70 // |MOJO_RESULT_UNAVAILABLE| - The operation is (temporarily) currently 71 // unavailable. The caller may simply retry the operation (possibly with a 72 // backoff). 73 // |MOJO_RESULT_DATA_LOSS| - Unrecoverable data loss or corruption. 74 // |MOJO_RESULT_BUSY| - One of the resources involved is currently being used 75 // (possibly on another thread) in a way that prevents the current 76 // operation from proceeding, e.g., if the other operation may result in 77 // the resource being invalidated. 78 // |MOJO_RESULT_SHOULD_WAIT| - The request cannot currently be completed 79 // (e.g., if the data requested is not yet available). The caller should 80 // wait for it to be feasible using a trap. 81 // 82 // The codes from |MOJO_RESULT_OK| to |MOJO_RESULT_DATA_LOSS| come from 83 // Google3's canonical error codes. 84 85 typedef uint32_t MojoResult; 86 87 #ifdef __cplusplus 88 const MojoResult MOJO_RESULT_OK = 0; 89 const MojoResult MOJO_RESULT_CANCELLED = 1; 90 const MojoResult MOJO_RESULT_UNKNOWN = 2; 91 const MojoResult MOJO_RESULT_INVALID_ARGUMENT = 3; 92 const MojoResult MOJO_RESULT_DEADLINE_EXCEEDED = 4; 93 const MojoResult MOJO_RESULT_NOT_FOUND = 5; 94 const MojoResult MOJO_RESULT_ALREADY_EXISTS = 6; 95 const MojoResult MOJO_RESULT_PERMISSION_DENIED = 7; 96 const MojoResult MOJO_RESULT_RESOURCE_EXHAUSTED = 8; 97 const MojoResult MOJO_RESULT_FAILED_PRECONDITION = 9; 98 const MojoResult MOJO_RESULT_ABORTED = 10; 99 const MojoResult MOJO_RESULT_OUT_OF_RANGE = 11; 100 const MojoResult MOJO_RESULT_UNIMPLEMENTED = 12; 101 const MojoResult MOJO_RESULT_INTERNAL = 13; 102 const MojoResult MOJO_RESULT_UNAVAILABLE = 14; 103 const MojoResult MOJO_RESULT_DATA_LOSS = 15; 104 const MojoResult MOJO_RESULT_BUSY = 16; 105 const MojoResult MOJO_RESULT_SHOULD_WAIT = 17; 106 #else 107 #define MOJO_RESULT_OK ((MojoResult)0) 108 #define MOJO_RESULT_CANCELLED ((MojoResult)1) 109 #define MOJO_RESULT_UNKNOWN ((MojoResult)2) 110 #define MOJO_RESULT_INVALID_ARGUMENT ((MojoResult)3) 111 #define MOJO_RESULT_DEADLINE_EXCEEDED ((MojoResult)4) 112 #define MOJO_RESULT_NOT_FOUND ((MojoResult)5) 113 #define MOJO_RESULT_ALREADY_EXISTS ((MojoResult)6) 114 #define MOJO_RESULT_PERMISSION_DENIED ((MojoResult)7) 115 #define MOJO_RESULT_RESOURCE_EXHAUSTED ((MojoResult)8) 116 #define MOJO_RESULT_FAILED_PRECONDITION ((MojoResult)9) 117 #define MOJO_RESULT_ABORTED ((MojoResult)10) 118 #define MOJO_RESULT_OUT_OF_RANGE ((MojoResult)11) 119 #define MOJO_RESULT_UNIMPLEMENTED ((MojoResult)12) 120 #define MOJO_RESULT_INTERNAL ((MojoResult)13) 121 #define MOJO_RESULT_UNAVAILABLE ((MojoResult)14) 122 #define MOJO_RESULT_DATA_LOSS ((MojoResult)15) 123 #define MOJO_RESULT_BUSY ((MojoResult)16) 124 #define MOJO_RESULT_SHOULD_WAIT ((MojoResult)17) 125 #endif 126 127 // |MojoDeadline|: Used to specify deadlines (timeouts), in microseconds (except 128 // for |MOJO_DEADLINE_INDEFINITE|). 129 // |MOJO_DEADLINE_INDEFINITE| - Used to indicate "forever". 130 131 typedef uint64_t MojoDeadline; 132 133 #ifdef __cplusplus 134 const MojoDeadline MOJO_DEADLINE_INDEFINITE = static_cast<MojoDeadline>(-1); 135 #else 136 #define MOJO_DEADLINE_INDEFINITE ((MojoDeadline)-1) 137 #endif 138 139 // Flags passed to |MojoInitialize()| via |MojoInitializeOptions|. 140 typedef uint32_t MojoInitializeFlags; 141 142 // No flags. 143 #define MOJO_INITIALIZE_FLAG_NONE ((MojoInitializeFlags)0) 144 145 // Options passed to |MojoInitialize()|. 146 struct MOJO_ALIGNAS(8) MojoInitializeOptions { 147 // The size of this structure, used for versioning. 148 uint32_t struct_size; 149 150 // See |MojoInitializeFlags|. 151 MojoInitializeFlags flags; 152 153 // Address and length of the UTF8-encoded path of a mojo_core shared library 154 // to load. If the |mojo_core_path| is null then |mojo_core_path_length| is 155 // ignored and Mojo will fall back first onto the |MOJO_CORE_LIBRARY_PATH| 156 // environment variable, and then onto the current working directory. 157 MOJO_POINTER_FIELD(const char*, mojo_core_path); 158 uint32_t mojo_core_path_length; 159 }; 160 MOJO_STATIC_ASSERT(sizeof(MojoInitializeOptions) == 24, 161 "MojoInitializeOptions has wrong size"); 162 163 // |MojoHandleSignals|: Used to specify signals that can be watched for on a 164 // handle (and which can be triggered), e.g., the ability to read or write to 165 // the handle. 166 // |MOJO_HANDLE_SIGNAL_NONE| - No flags. A registered watch will always fail 167 // to arm with |MOJO_RESULT_FAILED_PRECONDITION| when watching for this. 168 // |MOJO_HANDLE_SIGNAL_READABLE| - Can read (e.g., a message) from the handle. 169 // |MOJO_HANDLE_SIGNAL_WRITABLE| - Can write (e.g., a message) to the handle. 170 // |MOJO_HANDLE_SIGNAL_PEER_CLOSED| - The peer handle is closed. 171 // |MOJO_HANDLE_SIGNAL_NEW_DATA_READABLE| - Can read data from a data pipe 172 // consumer handle (implying MOJO_HANDLE_SIGNAL_READABLE is also set), 173 // AND there is some nonzero quantity of new data available on the pipe 174 // since the last |MojoReadData()| or |MojoBeginReadData()| call on the 175 // handle. 176 // |MOJO_HANDLE_SIGNAL_PEER_REMOTE| - The peer handle exists in a remote 177 // execution context (e.g. in another process.) Note that this signal is 178 // maintained with best effort but may at any time be slightly out of sync 179 // with the actual location of the peer handle. 180 // |MOJO_HANDLE_SIGNAL_QUOTA_EXCEEDED| - One or more quotas set on the handle 181 // is currently exceeded. 182 183 typedef uint32_t MojoHandleSignals; 184 185 #ifdef __cplusplus 186 const MojoHandleSignals MOJO_HANDLE_SIGNAL_NONE = 0; 187 const MojoHandleSignals MOJO_HANDLE_SIGNAL_READABLE = 1 << 0; 188 const MojoHandleSignals MOJO_HANDLE_SIGNAL_WRITABLE = 1 << 1; 189 const MojoHandleSignals MOJO_HANDLE_SIGNAL_PEER_CLOSED = 1 << 2; 190 const MojoHandleSignals MOJO_HANDLE_SIGNAL_NEW_DATA_READABLE = 1 << 3; 191 const MojoHandleSignals MOJO_HANDLE_SIGNAL_PEER_REMOTE = 1 << 4; 192 const MojoHandleSignals MOJO_HANDLE_SIGNAL_QUOTA_EXCEEDED = 1 << 5; 193 #else 194 #define MOJO_HANDLE_SIGNAL_NONE ((MojoHandleSignals)0) 195 #define MOJO_HANDLE_SIGNAL_READABLE ((MojoHandleSignals)1 << 0) 196 #define MOJO_HANDLE_SIGNAL_WRITABLE ((MojoHandleSignals)1 << 1) 197 #define MOJO_HANDLE_SIGNAL_PEER_CLOSED ((MojoHandleSignals)1 << 2) 198 #define MOJO_HANDLE_SIGNAL_NEW_DATA_READABLE ((MojoHandleSignals)1 << 3); 199 #define MOJO_HANDLE_SIGNAL_PEER_REMOTE ((MojoHandleSignals)1 << 4); 200 #define MOJO_HANDLE_SIGNAL_QUOTA_EXCEEDED ((MojoHandleSignals)1 << 5); 201 #endif 202 203 // |MojoHandleSignalsState|: Returned by watch notification callbacks and 204 // |MojoQueryHandleSignalsState| functions to indicate the signaling state of 205 // handles. Members are as follows: 206 // - |satisfied signals|: Bitmask of signals that were satisfied at some time 207 // before the call returned. 208 // - |satisfiable signals|: These are the signals that are possible to 209 // satisfy. For example, if the return value was 210 // |MOJO_RESULT_FAILED_PRECONDITION|, you can use this field to 211 // determine which, if any, of the signals can still be satisfied. 212 // Note: This struct is not extensible (and only has 32-bit quantities), so it's 213 // 32-bit-aligned. 214 MOJO_STATIC_ASSERT(MOJO_ALIGNOF(int32_t) == 4, "int32_t has weird alignment"); 215 struct MOJO_ALIGNAS(4) MojoHandleSignalsState { 216 MojoHandleSignals satisfied_signals; 217 MojoHandleSignals satisfiable_signals; 218 }; 219 MOJO_STATIC_ASSERT(sizeof(MojoHandleSignalsState) == 8, 220 "MojoHandleSignalsState has wrong size"); 221 222 // TODO(https://crbug.com/819046): Remove these aliases. 223 #define MOJO_WATCH_CONDITION_SATISFIED MOJO_TRIGGER_CONDITION_SIGNALS_SATISFIED 224 #define MOJO_WATCH_CONDITION_NOT_SATISFIED \ 225 MOJO_TRIGGER_CONDITION_SIGNALS_UNSATISFIED 226 227 #endif // MOJO_PUBLIC_C_SYSTEM_TYPES_H_ 228