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 35 typedef uint32_t MojoCreateDataPipeOptionsFlags; 36 37 #ifdef __cplusplus 38 const MojoCreateDataPipeOptionsFlags MOJO_CREATE_DATA_PIPE_OPTIONS_FLAG_NONE = 39 0; 40 const 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 49 MOJO_COMPILE_ASSERT(MOJO_ALIGNOF(int64_t) == 8, int64_t_has_weird_alignment); 50 struct 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 }; 56 MOJO_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 65 typedef uint32_t MojoWriteDataFlags; 66 67 #ifdef __cplusplus 68 const MojoWriteDataFlags MOJO_WRITE_DATA_FLAG_NONE = 0; 69 const 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 87 typedef uint32_t MojoReadDataFlags; 88 89 #ifdef __cplusplus 90 const MojoReadDataFlags MOJO_READ_DATA_FLAG_NONE = 0; 91 const MojoReadDataFlags MOJO_READ_DATA_FLAG_ALL_OR_NONE = 1 << 0; 92 const MojoReadDataFlags MOJO_READ_DATA_FLAG_DISCARD = 1 << 1; 93 const 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 102 extern "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., 125 // |*options| is 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|. 130 MOJO_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., 155 // |data_pipe_producer_dispatcher| is not a handle to a data pipe 156 // producer or |*num_bytes| is not a multiple of the data pipe's element 157 // 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? 171 MOJO_SYSTEM_EXPORT MojoResult 172 MojoWriteData(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., 201 // |data_pipe_producer_handle| is not a handle to a data pipe producer or 202 // flags has |MOJO_WRITE_DATA_FLAG_ALL_OR_NONE| set and 203 // |*buffer_num_bytes| is not a multiple of the element size). 204 // |MOJO_RESULT_FAILED_PRECONDITION| if the data pipe consumer handle has been 205 // closed. 206 // |MOJO_RESULT_OUT_OF_RANGE| if |flags| has 207 // |MOJO_WRITE_DATA_FLAG_ALL_OR_NONE| set and the required amount of data 208 // (specified by |*buffer_num_bytes|) cannot be written contiguously at 209 // this time. (Note that there may be space available for the required 210 // amount of data, but the "next" write position may not be large enough.) 211 // |MOJO_RESULT_BUSY| if there is already a two-phase write ongoing with 212 // |data_pipe_producer_handle| (i.e., |MojoBeginWriteData()| has been 213 // called, but not yet the matching |MojoEndWriteData()|). 214 // |MOJO_RESULT_SHOULD_WAIT| if no data can currently be written (and the 215 // consumer is still open). 216 MOJO_SYSTEM_EXPORT MojoResult 217 MojoBeginWriteData(MojoHandle data_pipe_producer_handle, 218 void** buffer, // Out. 219 uint32_t* buffer_num_bytes, // In/out. 220 MojoWriteDataFlags flags); 221 222 // Ends a two-phase write to the data pipe producer given by 223 // |data_pipe_producer_handle| that was begun by a call to 224 // |MojoBeginWriteData()| on the same handle. |num_bytes_written| should 225 // indicate the amount of data actually written; it must be less than or equal 226 // to the value of |*buffer_num_bytes| output by |MojoBeginWriteData()| and must 227 // be a multiple of the element size. The buffer given by |*buffer| from 228 // |MojoBeginWriteData()| must have been filled with exactly |num_bytes_written| 229 // bytes of data. 230 // 231 // On failure, the two-phase write (if any) is ended (so the handle may become 232 // writable again, if there's space available) but no data written to |*buffer| 233 // is "put into" the data pipe. 234 // 235 // Returns: 236 // |MOJO_RESULT_OK| on success. 237 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., 238 // |data_pipe_producer_handle| is not a handle to a data pipe producer or 239 // |num_bytes_written| is invalid (greater than the maximum value provided 240 // by |MojoBeginWriteData()| or not a multiple of the element size). 241 // |MOJO_RESULT_FAILED_PRECONDITION| if the data pipe producer is not in a 242 // two-phase write (e.g., |MojoBeginWriteData()| was not called or 243 // |MojoEndWriteData()| has already been called). 244 MOJO_SYSTEM_EXPORT MojoResult 245 MojoEndWriteData(MojoHandle data_pipe_producer_handle, 246 uint32_t num_bytes_written); 247 248 // Reads data from the data pipe consumer given by |data_pipe_consumer_handle|. 249 // May also be used to discard data or query the amount of data available. 250 // 251 // If |flags| has neither |MOJO_READ_DATA_FLAG_DISCARD| nor 252 // |MOJO_READ_DATA_FLAG_QUERY| set, this tries to read up to |*num_bytes| (which 253 // must be a multiple of the data pipe's element size) bytes of data to 254 // |elements| and set |*num_bytes| to the amount actually read. If flags has 255 // |MOJO_READ_DATA_FLAG_ALL_OR_NONE| set, it will either read exactly 256 // |*num_bytes| bytes of data or none. 257 // 258 // If flags has |MOJO_READ_DATA_FLAG_DISCARD| set, it discards up to 259 // |*num_bytes| (which again be a multiple of the element size) bytes of data, 260 // setting |*num_bytes| to the amount actually discarded. If flags has 261 // |MOJO_READ_DATA_FLAG_ALL_OR_NONE|, it will either discard exactly 262 // |*num_bytes| bytes of data or none. In this case, |MOJO_READ_DATA_FLAG_QUERY| 263 // must not be set, and |elements| is ignored (and should typically be set to 264 // null). 265 // 266 // If flags has |MOJO_READ_DATA_FLAG_QUERY| set, it queries the amount of data 267 // available, setting |*num_bytes| to the number of bytes available. In this 268 // case, |MOJO_READ_DATA_FLAG_DISCARD| must not be set, and 269 // |MOJO_READ_DATA_FLAG_ALL_OR_NONE| is ignored, as are |elements| and the input 270 // value of |*num_bytes|. 271 // 272 // Returns: 273 // |MOJO_RESULT_OK| on success (see above for a description of the different 274 // operations). 275 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., 276 // |data_pipe_consumer_handle| is invalid, the combination of flags in 277 // |flags| is invalid, etc.). 278 // |MOJO_RESULT_FAILED_PRECONDITION| if the data pipe producer handle has been 279 // closed and data (or the required amount of data) was not available to 280 // be read or discarded. 281 // |MOJO_RESULT_OUT_OF_RANGE| if |flags| has |MOJO_READ_DATA_FLAG_ALL_OR_NONE| 282 // set and the required amount of data is not available to be read or 283 // discarded (and the producer is still open). 284 // |MOJO_RESULT_BUSY| if there is a two-phase read ongoing with 285 // |data_pipe_consumer_handle| (i.e., |MojoBeginReadData()| has been 286 // called, but not yet the matching |MojoEndReadData()|). 287 // |MOJO_RESULT_SHOULD_WAIT| if there is no data to be read or discarded (and 288 // the producer is still open) and |flags| does *not* have 289 // |MOJO_READ_DATA_FLAG_ALL_OR_NONE| set. 290 MOJO_SYSTEM_EXPORT MojoResult MojoReadData(MojoHandle data_pipe_consumer_handle, 291 void* elements, // Out. 292 uint32_t* num_bytes, // In/out. 293 MojoReadDataFlags flags); 294 295 // Begins a two-phase read from the data pipe consumer given by 296 // |data_pipe_consumer_handle|. On success, |*buffer| will be a pointer from 297 // which the caller can read |*buffer_num_bytes| bytes of data. If flags has 298 // |MOJO_READ_DATA_FLAG_ALL_OR_NONE| set, then the output value 299 // |*buffer_num_bytes| will be at least as large as its input value, which must 300 // also be a multiple of the element size (if |MOJO_READ_DATA_FLAG_ALL_OR_NONE| 301 // is not set, the input value of |*buffer_num_bytes| is ignored). |flags| must 302 // not have |MOJO_READ_DATA_FLAG_DISCARD| or |MOJO_READ_DATA_FLAG_QUERY| set. 303 // 304 // During a two-phase read, |data_pipe_consumer_handle| is *not* readable. 305 // E.g., if another thread tries to read from it, it will get 306 // |MOJO_RESULT_BUSY|; that thread can then wait for |data_pipe_consumer_handle| 307 // to become readable again. 308 // 309 // Once the caller has finished reading data from |*buffer|, it should call 310 // |MojoEndReadData()| to specify the amount read and to complete the two-phase 311 // read. 312 // 313 // Returns: 314 // |MOJO_RESULT_OK| on success. 315 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., 316 // |data_pipe_consumer_handle| is not a handle to a data pipe consumer, 317 // |flags| has |MOJO_READ_DATA_FLAG_ALL_OR_NONE| set and 318 // |*buffer_num_bytes| is not a multiple of the element size, or |flags| 319 // has invalid flags set). 320 // |MOJO_RESULT_FAILED_PRECONDITION| if the data pipe producer handle has been 321 // closed. 322 // |MOJO_RESULT_OUT_OF_RANGE| if |flags| has |MOJO_READ_DATA_FLAG_ALL_OR_NONE| 323 // set and the required amount of data (specified by |*buffer_num_bytes|) 324 // cannot be read from a contiguous buffer at this time. (Note that there 325 // may be the required amount of data, but it may not be contiguous.) 326 // |MOJO_RESULT_BUSY| if there is already a two-phase read ongoing with 327 // |data_pipe_consumer_handle| (i.e., |MojoBeginReadData()| has been 328 // called, but not yet the matching |MojoEndReadData()|). 329 // |MOJO_RESULT_SHOULD_WAIT| if no data can currently be read (and the 330 // producer is still open). 331 MOJO_SYSTEM_EXPORT MojoResult 332 MojoBeginReadData(MojoHandle data_pipe_consumer_handle, 333 const void** buffer, // Out. 334 uint32_t* buffer_num_bytes, // In/out. 335 MojoReadDataFlags flags); 336 337 // Ends a two-phase read from the data pipe consumer given by 338 // |data_pipe_consumer_handle| that was begun by a call to |MojoBeginReadData()| 339 // on the same handle. |num_bytes_read| should indicate the amount of data 340 // actually read; it must be less than or equal to the value of 341 // |*buffer_num_bytes| output by |MojoBeginReadData()| and must be a multiple of 342 // the element size. 343 // 344 // On failure, the two-phase read (if any) is ended (so the handle may become 345 // readable again) but no data is "removed" from the data pipe. 346 // 347 // Returns: 348 // |MOJO_RESULT_OK| on success. 349 // |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g., 350 // |data_pipe_consumer_handle| is not a handle to a data pipe consumer or 351 // |num_bytes_written| is greater than the maximum value provided by 352 // |MojoBeginReadData()| or not a multiple of the element size). 353 // |MOJO_RESULT_FAILED_PRECONDITION| if the data pipe consumer is not in a 354 // two-phase read (e.g., |MojoBeginReadData()| was not called or 355 // |MojoEndReadData()| has already been called). 356 MOJO_SYSTEM_EXPORT MojoResult 357 MojoEndReadData(MojoHandle data_pipe_consumer_handle, 358 uint32_t num_bytes_read); 359 360 #ifdef __cplusplus 361 } // extern "C" 362 #endif 363 364 #endif // MOJO_PUBLIC_C_SYSTEM_DATA_PIPE_H_ 365