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 153 typedef uint32_t MojoHandleSignals; 154 155 #ifdef __cplusplus 156 const MojoHandleSignals MOJO_HANDLE_SIGNAL_NONE = 0; 157 const MojoHandleSignals MOJO_HANDLE_SIGNAL_READABLE = 1 << 0; 158 const MojoHandleSignals MOJO_HANDLE_SIGNAL_WRITABLE = 1 << 1; 159 const MojoHandleSignals MOJO_HANDLE_SIGNAL_PEER_CLOSED = 1 << 2; 160 #else 161 #define MOJO_HANDLE_SIGNAL_NONE ((MojoHandleSignals)0) 162 #define MOJO_HANDLE_SIGNAL_READABLE ((MojoHandleSignals)1 << 0) 163 #define MOJO_HANDLE_SIGNAL_WRITABLE ((MojoHandleSignals)1 << 1) 164 #define MOJO_HANDLE_SIGNAL_PEER_CLOSED ((MojoHandleSignals)1 << 2) 165 #endif 166 167 // |MojoHandleSignalsState|: Returned by wait functions to indicate the 168 // signaling state of handles. Members are as follows: 169 // - |satisfied signals|: Bitmask of signals that were satisfied at some time 170 // before the call returned. 171 // - |satisfiable signals|: These are the signals that are possible to 172 // satisfy. For example, if the return value was 173 // |MOJO_RESULT_FAILED_PRECONDITION|, you can use this field to 174 // determine which, if any, of the signals can still be satisfied. 175 // Note: This struct is not extensible (and only has 32-bit quantities), so it's 176 // 32-bit-aligned. 177 MOJO_STATIC_ASSERT(MOJO_ALIGNOF(int32_t) == 4, "int32_t has weird alignment"); 178 struct MOJO_ALIGNAS(4) MojoHandleSignalsState { 179 MojoHandleSignals satisfied_signals; 180 MojoHandleSignals satisfiable_signals; 181 }; 182 MOJO_STATIC_ASSERT(sizeof(MojoHandleSignalsState) == 8, 183 "MojoHandleSignalsState has wrong size"); 184 185 // |MojoWatchNotificationFlags|: Passed to a callback invoked as a result of 186 // signals being raised on a handle watched by |MojoWatch()|. May take the 187 // following values: 188 // |MOJO_WATCH_NOTIFICATION_FLAG_FROM_SYSTEM| - The callback is being invoked 189 // as a result of a system-level event rather than a direct API call from 190 // user code. This may be used as an indication that user code is safe to 191 // call without fear of reentry. 192 193 typedef uint32_t MojoWatchNotificationFlags; 194 195 #ifdef __cplusplus 196 const MojoWatchNotificationFlags MOJO_WATCH_NOTIFICATION_FLAG_NONE = 0; 197 const MojoWatchNotificationFlags MOJO_WATCH_NOTIFICATION_FLAG_FROM_SYSTEM = 198 1 << 0; 199 #else 200 #define MOJO_WATCH_NOTIFICATION_FLAG_NONE ((MojoWatchNotificationFlags)0) 201 #define MOJO_WATCH_NOTIFICATION_FLAG_FROM_SYSTEM \ 202 ((MojoWatchNotificationFlags)1 << 0); 203 #endif 204 205 // |MojoPropertyType|: Property types that can be passed to |MojoGetProperty()| 206 // to retrieve system properties. May take the following values: 207 // |MOJO_PROPERTY_TYPE_SYNC_CALL_ALLOWED| - Whether making synchronous calls 208 // (i.e., blocking to wait for a response to an outbound message) is 209 // allowed. The property value is of boolean type. If the value is true, 210 // users should refrain from making sync calls. 211 typedef uint32_t MojoPropertyType; 212 213 #ifdef __cplusplus 214 const MojoPropertyType MOJO_PROPERTY_TYPE_SYNC_CALL_ALLOWED = 0; 215 #else 216 #define MOJO_PROPERTY_TYPE_SYNC_CALL_ALLOWED ((MojoPropertyType)0) 217 #endif 218 219 #endif // MOJO_PUBLIC_C_SYSTEM_TYPES_H_ 220