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|: 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