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 // TODO(vtl): Notes: Use of undefined flags will lead to undefined behavior 18 // (typically they'll be ignored), not necessarily an error. 19 20 // |MojoTimeTicks|: A time delta, in microseconds, the meaning of which is 21 // source-dependent. 22 23 typedef int64_t MojoTimeTicks; 24 25 // |MojoHandle|: Handles to Mojo objects. 26 // |MOJO_HANDLE_INVALID| - A value that is never a valid handle. 27 28 typedef uint32_t MojoHandle; 29 30 #ifdef __cplusplus 31 const MojoHandle MOJO_HANDLE_INVALID = 0; 32 #else 33 #define MOJO_HANDLE_INVALID ((MojoHandle)0) 34 #endif 35 36 // |MojoResult|: Result codes for Mojo operations. The only success code is zero 37 // (|MOJO_RESULT_OK|); all non-zero values should be considered as error/failure 38 // codes (even if the value is not recognized). 39 // |MOJO_RESULT_OK| - Not an error; returned on success. 40 // |MOJO_RESULT_CANCELLED| - Operation was cancelled, typically by the caller. 41 // |MOJO_RESULT_UNKNOWN| - Unknown error (e.g., if not enough information is 42 // available for a more specific error). 43 // |MOJO_RESULT_INVALID_ARGUMENT| - Caller specified an invalid argument. This 44 // differs from |MOJO_RESULT_FAILED_PRECONDITION| in that the former 45 // indicates arguments that are invalid regardless of the state of the 46 // system. 47 // |MOJO_RESULT_DEADLINE_EXCEEDED| - Deadline expired before the operation 48 // could complete. 49 // |MOJO_RESULT_NOT_FOUND| - Some requested entity was not found (i.e., does 50 // not exist). 51 // |MOJO_RESULT_ALREADY_EXISTS| - Some entity or condition that we attempted 52 // to create already exists. 53 // |MOJO_RESULT_PERMISSION_DENIED| - The caller does not have permission to 54 // for the operation (use |MOJO_RESULT_RESOURCE_EXHAUSTED| for rejections 55 // caused by exhausting some resource instead). 56 // |MOJO_RESULT_RESOURCE_EXHAUSTED| - Some resource required for the call 57 // (possibly some quota) has been exhausted. 58 // |MOJO_RESULT_FAILED_PRECONDITION| - The system is not in a state required 59 // for the operation (use this if the caller must do something to rectify 60 // the state before retrying). 61 // |MOJO_RESULT_ABORTED| - The operation was aborted by the system, possibly 62 // due to a concurrency issue (use this if the caller may retry at a 63 // higher level). 64 // |MOJO_RESULT_OUT_OF_RANGE| - The operation was attempted past the valid 65 // range. Unlike |MOJO_RESULT_INVALID_ARGUMENT|, this indicates that the 66 // operation may be/become valid depending on the system state. (This 67 // error is similar to |MOJO_RESULT_FAILED_PRECONDITION|, but is more 68 // specific.) 69 // |MOJO_RESULT_UNIMPLEMENTED| - The operation is not implemented, supported, 70 // or enabled. 71 // |MOJO_RESULT_INTERNAL| - Internal error: this should never happen and 72 // indicates that some invariant expected by the system has been broken. 73 // |MOJO_RESULT_UNAVAILABLE| - The operation is (temporarily) currently 74 // unavailable. The caller may simply retry the operation (possibly with a 75 // backoff). 76 // |MOJO_RESULT_DATA_LOSS| - Unrecoverable data loss or corruption. 77 // |MOJO_RESULT_BUSY| - One of the resources involved is currently being used 78 // (possibly on another thread) in a way that prevents the current 79 // operation from proceeding, e.g., if the other operation may result in 80 // the resource being invalidated. 81 // |MOJO_RESULT_SHOULD_WAIT| - The request cannot currently be completed 82 // (e.g., if the data requested is not yet available). The caller should 83 // wait for it to be feasible using |MojoWait()| or |MojoWaitMany()|. 84 // 85 // The codes from |MOJO_RESULT_OK| to |MOJO_RESULT_DATA_LOSS| come from 86 // Google3's canonical error codes. 87 // 88 // TODO(vtl): Add a |MOJO_RESULT_UNSATISFIABLE|? 89 90 typedef uint32_t MojoResult; 91 92 #ifdef __cplusplus 93 const MojoResult MOJO_RESULT_OK = 0; 94 const MojoResult MOJO_RESULT_CANCELLED = 1; 95 const MojoResult MOJO_RESULT_UNKNOWN = 2; 96 const MojoResult MOJO_RESULT_INVALID_ARGUMENT = 3; 97 const MojoResult MOJO_RESULT_DEADLINE_EXCEEDED = 4; 98 const MojoResult MOJO_RESULT_NOT_FOUND = 5; 99 const MojoResult MOJO_RESULT_ALREADY_EXISTS = 6; 100 const MojoResult MOJO_RESULT_PERMISSION_DENIED = 7; 101 const MojoResult MOJO_RESULT_RESOURCE_EXHAUSTED = 8; 102 const MojoResult MOJO_RESULT_FAILED_PRECONDITION = 9; 103 const MojoResult MOJO_RESULT_ABORTED = 10; 104 const MojoResult MOJO_RESULT_OUT_OF_RANGE = 11; 105 const MojoResult MOJO_RESULT_UNIMPLEMENTED = 12; 106 const MojoResult MOJO_RESULT_INTERNAL = 13; 107 const MojoResult MOJO_RESULT_UNAVAILABLE = 14; 108 const MojoResult MOJO_RESULT_DATA_LOSS = 15; 109 const MojoResult MOJO_RESULT_BUSY = 16; 110 const MojoResult MOJO_RESULT_SHOULD_WAIT = 17; 111 #else 112 #define MOJO_RESULT_OK ((MojoResult)0) 113 #define MOJO_RESULT_CANCELLED ((MojoResult)1) 114 #define MOJO_RESULT_UNKNOWN ((MojoResult)2) 115 #define MOJO_RESULT_INVALID_ARGUMENT ((MojoResult)3) 116 #define MOJO_RESULT_DEADLINE_EXCEEDED ((MojoResult)4) 117 #define MOJO_RESULT_NOT_FOUND ((MojoResult)5) 118 #define MOJO_RESULT_ALREADY_EXISTS ((MojoResult)6) 119 #define MOJO_RESULT_PERMISSION_DENIED ((MojoResult)7) 120 #define MOJO_RESULT_RESOURCE_EXHAUSTED ((MojoResult)8) 121 #define MOJO_RESULT_FAILED_PRECONDITION ((MojoResult)9) 122 #define MOJO_RESULT_ABORTED ((MojoResult)10) 123 #define MOJO_RESULT_OUT_OF_RANGE ((MojoResult)11) 124 #define MOJO_RESULT_UNIMPLEMENTED ((MojoResult)12) 125 #define MOJO_RESULT_INTERNAL ((MojoResult)13) 126 #define MOJO_RESULT_UNAVAILABLE ((MojoResult)14) 127 #define MOJO_RESULT_DATA_LOSS ((MojoResult)15) 128 #define MOJO_RESULT_BUSY ((MojoResult)16) 129 #define MOJO_RESULT_SHOULD_WAIT ((MojoResult)17) 130 #endif 131 132 // |MojoDeadline|: Used to specify deadlines (timeouts), in microseconds (except 133 // for |MOJO_DEADLINE_INDEFINITE|). 134 // |MOJO_DEADLINE_INDEFINITE| - Used to indicate "forever". 135 136 typedef uint64_t MojoDeadline; 137 138 #ifdef __cplusplus 139 const MojoDeadline MOJO_DEADLINE_INDEFINITE = static_cast<MojoDeadline>(-1); 140 #else 141 #define MOJO_DEADLINE_INDEFINITE ((MojoDeadline) - 1) 142 #endif 143 144 // |MojoHandleSignals|: Used to specify signals that can be waited on for a 145 // handle (and which can be triggered), e.g., the ability to read or write to 146 // the handle. 147 // |MOJO_HANDLE_SIGNAL_NONE| - No flags. |MojoWait()|, etc. will return 148 // |MOJO_RESULT_FAILED_PRECONDITION| if you attempt to wait on this. 149 // |MOJO_HANDLE_SIGNAL_READABLE| - Can read (e.g., a message) from the handle. 150 // |MOJO_HANDLE_SIGNAL_WRITABLE| - Can write (e.g., a message) to the handle. 151 // |MOJO_HANDLE_SIGNAL_PEER_CLOSED| - The peer handle is closed. 152 // |MOJO_HANDLE_SIGNAL_NEW_DATA_READABLE| - Can read data from a data pipe 153 // consumer handle (implying MOJO_HANDLE_SIGNAL_READABLE is also set), 154 // AND there is some nonzero quantity of new data available on the pipe 155 // since the last |MojoReadData()| or |MojoBeginReadData()| call on the 156 // handle. 157 158 typedef uint32_t MojoHandleSignals; 159 160 #ifdef __cplusplus 161 const MojoHandleSignals MOJO_HANDLE_SIGNAL_NONE = 0; 162 const MojoHandleSignals MOJO_HANDLE_SIGNAL_READABLE = 1 << 0; 163 const MojoHandleSignals MOJO_HANDLE_SIGNAL_WRITABLE = 1 << 1; 164 const MojoHandleSignals MOJO_HANDLE_SIGNAL_PEER_CLOSED = 1 << 2; 165 const MojoHandleSignals MOJO_HANDLE_SIGNAL_NEW_DATA_READABLE = 1 << 3; 166 #else 167 #define MOJO_HANDLE_SIGNAL_NONE ((MojoHandleSignals)0) 168 #define MOJO_HANDLE_SIGNAL_READABLE ((MojoHandleSignals)1 << 0) 169 #define MOJO_HANDLE_SIGNAL_WRITABLE ((MojoHandleSignals)1 << 1) 170 #define MOJO_HANDLE_SIGNAL_PEER_CLOSED ((MojoHandleSignals)1 << 2) 171 #define MOJO_HANDLE_SIGNAL_NEW_DATA_READABLE ((MojoHandleSignals)1 << 3); 172 #endif 173 174 // |MojoHandleSignalsState|: Returned by wait functions to indicate the 175 // signaling state of handles. Members are as follows: 176 // - |satisfied signals|: Bitmask of signals that were satisfied at some time 177 // before the call returned. 178 // - |satisfiable signals|: These are the signals that are possible to 179 // satisfy. For example, if the return value was 180 // |MOJO_RESULT_FAILED_PRECONDITION|, you can use this field to 181 // determine which, if any, of the signals can still be satisfied. 182 // Note: This struct is not extensible (and only has 32-bit quantities), so it's 183 // 32-bit-aligned. 184 MOJO_STATIC_ASSERT(MOJO_ALIGNOF(int32_t) == 4, "int32_t has weird alignment"); 185 struct MOJO_ALIGNAS(4) MojoHandleSignalsState { 186 MojoHandleSignals satisfied_signals; 187 MojoHandleSignals satisfiable_signals; 188 }; 189 MOJO_STATIC_ASSERT(sizeof(MojoHandleSignalsState) == 8, 190 "MojoHandleSignalsState has wrong size"); 191 192 // |MojoWatchNotificationFlags|: Passed to a callback invoked as a result of 193 // signals being raised on a handle watched by |MojoWatch()|. May take the 194 // following values: 195 // |MOJO_WATCH_NOTIFICATION_FLAG_FROM_SYSTEM| - The callback is being invoked 196 // as a result of a system-level event rather than a direct API call from 197 // user code. This may be used as an indication that user code is safe to 198 // call without fear of reentry. 199 200 typedef uint32_t MojoWatchNotificationFlags; 201 202 #ifdef __cplusplus 203 const MojoWatchNotificationFlags MOJO_WATCH_NOTIFICATION_FLAG_NONE = 0; 204 const MojoWatchNotificationFlags MOJO_WATCH_NOTIFICATION_FLAG_FROM_SYSTEM = 205 1 << 0; 206 #else 207 #define MOJO_WATCH_NOTIFICATION_FLAG_NONE ((MojoWatchNotificationFlags)0) 208 #define MOJO_WATCH_NOTIFICATION_FLAG_FROM_SYSTEM \ 209 ((MojoWatchNotificationFlags)1 << 0); 210 #endif 211 212 // |MojoPropertyType|: Property types that can be passed to |MojoGetProperty()| 213 // to retrieve system properties. May take the following values: 214 // |MOJO_PROPERTY_TYPE_SYNC_CALL_ALLOWED| - Whether making synchronous calls 215 // (i.e., blocking to wait for a response to an outbound message) is 216 // allowed. The property value is of boolean type. If the value is true, 217 // users should refrain from making sync calls. 218 typedef uint32_t MojoPropertyType; 219 220 #ifdef __cplusplus 221 const MojoPropertyType MOJO_PROPERTY_TYPE_SYNC_CALL_ALLOWED = 0; 222 #else 223 #define MOJO_PROPERTY_TYPE_SYNC_CALL_ALLOWED ((MojoPropertyType)0) 224 #endif 225 226 #endif // MOJO_PUBLIC_C_SYSTEM_TYPES_H_ 227