mojo/public/c/system/types.h

   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
  22 typedef int64_t MojoTimeTicks;
  23
  24 // |MojoHandle|: Handles to Mojo objects.
  25 //   |MOJO_HANDLE_INVALID| - A value that is never a valid handle.
  26
  27 typedef uint32_t MojoHandle;
  28
  29 #ifdef __cplusplus
  30 const 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
  91 typedef int32_t MojoResult;
  92
  93 #ifdef __cplusplus
  94 const MojoResult MOJO_RESULT_OK = 0;
  95 const MojoResult MOJO_RESULT_CANCELLED = -1;
  96 const MojoResult MOJO_RESULT_UNKNOWN = -2;
  97 const MojoResult MOJO_RESULT_INVALID_ARGUMENT = -3;
  98 const MojoResult MOJO_RESULT_DEADLINE_EXCEEDED = -4;
  99 const MojoResult MOJO_RESULT_NOT_FOUND = -5;
 100 const MojoResult MOJO_RESULT_ALREADY_EXISTS = -6;
 101 const MojoResult MOJO_RESULT_PERMISSION_DENIED = -7;
 102 const MojoResult MOJO_RESULT_RESOURCE_EXHAUSTED = -8;
 103 const MojoResult MOJO_RESULT_FAILED_PRECONDITION = -9;
 104 const MojoResult MOJO_RESULT_ABORTED = -10;
 105 const MojoResult MOJO_RESULT_OUT_OF_RANGE = -11;
 106 const MojoResult MOJO_RESULT_UNIMPLEMENTED = -12;
 107 const MojoResult MOJO_RESULT_INTERNAL = -13;
 108 const MojoResult MOJO_RESULT_UNAVAILABLE = -14;
 109 const MojoResult MOJO_RESULT_DATA_LOSS = -15;
 110 const MojoResult MOJO_RESULT_BUSY = -16;
 111 const 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
 137 typedef uint64_t MojoDeadline;
 138
 139 #ifdef __cplusplus
 140 const 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
 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 #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.
 168 MOJO_COMPILE_ASSERT(MOJO_ALIGNOF(int32_t) == 4, int32_t_has_weird_alignment);
 169 struct MOJO_ALIGNAS(4) MojoHandleSignalsState {
 170   MojoHandleSignals satisfied_signals;
 171   MojoHandleSignals satisfiable_signals;
 172 };
 173 MOJO_COMPILE_ASSERT(sizeof(MojoHandleSignalsState) == 8,
 174                     MojoHandleSignalsState_has_wrong_size);
 175
 176 #endif  // MOJO_PUBLIC_C_SYSTEM_TYPES_H_