| OLD | NEW |
|---|
| (Empty) |
| 1 // Copyright 2013 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 #ifndef MOJO_PUBLIC_SYSTEM_CORE_H_ | |
| 6 #define MOJO_PUBLIC_SYSTEM_CORE_H_ | |
| 7 | |
| 8 // Note: This header should be compilable as C. | |
| 9 | |
| 10 #include <stdint.h> | |
| 11 | |
| 12 #include "mojo/public/system/macros.h" | |
| 13 #include "mojo/public/system/system_export.h" | |
| 14 | |
| 15 // Types/constants ------------------------------------------------------------- | |
| 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 // |MojoWaitFlags|: Used to specify the state of a handle to wait on (e.g., the | |
| 146 // ability to read or write to it). | |
| 147 // |MOJO_WAIT_FLAG_NONE| - No flags. |MojoWait()|, etc. will return | |
| 148 // |MOJO_RESULT_FAILED_PRECONDITION| if you attempt to wait on this. | |
| 149 // |MOJO_WAIT_FLAG_READABLE| - Can read (e.g., a message) from the handle. | |
| 150 // |MOJO_WAIT_FLAG_WRITABLE| - Can write (e.g., a message) to the handle. | |
| 151 // |MOJO_WAIT_FLAG_EVERYTHING| - All flags. | |
| 152 | |
| 153 typedef uint32_t MojoWaitFlags; | |
| 154 | |
| 155 #ifdef __cplusplus | |
| 156 const MojoWaitFlags MOJO_WAIT_FLAG_NONE = 0; | |
| 157 const MojoWaitFlags MOJO_WAIT_FLAG_READABLE = 1 << 0; | |
| 158 const MojoWaitFlags MOJO_WAIT_FLAG_WRITABLE = 1 << 1; | |
| 159 const MojoWaitFlags MOJO_WAIT_FLAG_EVERYTHING = ~0; | |
| 160 #else | |
| 161 #define MOJO_WAIT_FLAG_NONE ((MojoWaitFlags) 0) | |
| 162 #define MOJO_WAIT_FLAG_READABLE ((MojoWaitFlags) 1 << 0) | |
| 163 #define MOJO_WAIT_FLAG_WRITABLE ((MojoWaitFlags) 1 << 1) | |
| 164 #define MOJO_WAIT_FLAG_EVERYTHING (~((MojoWaitFlags) 0)) | |
| 165 #endif | |
| 166 | |
| 167 // Message pipe: | |
| 168 | |
| 169 // |MojoWriteMessageFlags|: Used to specify different modes to | |
| 170 // |MojoWriteMessage()|. | |
| 171 // |MOJO_WRITE_MESSAGE_FLAG_NONE| - No flags; default mode. | |
| 172 | |
| 173 typedef uint32_t MojoWriteMessageFlags; | |
| 174 | |
| 175 #ifdef __cplusplus | |
| 176 const MojoWriteMessageFlags MOJO_WRITE_MESSAGE_FLAG_NONE = 0; | |
| 177 #else | |
| 178 #define MOJO_WRITE_MESSAGE_FLAG_NONE ((MojoWriteMessageFlags) 0) | |
| 179 #endif | |
| 180 | |
| 181 // |MojoReadMessageFlags|: Used to specify different modes to | |
| 182 // |MojoReadMessage()|. | |
| 183 // |MOJO_READ_MESSAGE_FLAG_NONE| - No flags; default mode. | |
| 184 // |MOJO_READ_MESSAGE_FLAG_MAY_DISCARD| - If the message is unable to be read | |
| 185 // for whatever reason (e.g., the caller-supplied buffer is too small), | |
| 186 // discard the message (i.e., simply dequeue it). | |
| 187 | |
| 188 typedef uint32_t MojoReadMessageFlags; | |
| 189 | |
| 190 #ifdef __cplusplus | |
| 191 const MojoReadMessageFlags MOJO_READ_MESSAGE_FLAG_NONE = 0; | |
| 192 const MojoReadMessageFlags MOJO_READ_MESSAGE_FLAG_MAY_DISCARD = 1 << 0; | |
| 193 #else | |
| 194 #define MOJO_READ_MESSAGE_FLAG_NONE ((MojoReadMessageFlags) 0) | |
| 195 #define MOJO_READ_MESSAGE_FLAG_MAY_DISCARD ((MojoReadMessageFlags) 1 << 0) | |
| 196 #endif | |
| 197 | |
| 198 // Data pipe: | |
| 199 | |
| 200 // |MojoCreateDataPipeOptions|: Used to specify creation parameters for a data | |
| 201 // pipe to |MojoCreateDataPipe()|. | |
| 202 // |uint32_t struct_size|: Set to the size of the |MojoCreateDataPipeOptions| | |
| 203 // struct. (Used to allow for future extensions.) | |
| 204 // |MojoCreateDataPipeOptionsFlags flags|: Used to specify different modes of | |
| 205 // operation. | |
| 206 // |MOJO_CREATE_DATA_PIPE_OPTIONS_FLAG_NONE|: No flags; default mode. | |
| 207 // |MOJO_CREATE_DATA_PIPE_OPTIONS_FLAG_MAY_DISCARD|: May discard data for | |
| 208 // whatever reason; best-effort delivery. In particular, if the capacity | |
| 209 // is reached, old data may be discard to make room for new data. | |
| 210 // |uint32_t element_num_bytes|: The size of an element, in bytes. All | |
| 211 // transactions and buffers will consist of an integral number of | |
| 212 // elements. Must be nonzero. | |
| 213 // |uint32_t capacity_num_bytes|: The capacity of the data pipe, in number of | |
| 214 // bytes; must be a multiple of |element_num_bytes|. The data pipe will | |
| 215 // always be able to queue AT LEAST this much data. Set to zero to opt for | |
| 216 // a system-dependent automatically-calculated capacity (which will always | |
| 217 // be at least one element). | |
| 218 | |
| 219 typedef uint32_t MojoCreateDataPipeOptionsFlags; | |
| 220 | |
| 221 #ifdef __cplusplus | |
| 222 const MojoCreateDataPipeOptionsFlags | |
| 223 MOJO_CREATE_DATA_PIPE_OPTIONS_FLAG_NONE = 0; | |
| 224 const MojoCreateDataPipeOptionsFlags | |
| 225 MOJO_CREATE_DATA_PIPE_OPTIONS_FLAG_MAY_DISCARD = 1 << 0; | |
| 226 #else | |
| 227 #define MOJO_CREATE_DATA_PIPE_OPTIONS_FLAG_NONE \ | |
| 228 ((MojoCreateDataPipeOptionsFlags) 0) | |
| 229 #define MOJO_CREATE_DATA_PIPE_OPTIONS_FLAG_MAY_DISCARD \ | |
| 230 ((MojoCreateDataPipeOptionsFlags) 1 << 0) | |
| 231 #endif | |
| 232 | |
| 233 struct MojoCreateDataPipeOptions { | |
| 234 uint32_t struct_size; | |
| 235 MojoCreateDataPipeOptionsFlags flags; | |
| 236 uint32_t element_num_bytes; | |
| 237 uint32_t capacity_num_bytes; | |
| 238 }; | |
| 239 // TODO(vtl): Can we make this assertion work in C? | |
| 240 #ifdef __cplusplus | |
| 241 MOJO_COMPILE_ASSERT(sizeof(MojoCreateDataPipeOptions) == 16, | |
| 242 MojoCreateDataPipeOptions_has_wrong_size); | |
| 243 #endif | |
| 244 | |
| 245 // |MojoWriteDataFlags|: Used to specify different modes to |MojoWriteData()| | |
| 246 // and |MojoBeginWriteData()|. | |
| 247 // |MOJO_WRITE_DATA_FLAG_NONE| - No flags; default mode. | |
| 248 // |MOJO_WRITE_DATA_FLAG_ALL_OR_NONE| - Write either all the elements | |
| 249 // requested or none of them. | |
| 250 | |
| 251 typedef uint32_t MojoWriteDataFlags; | |
| 252 | |
| 253 #ifdef __cplusplus | |
| 254 const MojoWriteDataFlags MOJO_WRITE_DATA_FLAG_NONE = 0; | |
| 255 const MojoWriteDataFlags MOJO_WRITE_DATA_FLAG_ALL_OR_NONE = 1 << 0; | |
| 256 #else | |
| 257 #define MOJO_WRITE_DATA_FLAG_NONE ((MojoWriteDataFlags) 0) | |
| 258 #define MOJO_WRITE_DATA_FLAG_ALL_OR_NONE ((MojoWriteDataFlags) 1 << 0) | |
| 259 #endif | |
| 260 | |
| 261 // |MojoReadDataFlags|: Used to specify different modes to |MojoReadData()| and | |
| 262 // |MojoBeginReadData()|. | |
| 263 // |MOJO_READ_DATA_FLAG_NONE| - No flags; default mode. | |
| 264 // |MOJO_READ_DATA_FLAG_ALL_OR_NONE| - Read (or discard) either the requested | |
| 265 // number of elements or none. | |
| 266 // |MOJO_READ_DATA_FLAG_DISCARD| - Discard (up to) the requested number of | |
| 267 // elements. | |
| 268 // |MOJO_READ_DATA_FLAG_QUERY| - Query the number of elements available to | |
| 269 // read. For use with |MojoReadData()| only. Mutually exclusive with | |
| 270 // |MOJO_READ_DATA_FLAG_DISCARD| and |MOJO_READ_DATA_FLAG_ALL_OR_NONE| is | |
| 271 // ignored if this flag is set. | |
| 272 | |
| 273 typedef uint32_t MojoReadDataFlags; | |
| 274 | |
| 275 #ifdef __cplusplus | |
| 276 const MojoReadDataFlags MOJO_READ_DATA_FLAG_NONE = 0; | |
| 277 const MojoReadDataFlags MOJO_READ_DATA_FLAG_ALL_OR_NONE = 1 << 0; | |
| 278 const MojoReadDataFlags MOJO_READ_DATA_FLAG_DISCARD = 1 << 1; | |
| 279 const MojoReadDataFlags MOJO_READ_DATA_FLAG_QUERY = 1 << 2; | |
| 280 #else | |
| 281 #define MOJO_READ_DATA_FLAG_NONE ((MojoReadDataFlags) 0) | |
| 282 #define MOJO_READ_DATA_FLAG_ALL_OR_NONE ((MojoReadDataFlags) 1 << 0) | |
| 283 #define MOJO_READ_DATA_FLAG_DISCARD ((MojoReadDataFlags) 1 << 1) | |
| 284 #define MOJO_READ_DATA_FLAG_QUERY ((MojoReadDataFlags) 1 << 2) | |
| 285 #endif | |
| 286 | |
| 287 // Shared buffer: | |
| 288 | |
| 289 // |MojoCreateSharedBufferOptions|: Used to specify creation parameters for a | |
| 290 // shared buffer to |MojoCreateSharedBuffer()|. | |
| 291 // |uint32_t struct_size|: Set to the size of the | |
| 292 // |MojoCreateSharedBufferOptions| struct. (Used to allow for future | |
| 293 // extensions.) | |
| 294 // |MojoCreateSharedBufferOptionsFlags flags|: Reserved for future use. | |
| 295 // |MOJO_CREATE_SHARED_BUFFER_OPTIONS_FLAG_NONE|: No flags; default mode. | |
| 296 // | |
| 297 // TODO(vtl): Maybe add a flag to indicate whether the memory should be | |
| 298 // executable or not? | |
| 299 // TODO(vtl): Also a flag for discardable (ashmem-style) buffers. | |
| 300 | |
| 301 typedef uint32_t MojoCreateSharedBufferOptionsFlags; | |
| 302 | |
| 303 #ifdef __cplusplus | |
| 304 const MojoCreateSharedBufferOptionsFlags | |
| 305 MOJO_CREATE_SHARED_BUFFER_OPTIONS_FLAG_NONE = 0; | |
| 306 #else | |
| 307 #define MOJO_CREATE_SHARED_BUFFER_OPTIONS_FLAG_NONE \ | |
| 308 ((MojoCreateSharedBufferOptionsFlags) 0) | |
| 309 #endif | |
| 310 | |
| 311 struct MojoCreateSharedBufferOptions { | |
| 312 uint32_t struct_size; | |
| 313 MojoCreateSharedBufferOptionsFlags flags; | |
| 314 }; | |
| 315 // TODO(vtl): Can we make this assertion work in C? | |
| 316 #ifdef __cplusplus | |
| 317 MOJO_COMPILE_ASSERT(sizeof(MojoCreateSharedBufferOptions) == 8, | |
| 318 MojoCreateSharedBufferOptions_has_wrong_size); | |
| 319 #endif | |
| 320 | |
| 321 // |MojoDuplicateBufferHandleOptions|: Used to specify parameters in duplicating | |
| 322 // access to a shared buffer to |MojoDuplicateBufferHandle()|. | |
| 323 // |uint32_t struct_size|: Set to the size of the | |
| 324 // |MojoDuplicateBufferHandleOptions| struct. (Used to allow for future | |
| 325 // extensions.) | |
| 326 // |MojoDuplicateBufferHandleOptionsFlags flags|: Reserved for future use. | |
| 327 // |MOJO_DUPLICATE_BUFFER_HANDLE_OPTIONS_FLAG_NONE|: No flags; default | |
| 328 // mode. | |
| 329 // | |
| 330 // TODO(vtl): Add flags to remove writability (and executability)? Also, COW? | |
| 331 | |
| 332 typedef uint32_t MojoDuplicateBufferHandleOptionsFlags; | |
| 333 | |
| 334 #ifdef __cplusplus | |
| 335 const MojoDuplicateBufferHandleOptionsFlags | |
| 336 MOJO_DUPLICATE_BUFFER_HANDLE_OPTIONS_FLAG_NONE = 0; | |
| 337 #else | |
| 338 #define MOJO_DUPLICATE_BUFFER_HANDLE_OPTIONS_FLAG_NONE \ | |
| 339 ((MojoDuplicateBufferHandleOptionsFlags) 0) | |
| 340 #endif | |
| 341 | |
| 342 struct MojoDuplicateBufferHandleOptions { | |
| 343 uint32_t struct_size; | |
| 344 MojoDuplicateBufferHandleOptionsFlags flags; | |
| 345 }; | |
| 346 // TODO(vtl): Can we make this assertion work in C? | |
| 347 #ifdef __cplusplus | |
| 348 MOJO_COMPILE_ASSERT(sizeof(MojoDuplicateBufferHandleOptions) == 8, | |
| 349 MojoDuplicateBufferHandleOptions_has_wrong_size); | |
| 350 #endif | |
| 351 | |
| 352 // |MojoMapBufferFlags|: Used to specify different modes to |MojoMapBuffer()|. | |
| 353 // |MOJO_MAP_BUFFER_FLAG_NONE| - No flags; default mode. | |
| 354 | |
| 355 typedef uint32_t MojoMapBufferFlags; | |
| 356 | |
| 357 #ifdef __cplusplus | |
| 358 const MojoMapBufferFlags MOJO_MAP_BUFFER_FLAG_NONE = 0; | |
| 359 #else | |
| 360 #define MOJO_MAP_BUFFER_FLAG_NONE ((MojoMapBufferFlags) 0) | |
| 361 #endif | |
| 362 | |
| 363 // Functions ------------------------------------------------------------------- | |
| 364 | |
| 365 // Note: Pointer parameters that are labeled "optional" may be null (at least | |
| 366 // under some circumstances). Non-const pointer parameters are also labelled | |
| 367 // "in", "out", or "in/out", to indicate how they are used. (Note that how/if | |
| 368 // such a parameter is used may depend on other parameters or the requested | |
| 369 // operation's success/failure. E.g., a separate |flags| parameter may control | |
| 370 // whether a given "in/out" parameter is used for input, output, or both.) | |
| 371 | |
| 372 #ifdef __cplusplus | |
| 373 extern "C" { | |
| 374 #endif | |
| 375 | |
| 376 // Platform-dependent monotonically increasing tick count representing "right | |
| 377 // now." The resolution of this clock is ~1-15ms. Resolution varies depending | |
| 378 // on hardware/operating system configuration. | |
| 379 MOJO_SYSTEM_EXPORT MojoTimeTicks MojoGetTimeTicksNow(); | |
| 380 | |
| 381 // Closes the given |handle|. | |
| 382 // | |
| 383 // Returns: | |
| 384 // |MOJO_RESULT_OK| on success. | |
| 385 // |MOJO_RESULT_INVALID_ARGUMENT| if |handle| is not a valid handle. | |
| 386 // | |
| 387 // Concurrent operations on |handle| may succeed (or fail as usual) if they | |
| 388 // happen before the close, be cancelled with result |MOJO_RESULT_CANCELLED| if | |
| 389 // they properly overlap (this is likely the case with |MojoWait()|, etc.), or | |
| 390 // fail with |MOJO_RESULT_INVALID_ARGUMENT| if they happen after. | |
| 391 MOJO_SYSTEM_EXPORT MojoResult MojoClose(MojoHandle handle); | |
| 392 | |
| 393 // Waits on the given handle until the state indicated by |flags| is satisfied | |
| 394 // or until |deadline| has passed. | |
| 395 // | |
| 396 // Returns: | |
| 397 // |MOJO_RESULT_OK| if some flag in |flags| was satisfied (or is already | |
| 398 // satisfied). | |
| 399 // |MOJO_RESULT_INVALID_ARGUMENT| if |handle| is not a valid handle (e.g., if | |
| 400 // it has already been closed). | |
| 401 // |MOJO_RESULT_DEADLINE_EXCEEDED| if the deadline has passed without any of | |
| 402 // the flags being satisfied. | |
| 403 // |MOJO_RESULT_FAILED_PRECONDITION| if it is or becomes impossible that any | |
| 404 // flag in |flags| will ever be satisfied. | |
| 405 // | |
| 406 // If there are multiple waiters (on different threads, obviously) waiting on | |
| 407 // the same handle and flag and that flag becomes set, all waiters will be | |
| 408 // awoken. | |
| 409 MOJO_SYSTEM_EXPORT MojoResult MojoWait(MojoHandle handle, | |
| 410 MojoWaitFlags flags, | |
| 411 MojoDeadline deadline); | |
| 412 | |
| 413 // Waits on |handles[0]|, ..., |handles[num_handles-1]| for at least one of them | |
| 414 // to satisfy the state indicated by |flags[0]|, ..., |flags[num_handles-1]|, | |
| 415 // respectively, or until |deadline| has passed. | |
| 416 // | |
| 417 // Returns: | |
| 418 // The index |i| (from 0 to |num_handles-1|) if |handle[i]| satisfies | |
| 419 // |flags[i]|. | |
| 420 // |MOJO_RESULT_INVALID_ARGUMENT| if some |handle[i]| is not a valid handle | |
| 421 // (e.g., if it has already been closed). | |
| 422 // |MOJO_RESULT_DEADLINE_EXCEEDED| if the deadline has passed without any of | |
| 423 // handles satisfying any of its flags. | |
| 424 // |MOJO_RESULT_FAILED_PRECONDITION| if it is or becomes impossible that SOME | |
| 425 // |handle[i]| will ever satisfy any of its flags |flags[i]|. | |
| 426 MOJO_SYSTEM_EXPORT MojoResult MojoWaitMany(const MojoHandle* handles, | |
| 427 const MojoWaitFlags* flags, | |
| 428 uint32_t num_handles, | |
| 429 MojoDeadline deadline); | |
| 430 | |
| 431 // Message pipe: | |
| 432 | |
| 433 // Creates a message pipe, which is a bidirectional communication channel for | |
| 434 // framed data (i.e., messages). Messages can contain plain data and/or Mojo | |
| 435 // handles. On success, |*message_pipe_handle0| and |*message_pipe_handle1| are | |
| 436 // set to handles for the two endpoints (ports) for the message pipe. | |
| 437 // | |
| 438 // Returns: | |
| 439 // |MOJO_RESULT_OK| on success. | |
| 440 // |MOJO_RESULT_INVALID_ARGUMENT| if |message_pipe_handle0| and/or | |
| 441 // |message_pipe_handle1| do not appear to be valid pointers. | |
| 442 // |MOJO_RESULT_RESOURCE_EXHAUSTED| if a process/system/quota/etc. limit has | |
| 443 // been reached. | |
| 444 // | |
| 445 // TODO(vtl): Add an options struct pointer argument. | |
| 446 MOJO_SYSTEM_EXPORT MojoResult MojoCreateMessagePipe( | |
| 447 MojoHandle* message_pipe_handle0, // Out. | |
| 448 MojoHandle* message_pipe_handle1); // Out. | |
| 449 | |
| 450 // Writes a message to the message pipe endpoint given by |message_pipe_handle|, | |
| 451 // with message data specified by |bytes| of size |num_bytes| and attached | |
| 452 // handles specified by |handles| of count |num_handles|, and options specified | |
| 453 // by |flags|. If there is no message data, |bytes| may be null, in which case | |
| 454 // |num_bytes| must be zero. If there are no attached handles, |handles| may be | |
| 455 // null, in which case |num_handles| must be zero. | |
| 456 // | |
| 457 // If handles are attached, on success the handles will no longer be valid (the | |
| 458 // receiver will receive equivalent, but logically different, handles). Handles | |
| 459 // to be sent should not be in simultaneous use (e.g., on another thread). | |
| 460 // | |
| 461 // Returns: | |
| 462 // |MOJO_RESULT_OK| on success (i.e., the message was enqueued). | |
| 463 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., if | |
| 464 // |message_pipe_handle| is not a valid handle, or some of the | |
| 465 // requirements above are not satisfied). | |
| 466 // |MOJO_RESULT_RESOURCE_EXHAUSTED| if some system limit has been reached, or | |
| 467 // the number of handles to send is too large (TODO(vtl): reconsider the | |
| 468 // latter case). | |
| 469 // |MOJO_RESULT_FAILED_PRECONDITION| if the other endpoint has been closed. | |
| 470 // Note that closing an endpoint is not necessarily synchronous (e.g., | |
| 471 // across processes), so this function may be succeed even if the other | |
| 472 // endpoint has been closed (in which case the message would be dropped). | |
| 473 // |MOJO_RESULT_BUSY| if some handle to be sent is currently in use. | |
| 474 // | |
| 475 // TODO(vtl): Add a notion of capacity for message pipes, and return | |
| 476 // |MOJO_RESULT_SHOULD_WAIT| if the message pipe is full. | |
| 477 MOJO_SYSTEM_EXPORT MojoResult MojoWriteMessage( | |
| 478 MojoHandle message_pipe_handle, | |
| 479 const void* bytes, // Optional. | |
| 480 uint32_t num_bytes, | |
| 481 const MojoHandle* handles, // Optional. | |
| 482 uint32_t num_handles, | |
| 483 MojoWriteMessageFlags flags); | |
| 484 | |
| 485 // Reads a message from the message pipe endpoint given by | |
| 486 // |message_pipe_handle|; also usable to query the size of the next message or | |
| 487 // discard the next message. |bytes|/|*num_bytes| indicate the buffer/buffer | |
| 488 // size to receive the message data (if any) and |handles|/|*num_handles| | |
| 489 // indicate the buffer/maximum handle count to receive the attached handles (if | |
| 490 // any). | |
| 491 // | |
| 492 // |num_bytes| and |num_handles| are optional "in-out" parameters. If non-null, | |
| 493 // on return |*num_bytes| and |*num_handles| will usually indicate the number | |
| 494 // of bytes and number of attached handles in the "next" message, respectively, | |
| 495 // whether that message was read or not. (If null, the number of bytes/handles | |
| 496 // is treated as zero.) | |
| 497 // | |
| 498 // If |bytes| is null, then |*num_bytes| must be zero, and similarly for | |
| 499 // |handles| and |*num_handles|. | |
| 500 // | |
| 501 // Partial reads are NEVER done. Either a full read is done and |MOJO_RESULT_OK| | |
| 502 // returned, or the read is NOT done and |MOJO_RESULT_RESOURCE_EXHAUSTED| is | |
| 503 // returned (if |MOJO_READ_MESSAGE_FLAG_MAY_DISCARD| was set, the message is | |
| 504 // also discarded in this case). | |
| 505 // | |
| 506 // Returns: | |
| 507 // |MOJO_RESULT_OK| on success (i.e., a message was actually read). | |
| 508 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid. | |
| 509 // |MOJO_RESULT_FAILED_PRECONDITION| if the other endpoint has been closed. | |
| 510 // |MOJO_RESULT_RESOURCE_EXHAUSTED| if one of the buffers to receive the | |
| 511 // message/attached handles (|bytes|/|*num_bytes| or | |
| 512 // |handles|/|*num_handles|) was too small. (TODO(vtl): Reconsider this | |
| 513 // error code; should distinguish this from the hitting-system-limits | |
| 514 // case.) | |
| 515 // |MOJO_RESULT_SHOULD_WAIT| if no message was available to be read. | |
| 516 MOJO_SYSTEM_EXPORT MojoResult MojoReadMessage( | |
| 517 MojoHandle message_pipe_handle, | |
| 518 void* bytes, // Optional out. | |
| 519 uint32_t* num_bytes, // Optional in/out. | |
| 520 MojoHandle* handles, // Optional out. | |
| 521 uint32_t* num_handles, // Optional in/out. | |
| 522 MojoReadMessageFlags flags); | |
| 523 | |
| 524 // Data pipe: | |
| 525 | |
| 526 // Creates a data pipe, which is a unidirectional communication channel for | |
| 527 // unframed data, with the given options. Data is unframed, but must come as | |
| 528 // (multiples of) discrete elements, of the size given in |options|. See | |
| 529 // |MojoCreateDataPipeOptions| for a description of the different options | |
| 530 // available for data pipes. | |
| 531 // | |
| 532 // |options| may be set to null for a data pipe with the default options (which | |
| 533 // will have an element size of one byte and have some system-dependent | |
| 534 // capacity). | |
| 535 // | |
| 536 // On success, |*data_pipe_producer_handle| will be set to the handle for the | |
| 537 // producer and |*data_pipe_consumer_handle| will be set to the handle for the | |
| 538 // consumer. (On failure, they are not modified.) | |
| 539 // | |
| 540 // Returns: | |
| 541 // |MOJO_RESULT_OK| on success. | |
| 542 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., if | |
| 543 // |*options| is invalid or one of the pointer handles looks invalid). | |
| 544 // |MOJO_RESULT_RESOURCE_EXHAUSTED| if a process/system/quota/etc. limit has | |
| 545 // been reached (e.g., if the requested capacity was too large, or if the | |
| 546 // maximum number of handles was exceeded). | |
| 547 MOJO_SYSTEM_EXPORT MojoResult MojoCreateDataPipe( | |
| 548 const struct MojoCreateDataPipeOptions* options, // Optional. | |
| 549 MojoHandle* data_pipe_producer_handle, // Out. | |
| 550 MojoHandle* data_pipe_consumer_handle); // Out. | |
| 551 | |
| 552 // Writes the given data to the data pipe producer given by | |
| 553 // |data_pipe_producer_handle|. |elements| points to data of size |*num_bytes|; | |
| 554 // |*num_bytes| should be a multiple of the data pipe's element size. If | |
| 555 // |MOJO_WRITE_DATA_FLAG_ALL_OR_NONE| is set in |flags|, either all the data | |
| 556 // will be written or none is. | |
| 557 // | |
| 558 // On success, |*num_bytes| is set to the amount of data that was actually | |
| 559 // written. | |
| 560 // | |
| 561 // Note: If the data pipe has the "may discard" option flag (specified on | |
| 562 // creation), this will discard as much data as required to write the given | |
| 563 // data, starting with the earliest written data that has not been consumed. | |
| 564 // However, even with "may discard", if |*num_bytes| is greater than the data | |
| 565 // pipe's capacity (and |MOJO_WRITE_DATA_FLAG_ALL_OR_NONE| is not set), this | |
| 566 // will write the maximum amount possible (namely, the data pipe's capacity) and | |
| 567 // set |*num_bytes| to that amount. It will *not* discard data from |elements|. | |
| 568 // | |
| 569 // Returns: | |
| 570 // |MOJO_RESULT_OK| on success. | |
| 571 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., if | |
| 572 // |data_pipe_producer_dispatcher| is not a handle to a data pipe | |
| 573 // producer, |elements| does not look like a valid pointer, or | |
| 574 // |*num_bytes| is not a multiple of the data pipe's element size). | |
| 575 // |MOJO_RESULT_FAILED_PRECONDITION| if the data pipe consumer handle has been | |
| 576 // closed. | |
| 577 // |MOJO_RESULT_OUT_OF_RANGE| if |flags| has | |
| 578 // |MOJO_WRITE_DATA_FLAG_ALL_OR_NONE| set and the required amount of data | |
| 579 // (specified by |*num_bytes|) could not be written. | |
| 580 // |MOJO_RESULT_BUSY| if there is a two-phase write ongoing with | |
| 581 // |data_pipe_producer_handle| (i.e., |MojoBeginWriteData()| has been | |
| 582 // called, but not yet the matching |MojoEndWriteData()|). | |
| 583 // |MOJO_RESULT_SHOULD_WAIT| if no data can currently be written (and the | |
| 584 // consumer is still open) and |flags| does *not* have | |
| 585 // |MOJO_WRITE_DATA_FLAG_ALL_OR_NONE| set. | |
| 586 // | |
| 587 // TODO(vtl): Should there be a way of querying how much data can be written? | |
| 588 MOJO_SYSTEM_EXPORT MojoResult MojoWriteData( | |
| 589 MojoHandle data_pipe_producer_handle, | |
| 590 const void* elements, | |
| 591 uint32_t* num_bytes, // In/out. | |
| 592 MojoWriteDataFlags flags); | |
| 593 | |
| 594 // Begins a two-phase write to the data pipe producer given by | |
| 595 // |data_pipe_producer_handle|. On success, |*buffer| will be a pointer to which | |
| 596 // the caller can write |*buffer_num_bytes| bytes of data. If flags has | |
| 597 // |MOJO_WRITE_DATA_FLAG_ALL_OR_NONE| set, then the output value | |
| 598 // |*buffer_num_bytes| will be at least as large as its input value, which must | |
| 599 // also be a multiple of the element size (if |MOJO_WRITE_DATA_FLAG_ALL_OR_NONE| | |
| 600 // is not set, the input value of |*buffer_num_bytes| is ignored). | |
| 601 // | |
| 602 // During a two-phase write, |data_pipe_producer_handle| is *not* writable. | |
| 603 // E.g., if another thread tries to write to it, it will get |MOJO_RESULT_BUSY|; | |
| 604 // that thread can then wait for |data_pipe_producer_handle| to become writable | |
| 605 // again. | |
| 606 // | |
| 607 // Once the caller has finished writing data to |*buffer|, it should call | |
| 608 // |MojoEndWriteData()| to specify the amount written and to complete the | |
| 609 // two-phase write. | |
| 610 // | |
| 611 // Note: If the data pipe has the "may discard" option flag (specified on | |
| 612 // creation) and |flags| has |MOJO_WRITE_DATA_FLAG_ALL_OR_NONE| set, this may | |
| 613 // discard some data. | |
| 614 // | |
| 615 // Returns: | |
| 616 // |MOJO_RESULT_OK| on success. | |
| 617 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., if | |
| 618 // |data_pipe_producer_handle| is not a handle to a data pipe producer, | |
| 619 // |buffer| or |buffer_num_bytes| does not look like a valid pointer, or | |
| 620 // flags has |MOJO_WRITE_DATA_FLAG_ALL_OR_NONE| set and | |
| 621 // |*buffer_num_bytes| is not a multiple of the element size). | |
| 622 // |MOJO_RESULT_FAILED_PRECONDITION| if the data pipe consumer handle has been | |
| 623 // closed. | |
| 624 // |MOJO_RESULT_OUT_OF_RANGE| if |flags| has | |
| 625 // |MOJO_WRITE_DATA_FLAG_ALL_OR_NONE| set and the required amount of data | |
| 626 // (specified by |*buffer_num_bytes|) cannot be written contiguously at | |
| 627 // this time. (Note that there may be space available for the required | |
| 628 // amount of data, but the "next" write position may not be large enough.) | |
| 629 // |MOJO_RESULT_BUSY| if there is already a two-phase write ongoing with | |
| 630 // |data_pipe_producer_handle| (i.e., |MojoBeginWriteData()| has been | |
| 631 // called, but not yet the matching |MojoEndWriteData()|). | |
| 632 // |MOJO_RESULT_SHOULD_WAIT| if no data can currently be written (and the | |
| 633 // consumer is still open). | |
| 634 MOJO_SYSTEM_EXPORT MojoResult MojoBeginWriteData( | |
| 635 MojoHandle data_pipe_producer_handle, | |
| 636 void** buffer, // Out. | |
| 637 uint32_t* buffer_num_bytes, // In/out. | |
| 638 MojoWriteDataFlags flags); | |
| 639 | |
| 640 // Ends a two-phase write to the data pipe producer given by | |
| 641 // |data_pipe_producer_handle| that was begun by a call to | |
| 642 // |MojoBeginWriteData()| on the same handle. |num_bytes_written| should | |
| 643 // indicate the amount of data actually written; it must be less than or equal | |
| 644 // to the value of |*buffer_num_bytes| output by |MojoBeginWriteData()| and must | |
| 645 // be a multiple of the element size. The buffer given by |*buffer| from | |
| 646 // |MojoBeginWriteData()| must have been filled with exactly |num_bytes_written| | |
| 647 // bytes of data. | |
| 648 // | |
| 649 // On failure, the two-phase write (if any) is ended (so the handle may become | |
| 650 // writable again, if there's space available) but no data written to |*buffer| | |
| 651 // is "put into" the data pipe. | |
| 652 // | |
| 653 // Returns: | |
| 654 // |MOJO_RESULT_OK| on success. | |
| 655 // |MOJO_RESULT_INVALID_ARGUMENT| if |data_pipe_producer_handle| is not a | |
| 656 // handle to a data pipe producer or |num_bytes_written| is invalid | |
| 657 // (greater than the maximum value provided by |MojoBeginWriteData()| or | |
| 658 // not a multiple of the element size). | |
| 659 // |MOJO_RESULT_FAILED_PRECONDITION| if the data pipe producer is not in a | |
| 660 // two-phase write (e.g., |MojoBeginWriteData()| was not called or | |
| 661 // |MojoEndWriteData()| has already been called). | |
| 662 MOJO_SYSTEM_EXPORT MojoResult MojoEndWriteData( | |
| 663 MojoHandle data_pipe_producer_handle, | |
| 664 uint32_t num_bytes_written); | |
| 665 | |
| 666 // Reads data from the data pipe consumer given by |data_pipe_consumer_handle|. | |
| 667 // May also be used to discard data or query the amount of data available. | |
| 668 // | |
| 669 // If |flags| has neither |MOJO_READ_DATA_FLAG_DISCARD| nor | |
| 670 // |MOJO_READ_DATA_FLAG_QUERY| set, this tries to read up to |*num_bytes| (which | |
| 671 // must be a multiple of the data pipe's element size) bytes of data to | |
| 672 // |elements| and set |*num_bytes| to the amount actually read. If flags has | |
| 673 // |MOJO_READ_DATA_FLAG_ALL_OR_NONE| set, it will either read exactly | |
| 674 // |*num_bytes| bytes of data or none. | |
| 675 // | |
| 676 // If flags has |MOJO_READ_DATA_FLAG_DISCARD| set, it discards up to | |
| 677 // |*num_bytes| (which again be a multiple of the element size) bytes of data, | |
| 678 // setting |*num_bytes| to the amount actually discarded. If flags has | |
| 679 // |MOJO_READ_DATA_FLAG_ALL_OR_NONE|, it will either discard exactly | |
| 680 // |*num_bytes| bytes of data or none. In this case, |MOJO_READ_DATA_FLAG_QUERY| | |
| 681 // must not be set, and |elements| is ignored (and should typically be set to | |
| 682 // null). | |
| 683 // | |
| 684 // If flags has |MOJO_READ_DATA_FLAG_QUERY| set, it queries the amount of data | |
| 685 // available, setting |*num_bytes| to the number of bytes available. In this | |
| 686 // case, |MOJO_READ_DATA_FLAG_DISCARD| must not be set, and | |
| 687 // |MOJO_READ_DATA_FLAG_ALL_OR_NONE| is ignored, as are |elements| and the input | |
| 688 // value of |*num_bytes|. | |
| 689 // | |
| 690 // Returns: | |
| 691 // |MOJO_RESULT_OK| on success (see above for a description of the different | |
| 692 // operations). | |
| 693 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., | |
| 694 // |data_pipe_consumer_handle| is invalid, the combination of flags in | |
| 695 // |flags| is invalid, etc.). | |
| 696 // |MOJO_RESULT_FAILED_PRECONDITION| if the data pipe producer handle has been | |
| 697 // closed and data (or the required amount of data) was not available to | |
| 698 // be read or discarded. | |
| 699 // |MOJO_RESULT_OUT_OF_RANGE| if |flags| has |MOJO_READ_DATA_FLAG_ALL_OR_NONE| | |
| 700 // set and the required amount of data is not available to be read or | |
| 701 // discarded (and the producer is still open). | |
| 702 // |MOJO_RESULT_BUSY| if there is a two-phase read ongoing with | |
| 703 // |data_pipe_consumer_handle| (i.e., |MojoBeginReadData()| has been | |
| 704 // called, but not yet the matching |MojoEndReadData()|). | |
| 705 // |MOJO_RESULT_SHOULD_WAIT| if there is no data to be read or discarded (and | |
| 706 // the producer is still open) and |flags| does *not* have | |
| 707 // |MOJO_READ_DATA_FLAG_ALL_OR_NONE| set. | |
| 708 MOJO_SYSTEM_EXPORT MojoResult MojoReadData( | |
| 709 MojoHandle data_pipe_consumer_handle, | |
| 710 void* elements, // Out. | |
| 711 uint32_t* num_bytes, // In/out. | |
| 712 MojoReadDataFlags flags); | |
| 713 | |
| 714 // Begins a two-phase read from the data pipe consumer given by | |
| 715 // |data_pipe_consumer_handle|. On success, |*buffer| will be a pointer from | |
| 716 // which the caller can read |*buffer_num_bytes| bytes of data. If flags has | |
| 717 // |MOJO_READ_DATA_FLAG_ALL_OR_NONE| set, then the output value | |
| 718 // |*buffer_num_bytes| will be at least as large as its input value, which must | |
| 719 // also be a multiple of the element size (if |MOJO_READ_DATA_FLAG_ALL_OR_NONE| | |
| 720 // is not set, the input value of |*buffer_num_bytes| is ignored). |flags| must | |
| 721 // not have |MOJO_READ_DATA_FLAG_DISCARD| or |MOJO_READ_DATA_FLAG_QUERY| set. | |
| 722 // | |
| 723 // During a two-phase read, |data_pipe_consumer_handle| is *not* readable. | |
| 724 // E.g., if another thread tries to read from it, it will get | |
| 725 // |MOJO_RESULT_BUSY|; that thread can then wait for |data_pipe_consumer_handle| | |
| 726 // to become readable again. | |
| 727 // | |
| 728 // Once the caller has finished reading data from |*buffer|, it should call | |
| 729 // |MojoEndReadData()| to specify the amount read and to complete the two-phase | |
| 730 // read. | |
| 731 // | |
| 732 // Returns: | |
| 733 // |MOJO_RESULT_OK| on success. | |
| 734 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., if | |
| 735 // |data_pipe_consumer_handle| is not a handle to a data pipe consumer, | |
| 736 // |buffer| or |buffer_num_bytes| does not look like a valid pointer, | |
| 737 // |flags| has |MOJO_READ_DATA_FLAG_ALL_OR_NONE| set and | |
| 738 // |*buffer_num_bytes| is not a multiple of the element size, or |flags| | |
| 739 // has invalid flags set). | |
| 740 // |MOJO_RESULT_FAILED_PRECONDITION| if the data pipe producer handle has been | |
| 741 // closed. | |
| 742 // |MOJO_RESULT_OUT_OF_RANGE| if |flags| has |MOJO_READ_DATA_FLAG_ALL_OR_NONE| | |
| 743 // set and the required amount of data (specified by |*buffer_num_bytes|) | |
| 744 // cannot be read from a contiguous buffer at this time. (Note that there | |
| 745 // may be the required amount of data, but it may not be contiguous.) | |
| 746 // |MOJO_RESULT_BUSY| if there is already a two-phase read ongoing with | |
| 747 // |data_pipe_consumer_handle| (i.e., |MojoBeginReadData()| has been | |
| 748 // called, but not yet the matching |MojoEndReadData()|). | |
| 749 // |MOJO_RESULT_SHOULD_WAIT| if no data can currently be read (and the | |
| 750 // producer is still open). | |
| 751 MOJO_SYSTEM_EXPORT MojoResult MojoBeginReadData( | |
| 752 MojoHandle data_pipe_consumer_handle, | |
| 753 const void** buffer, // Out. | |
| 754 uint32_t* buffer_num_bytes, // In/out. | |
| 755 MojoReadDataFlags flags); | |
| 756 | |
| 757 // Ends a two-phase read from the data pipe consumer given by | |
| 758 // |data_pipe_consumer_handle| that was begun by a call to |MojoBeginReadData()| | |
| 759 // on the same handle. |num_bytes_read| should indicate the amount of data | |
| 760 // actually read; it must be less than or equal to the value of | |
| 761 // |*buffer_num_bytes| output by |MojoBeginReadData()| and must be a multiple of | |
| 762 // the element size. | |
| 763 // | |
| 764 // On failure, the two-phase read (if any) is ended (so the handle may become | |
| 765 // readable again) but no data is "removed" from the data pipe. | |
| 766 // | |
| 767 // Returns: | |
| 768 // |MOJO_RESULT_OK| on success. | |
| 769 // |MOJO_RESULT_INVALID_ARGUMENT| if |data_pipe_consumer_handle| is not a | |
| 770 // handle to a data pipe consumer or |num_bytes_written| is invalid | |
| 771 // (greater than the maximum value provided by |MojoBeginReadData()| or | |
| 772 // not a multiple of the element size). | |
| 773 // |MOJO_RESULT_FAILED_PRECONDITION| if the data pipe consumer is not in a | |
| 774 // two-phase read (e.g., |MojoBeginReadData()| was not called or | |
| 775 // |MojoEndReadData()| has already been called). | |
| 776 MOJO_SYSTEM_EXPORT MojoResult MojoEndReadData( | |
| 777 MojoHandle data_pipe_consumer_handle, | |
| 778 uint32_t num_bytes_read); | |
| 779 | |
| 780 // Shared buffer: | |
| 781 | |
| 782 // TODO(vtl): General comments. | |
| 783 | |
| 784 // Creates a buffer that can be shared between applications (by duplicating the | |
| 785 // handle -- see |MojoDuplicateBufferHandle()| -- and passing it over a message | |
| 786 // pipe). To access the buffer, one must call |MojoMapBuffer()|. | |
| 787 // TODO(vtl): More. | |
| 788 MOJO_SYSTEM_EXPORT MojoResult MojoCreateSharedBuffer( | |
| 789 const struct MojoCreateSharedBufferOptions* options, // Optional. | |
| 790 uint64_t num_bytes, // In. | |
| 791 MojoHandle* shared_buffer_handle); // Out. | |
| 792 | |
| 793 // Duplicates the handle |buffer_handle| to a buffer. This creates another | |
| 794 // handle (returned in |*new_buffer_handle| on success), which can then be sent | |
| 795 // to another application over a message pipe, while retaining access to the | |
| 796 // |buffer_handle| (and any mappings that it may have). | |
| 797 // | |
| 798 // Note: We may add buffer types for which this operation is not supported. | |
| 799 // TODO(vtl): More. | |
| 800 MOJO_SYSTEM_EXPORT MojoResult MojoDuplicateBufferHandle( | |
| 801 MojoHandle buffer_handle, | |
| 802 const struct MojoDuplicateBufferHandleOptions* options, // Optional. | |
| 803 MojoHandle* new_buffer_handle); // Out. | |
| 804 | |
| 805 // Map the part (at offset |offset| of length |num_bytes|) of the buffer given | |
| 806 // by |buffer_handle| into memory. |offset + num_bytes| must be less than or | |
| 807 // equal to the size of the buffer. On success, |*buffer| points to memory with | |
| 808 // the requested part of the buffer. | |
| 809 // | |
| 810 // A single buffer handle may have multiple active mappings (possibly depending | |
| 811 // on the buffer type). The permissions (e.g., writable or executable) of the | |
| 812 // returned memory may depend on the properties of the buffer and properties | |
| 813 // attached to the buffer handle as well as |flags|. | |
| 814 // TODO(vtl): More. | |
| 815 MOJO_SYSTEM_EXPORT MojoResult MojoMapBuffer(MojoHandle buffer_handle, | |
| 816 uint64_t offset, | |
| 817 uint64_t num_bytes, | |
| 818 void** buffer, // Out. | |
| 819 MojoMapBufferFlags flags); | |
| 820 | |
| 821 // Unmap a buffer pointer that was mapped by |MojoMapBuffer()|. | |
| 822 // TODO(vtl): More. | |
| 823 MOJO_SYSTEM_EXPORT MojoResult MojoUnmapBuffer(void* buffer); // In. | |
| 824 | |
| 825 #ifdef __cplusplus | |
| 826 } // extern "C" | |
| 827 #endif | |
| 828 | |
| 829 #endif // MOJO_PUBLIC_SYSTEM_CORE_H_ | |
| OLD | NEW |
|---|
Chromium Code Reviews
Issue 213393002:
Mojo: Move public C system header files to mojo/public/c/system/. (Closed)
Base URL: svn://svn.chromium.org/chrome/trunk/src