data_pipe.h revision 46d4c2bc3267f3f028f39e7e311b0f89aba2e4fd
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/constants and functions specific to data pipes. 6// 7// Note: This header should be compilable as C. 8 9#ifndef MOJO_PUBLIC_C_SYSTEM_DATA_PIPE_H_ 10#define MOJO_PUBLIC_C_SYSTEM_DATA_PIPE_H_ 11 12#include "mojo/public/c/system/macros.h" 13#include "mojo/public/c/system/system_export.h" 14#include "mojo/public/c/system/types.h" 15 16// |MojoCreateDataPipeOptions|: Used to specify creation parameters for a data 17// pipe to |MojoCreateDataPipe()|. 18// |uint32_t struct_size|: Set to the size of the |MojoCreateDataPipeOptions| 19// struct. (Used to allow for future extensions.) 20// |MojoCreateDataPipeOptionsFlags flags|: Used to specify different modes of 21// operation. 22// |MOJO_CREATE_DATA_PIPE_OPTIONS_FLAG_NONE|: No flags; default mode. 23// |MOJO_CREATE_DATA_PIPE_OPTIONS_FLAG_MAY_DISCARD|: May discard data for 24// whatever reason; best-effort delivery. In particular, if the capacity 25// is reached, old data may be discard to make room for new data. 26// |uint32_t element_num_bytes|: The size of an element, in bytes. All 27// transactions and buffers will consist of an integral number of 28// elements. Must be nonzero. 29// |uint32_t capacity_num_bytes|: The capacity of the data pipe, in number of 30// bytes; must be a multiple of |element_num_bytes|. The data pipe will 31// always be able to queue AT LEAST this much data. Set to zero to opt for 32// a system-dependent automatically-calculated capacity (which will always 33// be at least one element). 34 35typedef uint32_t MojoCreateDataPipeOptionsFlags; 36 37#ifdef __cplusplus 38const MojoCreateDataPipeOptionsFlags 39 MOJO_CREATE_DATA_PIPE_OPTIONS_FLAG_NONE = 0; 40const MojoCreateDataPipeOptionsFlags 41 MOJO_CREATE_DATA_PIPE_OPTIONS_FLAG_MAY_DISCARD = 1 << 0; 42#else 43#define MOJO_CREATE_DATA_PIPE_OPTIONS_FLAG_NONE \ 44 ((MojoCreateDataPipeOptionsFlags) 0) 45#define MOJO_CREATE_DATA_PIPE_OPTIONS_FLAG_MAY_DISCARD \ 46 ((MojoCreateDataPipeOptionsFlags) 1 << 0) 47#endif 48 49MOJO_COMPILE_ASSERT(MOJO_ALIGNOF(int64_t) == 8, int64_t_has_weird_alignment); 50struct MOJO_ALIGNAS(8) MojoCreateDataPipeOptions { 51 uint32_t struct_size; 52 MojoCreateDataPipeOptionsFlags flags; 53 uint32_t element_num_bytes; 54 uint32_t capacity_num_bytes; 55}; 56MOJO_COMPILE_ASSERT(sizeof(MojoCreateDataPipeOptions) == 16, 57 MojoCreateDataPipeOptions_has_wrong_size); 58 59// |MojoWriteDataFlags|: Used to specify different modes to |MojoWriteData()| 60// and |MojoBeginWriteData()|. 61// |MOJO_WRITE_DATA_FLAG_NONE| - No flags; default mode. 62// |MOJO_WRITE_DATA_FLAG_ALL_OR_NONE| - Write either all the elements 63// requested or none of them. 64 65typedef uint32_t MojoWriteDataFlags; 66 67#ifdef __cplusplus 68const MojoWriteDataFlags MOJO_WRITE_DATA_FLAG_NONE = 0; 69const MojoWriteDataFlags MOJO_WRITE_DATA_FLAG_ALL_OR_NONE = 1 << 0; 70#else 71#define MOJO_WRITE_DATA_FLAG_NONE ((MojoWriteDataFlags) 0) 72#define MOJO_WRITE_DATA_FLAG_ALL_OR_NONE ((MojoWriteDataFlags) 1 << 0) 73#endif 74 75// |MojoReadDataFlags|: Used to specify different modes to |MojoReadData()| and 76// |MojoBeginReadData()|. 77// |MOJO_READ_DATA_FLAG_NONE| - No flags; default mode. 78// |MOJO_READ_DATA_FLAG_ALL_OR_NONE| - Read (or discard) either the requested 79// number of elements or none. 80// |MOJO_READ_DATA_FLAG_DISCARD| - Discard (up to) the requested number of 81// elements. 82// |MOJO_READ_DATA_FLAG_QUERY| - Query the number of elements available to 83// read. For use with |MojoReadData()| only. Mutually exclusive with 84// |MOJO_READ_DATA_FLAG_DISCARD| and |MOJO_READ_DATA_FLAG_ALL_OR_NONE| is 85// ignored if this flag is set. 86 87typedef uint32_t MojoReadDataFlags; 88 89#ifdef __cplusplus 90const MojoReadDataFlags MOJO_READ_DATA_FLAG_NONE = 0; 91const MojoReadDataFlags MOJO_READ_DATA_FLAG_ALL_OR_NONE = 1 << 0; 92const MojoReadDataFlags MOJO_READ_DATA_FLAG_DISCARD = 1 << 1; 93const MojoReadDataFlags MOJO_READ_DATA_FLAG_QUERY = 1 << 2; 94#else 95#define MOJO_READ_DATA_FLAG_NONE ((MojoReadDataFlags) 0) 96#define MOJO_READ_DATA_FLAG_ALL_OR_NONE ((MojoReadDataFlags) 1 << 0) 97#define MOJO_READ_DATA_FLAG_DISCARD ((MojoReadDataFlags) 1 << 1) 98#define MOJO_READ_DATA_FLAG_QUERY ((MojoReadDataFlags) 1 << 2) 99#endif 100 101#ifdef __cplusplus 102extern "C" { 103#endif 104 105// Note: See the comment in functions.h about the meaning of the "optional" 106// label for pointer parameters. 107 108// Creates a data pipe, which is a unidirectional communication channel for 109// unframed data, with the given options. Data is unframed, but must come as 110// (multiples of) discrete elements, of the size given in |options|. See 111// |MojoCreateDataPipeOptions| for a description of the different options 112// available for data pipes. 113// 114// |options| may be set to null for a data pipe with the default options (which 115// will have an element size of one byte and have some system-dependent 116// capacity). 117// 118// On success, |*data_pipe_producer_handle| will be set to the handle for the 119// producer and |*data_pipe_consumer_handle| will be set to the handle for the 120// consumer. (On failure, they are not modified.) 121// 122// Returns: 123// |MOJO_RESULT_OK| on success. 124// |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., if 125// |*options| is invalid or one of the handle pointers looks invalid). 126// |MOJO_RESULT_RESOURCE_EXHAUSTED| if a process/system/quota/etc. limit has 127// been reached (e.g., if the requested capacity was too large, or if the 128// maximum number of handles was exceeded). 129// |MOJO_RESULT_UNIMPLEMENTED| if an unsupported flag was set in |*options|. 130MOJO_SYSTEM_EXPORT MojoResult MojoCreateDataPipe( 131 const struct MojoCreateDataPipeOptions* options, // Optional. 132 MojoHandle* data_pipe_producer_handle, // Out. 133 MojoHandle* data_pipe_consumer_handle); // Out. 134 135// Writes the given data to the data pipe producer given by 136// |data_pipe_producer_handle|. |elements| points to data of size |*num_bytes|; 137// |*num_bytes| should be a multiple of the data pipe's element size. If 138// |MOJO_WRITE_DATA_FLAG_ALL_OR_NONE| is set in |flags|, either all the data 139// will be written or none is. 140// 141// On success, |*num_bytes| is set to the amount of data that was actually 142// written. 143// 144// Note: If the data pipe has the "may discard" option flag (specified on 145// creation), this will discard as much data as required to write the given 146// data, starting with the earliest written data that has not been consumed. 147// However, even with "may discard", if |*num_bytes| is greater than the data 148// pipe's capacity (and |MOJO_WRITE_DATA_FLAG_ALL_OR_NONE| is not set), this 149// will write the maximum amount possible (namely, the data pipe's capacity) and 150// set |*num_bytes| to that amount. It will *not* discard data from |elements|. 151// 152// Returns: 153// |MOJO_RESULT_OK| on success. 154// |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., if 155// |data_pipe_producer_dispatcher| is not a handle to a data pipe 156// producer, |elements| does not look like a valid pointer, or 157// |*num_bytes| is not a multiple of the data pipe's element size). 158// |MOJO_RESULT_FAILED_PRECONDITION| if the data pipe consumer handle has been 159// closed. 160// |MOJO_RESULT_OUT_OF_RANGE| if |flags| has 161// |MOJO_WRITE_DATA_FLAG_ALL_OR_NONE| set and the required amount of data 162// (specified by |*num_bytes|) could not be written. 163// |MOJO_RESULT_BUSY| if there is a two-phase write ongoing with 164// |data_pipe_producer_handle| (i.e., |MojoBeginWriteData()| has been 165// called, but not yet the matching |MojoEndWriteData()|). 166// |MOJO_RESULT_SHOULD_WAIT| if no data can currently be written (and the 167// consumer is still open) and |flags| does *not* have 168// |MOJO_WRITE_DATA_FLAG_ALL_OR_NONE| set. 169// 170// TODO(vtl): Should there be a way of querying how much data can be written? 171MOJO_SYSTEM_EXPORT MojoResult MojoWriteData( 172 MojoHandle data_pipe_producer_handle, 173 const void* elements, 174 uint32_t* num_bytes, // In/out. 175 MojoWriteDataFlags flags); 176 177// Begins a two-phase write to the data pipe producer given by 178// |data_pipe_producer_handle|. On success, |*buffer| will be a pointer to which 179// the caller can write |*buffer_num_bytes| bytes of data. If flags has 180// |MOJO_WRITE_DATA_FLAG_ALL_OR_NONE| set, then the output value 181// |*buffer_num_bytes| will be at least as large as its input value, which must 182// also be a multiple of the element size (if |MOJO_WRITE_DATA_FLAG_ALL_OR_NONE| 183// is not set, the input value of |*buffer_num_bytes| is ignored). 184// 185// During a two-phase write, |data_pipe_producer_handle| is *not* writable. 186// E.g., if another thread tries to write to it, it will get |MOJO_RESULT_BUSY|; 187// that thread can then wait for |data_pipe_producer_handle| to become writable 188// again. 189// 190// Once the caller has finished writing data to |*buffer|, it should call 191// |MojoEndWriteData()| to specify the amount written and to complete the 192// two-phase write. 193// 194// Note: If the data pipe has the "may discard" option flag (specified on 195// creation) and |flags| has |MOJO_WRITE_DATA_FLAG_ALL_OR_NONE| set, this may 196// discard some data. 197// 198// Returns: 199// |MOJO_RESULT_OK| on success. 200// |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., if 201// |data_pipe_producer_handle| is not a handle to a data pipe producer, 202// |buffer| or |buffer_num_bytes| does not look like a valid pointer, or 203// flags has |MOJO_WRITE_DATA_FLAG_ALL_OR_NONE| set and 204// |*buffer_num_bytes| is not a multiple of the element size). 205// |MOJO_RESULT_FAILED_PRECONDITION| if the data pipe consumer handle has been 206// closed. 207// |MOJO_RESULT_OUT_OF_RANGE| if |flags| has 208// |MOJO_WRITE_DATA_FLAG_ALL_OR_NONE| set and the required amount of data 209// (specified by |*buffer_num_bytes|) cannot be written contiguously at 210// this time. (Note that there may be space available for the required 211// amount of data, but the "next" write position may not be large enough.) 212// |MOJO_RESULT_BUSY| if there is already a two-phase write ongoing with 213// |data_pipe_producer_handle| (i.e., |MojoBeginWriteData()| has been 214// called, but not yet the matching |MojoEndWriteData()|). 215// |MOJO_RESULT_SHOULD_WAIT| if no data can currently be written (and the 216// consumer is still open). 217MOJO_SYSTEM_EXPORT MojoResult MojoBeginWriteData( 218 MojoHandle data_pipe_producer_handle, 219 void** buffer, // Out. 220 uint32_t* buffer_num_bytes, // In/out. 221 MojoWriteDataFlags flags); 222 223// Ends a two-phase write to the data pipe producer given by 224// |data_pipe_producer_handle| that was begun by a call to 225// |MojoBeginWriteData()| on the same handle. |num_bytes_written| should 226// indicate the amount of data actually written; it must be less than or equal 227// to the value of |*buffer_num_bytes| output by |MojoBeginWriteData()| and must 228// be a multiple of the element size. The buffer given by |*buffer| from 229// |MojoBeginWriteData()| must have been filled with exactly |num_bytes_written| 230// bytes of data. 231// 232// On failure, the two-phase write (if any) is ended (so the handle may become 233// writable again, if there's space available) but no data written to |*buffer| 234// is "put into" the data pipe. 235// 236// Returns: 237// |MOJO_RESULT_OK| on success. 238// |MOJO_RESULT_INVALID_ARGUMENT| if |data_pipe_producer_handle| is not a 239// handle to a data pipe producer or |num_bytes_written| is invalid 240// (greater than the maximum value provided by |MojoBeginWriteData()| or 241// not a multiple of the element size). 242// |MOJO_RESULT_FAILED_PRECONDITION| if the data pipe producer is not in a 243// two-phase write (e.g., |MojoBeginWriteData()| was not called or 244// |MojoEndWriteData()| has already been called). 245MOJO_SYSTEM_EXPORT MojoResult MojoEndWriteData( 246 MojoHandle data_pipe_producer_handle, 247 uint32_t num_bytes_written); 248 249// Reads data from the data pipe consumer given by |data_pipe_consumer_handle|. 250// May also be used to discard data or query the amount of data available. 251// 252// If |flags| has neither |MOJO_READ_DATA_FLAG_DISCARD| nor 253// |MOJO_READ_DATA_FLAG_QUERY| set, this tries to read up to |*num_bytes| (which 254// must be a multiple of the data pipe's element size) bytes of data to 255// |elements| and set |*num_bytes| to the amount actually read. If flags has 256// |MOJO_READ_DATA_FLAG_ALL_OR_NONE| set, it will either read exactly 257// |*num_bytes| bytes of data or none. 258// 259// If flags has |MOJO_READ_DATA_FLAG_DISCARD| set, it discards up to 260// |*num_bytes| (which again be a multiple of the element size) bytes of data, 261// setting |*num_bytes| to the amount actually discarded. If flags has 262// |MOJO_READ_DATA_FLAG_ALL_OR_NONE|, it will either discard exactly 263// |*num_bytes| bytes of data or none. In this case, |MOJO_READ_DATA_FLAG_QUERY| 264// must not be set, and |elements| is ignored (and should typically be set to 265// null). 266// 267// If flags has |MOJO_READ_DATA_FLAG_QUERY| set, it queries the amount of data 268// available, setting |*num_bytes| to the number of bytes available. In this 269// case, |MOJO_READ_DATA_FLAG_DISCARD| must not be set, and 270// |MOJO_READ_DATA_FLAG_ALL_OR_NONE| is ignored, as are |elements| and the input 271// value of |*num_bytes|. 272// 273// Returns: 274// |MOJO_RESULT_OK| on success (see above for a description of the different 275// operations). 276// |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., 277// |data_pipe_consumer_handle| is invalid, the combination of flags in 278// |flags| is invalid, etc.). 279// |MOJO_RESULT_FAILED_PRECONDITION| if the data pipe producer handle has been 280// closed and data (or the required amount of data) was not available to 281// be read or discarded. 282// |MOJO_RESULT_OUT_OF_RANGE| if |flags| has |MOJO_READ_DATA_FLAG_ALL_OR_NONE| 283// set and the required amount of data is not available to be read or 284// discarded (and the producer is still open). 285// |MOJO_RESULT_BUSY| if there is a two-phase read ongoing with 286// |data_pipe_consumer_handle| (i.e., |MojoBeginReadData()| has been 287// called, but not yet the matching |MojoEndReadData()|). 288// |MOJO_RESULT_SHOULD_WAIT| if there is no data to be read or discarded (and 289// the producer is still open) and |flags| does *not* have 290// |MOJO_READ_DATA_FLAG_ALL_OR_NONE| set. 291MOJO_SYSTEM_EXPORT MojoResult MojoReadData( 292 MojoHandle data_pipe_consumer_handle, 293 void* elements, // Out. 294 uint32_t* num_bytes, // In/out. 295 MojoReadDataFlags flags); 296 297// Begins a two-phase read from the data pipe consumer given by 298// |data_pipe_consumer_handle|. On success, |*buffer| will be a pointer from 299// which the caller can read |*buffer_num_bytes| bytes of data. If flags has 300// |MOJO_READ_DATA_FLAG_ALL_OR_NONE| set, then the output value 301// |*buffer_num_bytes| will be at least as large as its input value, which must 302// also be a multiple of the element size (if |MOJO_READ_DATA_FLAG_ALL_OR_NONE| 303// is not set, the input value of |*buffer_num_bytes| is ignored). |flags| must 304// not have |MOJO_READ_DATA_FLAG_DISCARD| or |MOJO_READ_DATA_FLAG_QUERY| set. 305// 306// During a two-phase read, |data_pipe_consumer_handle| is *not* readable. 307// E.g., if another thread tries to read from it, it will get 308// |MOJO_RESULT_BUSY|; that thread can then wait for |data_pipe_consumer_handle| 309// to become readable again. 310// 311// Once the caller has finished reading data from |*buffer|, it should call 312// |MojoEndReadData()| to specify the amount read and to complete the two-phase 313// read. 314// 315// Returns: 316// |MOJO_RESULT_OK| on success. 317// |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., if 318// |data_pipe_consumer_handle| is not a handle to a data pipe consumer, 319// |buffer| or |buffer_num_bytes| does not look like a valid pointer, 320// |flags| has |MOJO_READ_DATA_FLAG_ALL_OR_NONE| set and 321// |*buffer_num_bytes| is not a multiple of the element size, or |flags| 322// has invalid flags set). 323// |MOJO_RESULT_FAILED_PRECONDITION| if the data pipe producer handle has been 324// closed. 325// |MOJO_RESULT_OUT_OF_RANGE| if |flags| has |MOJO_READ_DATA_FLAG_ALL_OR_NONE| 326// set and the required amount of data (specified by |*buffer_num_bytes|) 327// cannot be read from a contiguous buffer at this time. (Note that there 328// may be the required amount of data, but it may not be contiguous.) 329// |MOJO_RESULT_BUSY| if there is already a two-phase read ongoing with 330// |data_pipe_consumer_handle| (i.e., |MojoBeginReadData()| has been 331// called, but not yet the matching |MojoEndReadData()|). 332// |MOJO_RESULT_SHOULD_WAIT| if no data can currently be read (and the 333// producer is still open). 334MOJO_SYSTEM_EXPORT MojoResult MojoBeginReadData( 335 MojoHandle data_pipe_consumer_handle, 336 const void** buffer, // Out. 337 uint32_t* buffer_num_bytes, // In/out. 338 MojoReadDataFlags flags); 339 340// Ends a two-phase read from the data pipe consumer given by 341// |data_pipe_consumer_handle| that was begun by a call to |MojoBeginReadData()| 342// on the same handle. |num_bytes_read| should indicate the amount of data 343// actually read; it must be less than or equal to the value of 344// |*buffer_num_bytes| output by |MojoBeginReadData()| and must be a multiple of 345// the element size. 346// 347// On failure, the two-phase read (if any) is ended (so the handle may become 348// readable again) but no data is "removed" from the data pipe. 349// 350// Returns: 351// |MOJO_RESULT_OK| on success. 352// |MOJO_RESULT_INVALID_ARGUMENT| if |data_pipe_consumer_handle| is not a 353// handle to a data pipe consumer or |num_bytes_written| is invalid 354// (greater than the maximum value provided by |MojoBeginReadData()| or 355// not a multiple of the element size). 356// |MOJO_RESULT_FAILED_PRECONDITION| if the data pipe consumer is not in a 357// two-phase read (e.g., |MojoBeginReadData()| was not called or 358// |MojoEndReadData()| has already been called). 359MOJO_SYSTEM_EXPORT MojoResult MojoEndReadData( 360 MojoHandle data_pipe_consumer_handle, 361 uint32_t num_bytes_read); 362 363#ifdef __cplusplus 364} // extern "C" 365#endif 366 367#endif // MOJO_PUBLIC_C_SYSTEM_DATA_PIPE_H_ 368