Home | History | Annotate | Download | only in system 
      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_
    177