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|: Used to specify time ticks. Value is in microseconds.
21
22typedef int64_t MojoTimeTicks;
23
24// |MojoHandle|: Handles to Mojo objects.
25//   |MOJO_HANDLE_INVALID| - A value that is never a valid handle.
26
27typedef uint32_t MojoHandle;
28
29#ifdef __cplusplus
30const MojoHandle MOJO_HANDLE_INVALID = 0;
31#else
32#define MOJO_HANDLE_INVALID ((MojoHandle)0)
33#endif
34
35// |MojoResult|: Result codes for Mojo operations. Non-negative values are
36// success codes; negative values are error/failure codes.
37//   |MOJO_RESULT_OK| - Not an error; returned on success. Note that positive
38//       |MojoResult|s may also be used to indicate success.
39//   |MOJO_RESULT_CANCELLED| - Operation was cancelled, typically by the caller.
40//   |MOJO_RESULT_UNKNOWN| - Unknown error (e.g., if not enough information is
41//       available for a more specific error).
42//   |MOJO_RESULT_INVALID_ARGUMENT| - Caller specified an invalid argument. This
43//       differs from |MOJO_RESULT_FAILED_PRECONDITION| in that the former
44//       indicates arguments that are invalid regardless of the state of the
45//       system.
46//   |MOJO_RESULT_DEADLINE_EXCEEDED| - Deadline expired before the operation
47//       could complete.
48//   |MOJO_RESULT_NOT_FOUND| - Some requested entity was not found (i.e., does
49//       not exist).
50//   |MOJO_RESULT_ALREADY_EXISTS| - Some entity or condition that we attempted
51//       to create already exists.
52//   |MOJO_RESULT_PERMISSION_DENIED| - The caller does not have permission to
53//       for the operation (use |MOJO_RESULT_RESOURCE_EXHAUSTED| for rejections
54//       caused by exhausting some resource instead).
55//   |MOJO_RESULT_RESOURCE_EXHAUSTED| - Some resource required for the call
56//       (possibly some quota) has been exhausted.
57//   |MOJO_RESULT_FAILED_PRECONDITION| - The system is not in a state required
58//       for the operation (use this if the caller must do something to rectify
59//       the state before retrying).
60//   |MOJO_RESULT_ABORTED| - The operation was aborted by the system, possibly
61//       due to a concurrency issue (use this if the caller may retry at a
62//       higher level).
63//   |MOJO_RESULT_OUT_OF_RANGE| - The operation was attempted past the valid
64//       range. Unlike |MOJO_RESULT_INVALID_ARGUMENT|, this indicates that the
65//       operation may be/become valid depending on the system state. (This
66//       error is similar to |MOJO_RESULT_FAILED_PRECONDITION|, but is more
67//       specific.)
68//   |MOJO_RESULT_UNIMPLEMENTED| - The operation is not implemented, supported,
69//       or enabled.
70//   |MOJO_RESULT_INTERNAL| - Internal error: this should never happen and
71//       indicates that some invariant expected by the system has been broken.
72//   |MOJO_RESULT_UNAVAILABLE| - The operation is (temporarily) currently
73//       unavailable. The caller may simply retry the operation (possibly with a
74//       backoff).
75//   |MOJO_RESULT_DATA_LOSS| - Unrecoverable data loss or corruption.
76//   |MOJO_RESULT_BUSY| - One of the resources involved is currently being used
77//       (possibly on another thread) in a way that prevents the current
78//       operation from proceeding, e.g., if the other operation may result in
79//       the resource being invalidated.
80//   |MOJO_RESULT_SHOULD_WAIT| - The request cannot currently be completed
81//       (e.g., if the data requested is not yet available). The caller should
82//       wait for it to be feasible using |MojoWait()| or |MojoWaitMany()|.
83//
84// Note that positive values are also available as success codes.
85//
86// The codes from |MOJO_RESULT_OK| to |MOJO_RESULT_DATA_LOSS| come from
87// Google3's canonical error codes.
88//
89// TODO(vtl): Add a |MOJO_RESULT_UNSATISFIABLE|?
90
91typedef int32_t MojoResult;
92
93#ifdef __cplusplus
94const MojoResult MOJO_RESULT_OK = 0;
95const MojoResult MOJO_RESULT_CANCELLED = -1;
96const MojoResult MOJO_RESULT_UNKNOWN = -2;
97const MojoResult MOJO_RESULT_INVALID_ARGUMENT = -3;
98const MojoResult MOJO_RESULT_DEADLINE_EXCEEDED = -4;
99const MojoResult MOJO_RESULT_NOT_FOUND = -5;
100const MojoResult MOJO_RESULT_ALREADY_EXISTS = -6;
101const MojoResult MOJO_RESULT_PERMISSION_DENIED = -7;
102const MojoResult MOJO_RESULT_RESOURCE_EXHAUSTED = -8;
103const MojoResult MOJO_RESULT_FAILED_PRECONDITION = -9;
104const MojoResult MOJO_RESULT_ABORTED = -10;
105const MojoResult MOJO_RESULT_OUT_OF_RANGE = -11;
106const MojoResult MOJO_RESULT_UNIMPLEMENTED = -12;
107const MojoResult MOJO_RESULT_INTERNAL = -13;
108const MojoResult MOJO_RESULT_UNAVAILABLE = -14;
109const MojoResult MOJO_RESULT_DATA_LOSS = -15;
110const MojoResult MOJO_RESULT_BUSY = -16;
111const MojoResult MOJO_RESULT_SHOULD_WAIT = -17;
112#else
113#define MOJO_RESULT_OK ((MojoResult)0)
114#define MOJO_RESULT_CANCELLED ((MojoResult) - 1)
115#define MOJO_RESULT_UNKNOWN ((MojoResult) - 2)
116#define MOJO_RESULT_INVALID_ARGUMENT ((MojoResult) - 3)
117#define MOJO_RESULT_DEADLINE_EXCEEDED ((MojoResult) - 4)
118#define MOJO_RESULT_NOT_FOUND ((MojoResult) - 5)
119#define MOJO_RESULT_ALREADY_EXISTS ((MojoResult) - 6)
120#define MOJO_RESULT_PERMISSION_DENIED ((MojoResult) - 7)
121#define MOJO_RESULT_RESOURCE_EXHAUSTED ((MojoResult) - 8)
122#define MOJO_RESULT_FAILED_PRECONDITION ((MojoResult) - 9)
123#define MOJO_RESULT_ABORTED ((MojoResult) - 10)
124#define MOJO_RESULT_OUT_OF_RANGE ((MojoResult) - 11)
125#define MOJO_RESULT_UNIMPLEMENTED ((MojoResult) - 12)
126#define MOJO_RESULT_INTERNAL ((MojoResult) - 13)
127#define MOJO_RESULT_UNAVAILABLE ((MojoResult) - 14)
128#define MOJO_RESULT_DATA_LOSS ((MojoResult) - 15)
129#define MOJO_RESULT_BUSY ((MojoResult) - 16)
130#define MOJO_RESULT_SHOULD_WAIT ((MojoResult) - 17)
131#endif
132
133// |MojoDeadline|: Used to specify deadlines (timeouts), in microseconds (except
134// for |MOJO_DEADLINE_INDEFINITE|).
135//   |MOJO_DEADLINE_INDEFINITE| - Used to indicate "forever".
136
137typedef uint64_t MojoDeadline;
138
139#ifdef __cplusplus
140const MojoDeadline MOJO_DEADLINE_INDEFINITE = static_cast<MojoDeadline>(-1);
141#else
142#define MOJO_DEADLINE_INDEFINITE ((MojoDeadline) - 1)
143#endif
144
145// |MojoHandleSignals|: Used to specify signals that can be waited on for a
146// handle (and which can be triggered), e.g., the ability to read or write to
147// the handle.
148//   |MOJO_HANDLE_SIGNAL_NONE| - No flags. |MojoWait()|, etc. will return
149//       |MOJO_RESULT_FAILED_PRECONDITION| if you attempt to wait on this.
150//   |MOJO_HANDLE_SIGNAL_READABLE| - Can read (e.g., a message) from the handle.
151//   |MOJO_HANDLE_SIGNAL_WRITABLE| - Can write (e.g., a message) to the handle.
152
153typedef uint32_t MojoHandleSignals;
154
155#ifdef __cplusplus
156const MojoHandleSignals MOJO_HANDLE_SIGNAL_NONE = 0;
157const MojoHandleSignals MOJO_HANDLE_SIGNAL_READABLE = 1 << 0;
158const MojoHandleSignals MOJO_HANDLE_SIGNAL_WRITABLE = 1 << 1;
159#else
160#define MOJO_HANDLE_SIGNAL_NONE ((MojoHandleSignals)0)
161#define MOJO_HANDLE_SIGNAL_READABLE ((MojoHandleSignals)1 << 0)
162#define MOJO_HANDLE_SIGNAL_WRITABLE ((MojoHandleSignals)1 << 1)
163#endif
164
165// TODO(vtl): Add out parameters with this to MojoWait/MojoWaitMany.
166// Note: This struct is not extensible (and only has 32-bit quantities), so it's
167// 32-bit-aligned.
168MOJO_COMPILE_ASSERT(MOJO_ALIGNOF(int32_t) == 4, int32_t_has_weird_alignment);
169struct MOJO_ALIGNAS(4) MojoHandleSignalsState {
170  MojoHandleSignals satisfied_signals;
171  MojoHandleSignals satisfiable_signals;
172};
173MOJO_COMPILE_ASSERT(sizeof(MojoHandleSignalsState) == 8,
174                    MojoHandleSignalsState_has_wrong_size);
175
176#endif  // MOJO_PUBLIC_C_SYSTEM_TYPES_H_
177