• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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