blob: aaeafcf21e76dfd8a565d330e02ed08eb152f9eb [file] [log] [blame]
// Copyright 2014 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
// This file contains types/constants and functions specific to data pipes.
//
// Note: This header should be compilable as C.
#ifndef MOJO_PUBLIC_C_SYSTEM_DATA_PIPE_H_
#define MOJO_PUBLIC_C_SYSTEM_DATA_PIPE_H_
#include <stdint.h>
#include "mojo/public/c/system/macros.h"
#include "mojo/public/c/system/system_export.h"
#include "mojo/public/c/system/types.h"
// |MojoCreateDataPipeOptions|: Used to specify creation parameters for a data
// pipe to |MojoCreateDataPipe()|.
//
// |uint32_t struct_size|: Set to the size of the |MojoCreateDataPipeOptions|
// struct. (Used to allow for future extensions.)
//
// |MojoCreateDataPipeOptionsFlags flags|: Used to specify different modes of
// operation. May be some combination of the following values:
//
// |MOJO_CREATE_DATA_PIPE_OPTIONS_FLAG_NONE|: No flags; default mode.
//
// |uint32_t element_num_bytes|: The size of an element, in bytes. All
// transactions and buffers will consist of an integral number of
// elements. Must be nonzero.
//
// |uint32_t capacity_num_bytes|: The capacity of the data pipe, in number of
// bytes; must be a multiple of |element_num_bytes|. The data pipe will
// always be able to queue AT LEAST this much data. Set to zero to opt for
// a system-dependent automatically-calculated capacity (which will always
// be at least one element).
typedef uint32_t MojoCreateDataPipeOptionsFlags;
#ifdef __cplusplus
const MojoCreateDataPipeOptionsFlags MOJO_CREATE_DATA_PIPE_OPTIONS_FLAG_NONE =
0;
#else
#define MOJO_CREATE_DATA_PIPE_OPTIONS_FLAG_NONE \
((MojoCreateDataPipeOptionsFlags)0)
#endif
MOJO_STATIC_ASSERT(MOJO_ALIGNOF(int64_t) == 8, "int64_t has weird alignment");
struct MOJO_ALIGNAS(8) MojoCreateDataPipeOptions {
MOJO_ALIGNAS(4) uint32_t struct_size;
MOJO_ALIGNAS(4) MojoCreateDataPipeOptionsFlags flags;
MOJO_ALIGNAS(4) uint32_t element_num_bytes;
MOJO_ALIGNAS(4) uint32_t capacity_num_bytes;
};
MOJO_STATIC_ASSERT(sizeof(MojoCreateDataPipeOptions) == 16,
"MojoCreateDataPipeOptions has wrong size");
// |MojoWriteDataFlags|: Used to specify different modes to |MojoWriteData()|
// and |MojoBeginWriteData()|. May be some combination of the following values:
//
// |MOJO_WRITE_DATA_FLAG_NONE| - No flags; default mode.
// |MOJO_WRITE_DATA_FLAG_ALL_OR_NONE| - Write either all the elements
// requested or none of them.
typedef uint32_t MojoWriteDataFlags;
#ifdef __cplusplus
const MojoWriteDataFlags MOJO_WRITE_DATA_FLAG_NONE = 0;
const MojoWriteDataFlags MOJO_WRITE_DATA_FLAG_ALL_OR_NONE = 1 << 0;
#else
#define MOJO_WRITE_DATA_FLAG_NONE ((MojoWriteDataFlags)0)
#define MOJO_WRITE_DATA_FLAG_ALL_OR_NONE ((MojoWriteDataFlags)1 << 0)
#endif
// |MojoReadDataFlags|: Used to specify different modes to |MojoReadData()| and
// |MojoBeginReadData()|. May be some combination of the following values:
//
// |MOJO_READ_DATA_FLAG_NONE| - No flags; default mode.
// |MOJO_READ_DATA_FLAG_ALL_OR_NONE| - Read (or discard) either the requested
// number of elements or none. For use with |MojoReadData()| only.
// |MOJO_READ_DATA_FLAG_DISCARD| - Discard (up to) the requested number of
// elements. For use with |MojoReadData()| only.
// |MOJO_READ_DATA_FLAG_QUERY| - Query the number of elements available to
// read. For use with |MojoReadData()| only. Mutually exclusive with
// |MOJO_READ_DATA_FLAG_DISCARD|, and |MOJO_READ_DATA_FLAG_ALL_OR_NONE|
// is ignored if this flag is set.
// |MOJO_READ_DATA_FLAG_PEEK| - Read elements without removing them. For use
// with |MojoReadData()| only. Mutually exclusive with
// |MOJO_READ_DATA_FLAG_DISCARD| and |MOJO_READ_DATA_FLAG_QUERY|.
typedef uint32_t MojoReadDataFlags;
#ifdef __cplusplus
const MojoReadDataFlags MOJO_READ_DATA_FLAG_NONE = 0;
const MojoReadDataFlags MOJO_READ_DATA_FLAG_ALL_OR_NONE = 1 << 0;
const MojoReadDataFlags MOJO_READ_DATA_FLAG_DISCARD = 1 << 1;
const MojoReadDataFlags MOJO_READ_DATA_FLAG_QUERY = 1 << 2;
const MojoReadDataFlags MOJO_READ_DATA_FLAG_PEEK = 1 << 3;
#else
#define MOJO_READ_DATA_FLAG_NONE ((MojoReadDataFlags)0)
#define MOJO_READ_DATA_FLAG_ALL_OR_NONE ((MojoReadDataFlags)1 << 0)
#define MOJO_READ_DATA_FLAG_DISCARD ((MojoReadDataFlags)1 << 1)
#define MOJO_READ_DATA_FLAG_QUERY ((MojoReadDataFlags)1 << 2)
#define MOJO_READ_DATA_FLAG_PEEK ((MojoReadDataFlags)1 << 3)
#endif
#ifdef __cplusplus
extern "C" {
#endif
// Note: See the comment in functions.h about the meaning of the "optional"
// label for pointer parameters.
// Creates a data pipe, which is a unidirectional communication channel for
// unframed data. Data must be read and written in multiples of discrete
// discrete elements of size given in |options|.
//
// See |MojoCreateDataPipeOptions| for a description of the different options
// available for data pipes.
//
// |options| may be set to null for a data pipe with the default options (which
// will have an element size of one byte and have some system-dependent
// capacity).
//
// On success, |*data_pipe_producer_handle| will be set to the handle for the
// producer and |*data_pipe_consumer_handle| will be set to the handle for the
// consumer. On failure they are not modified.
//
// Returns:
// |MOJO_RESULT_OK| on success.
// |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g.,
// |*options| is invalid).
// |MOJO_RESULT_RESOURCE_EXHAUSTED| if a process/system/quota/etc. limit has
// been reached (e.g., if the requested capacity was too large, or if the
// maximum number of handles was exceeded).
// |MOJO_RESULT_UNIMPLEMENTED| if an unsupported flag was set in |*options|.
MOJO_SYSTEM_EXPORT MojoResult MojoCreateDataPipe(
const struct MojoCreateDataPipeOptions* options, // Optional.
MojoHandle* data_pipe_producer_handle, // Out.
MojoHandle* data_pipe_consumer_handle); // Out.
// Writes the data pipe producer given by |data_pipe_producer_handle|.
//
// |elements| points to data of size |*num_bytes|; |*num_bytes| must be a
// multiple of the data pipe's element size. If
// |MOJO_WRITE_DATA_FLAG_ALL_OR_NONE| is set in |flags|, either all the data
// is written (if enough write capacity is available) or none is.
//
// On success |*num_bytes| is set to the amount of data that was actually
// written. On failure it is unmodified.
//
// Returns:
// |MOJO_RESULT_OK| on success.
// |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g.,
// |data_pipe_producer_dispatcher| is not a handle to a data pipe
// producer or |*num_bytes| is not a multiple of the data pipe's element
// size.)
// |MOJO_RESULT_FAILED_PRECONDITION| if the data pipe consumer handle has been
// closed.
// |MOJO_RESULT_OUT_OF_RANGE| if |flags| has
// |MOJO_WRITE_DATA_FLAG_ALL_OR_NONE| set and the required amount of data
// (specified by |*num_bytes|) could not be written.
// |MOJO_RESULT_BUSY| if there is a two-phase write ongoing with
// |data_pipe_producer_handle| (i.e., |MojoBeginWriteData()| has been
// called, but not yet the matching |MojoEndWriteData()|).
// |MOJO_RESULT_SHOULD_WAIT| if no data can currently be written (and the
// consumer is still open) and |flags| does *not* have
// |MOJO_WRITE_DATA_FLAG_ALL_OR_NONE| set.
MOJO_SYSTEM_EXPORT MojoResult
MojoWriteData(MojoHandle data_pipe_producer_handle,
const void* elements,
uint32_t* num_bytes, // In/out.
MojoWriteDataFlags flags);
// Begins a two-phase write to the data pipe producer given by
// |data_pipe_producer_handle|. On success |*buffer| will be a pointer to which
// the caller can write up to |*buffer_num_bytes| bytes of data.
//
// During a two-phase write, |data_pipe_producer_handle| is *not* writable.
// If another caller tries to write to it by calling |MojoWriteData()| or
// |MojoBeginWriteData()|, their request will fail with |MOJO_RESULT_BUSY|.
//
// If |MojoBeginWriteData()| returns MOJO_RESULT_OK and once the caller has
// finished writing data to |*buffer|, |MojoEndWriteData()| must be called to
// indicate the amount of data actually written and to complete the two-phase
// write operation. |MojoEndWriteData()| need not be called when
// |MojoBeginWriteData()| fails.
//
// Returns:
// |MOJO_RESULT_OK| on success.
// |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g.,
// |data_pipe_producer_handle| is not a handle to a data pipe producer or
// flags has |MOJO_WRITE_DATA_FLAG_ALL_OR_NONE| set.
// |MOJO_RESULT_FAILED_PRECONDITION| if the data pipe consumer handle has been
// closed.
// |MOJO_RESULT_BUSY| if there is already a two-phase write ongoing with
// |data_pipe_producer_handle| (i.e., |MojoBeginWriteData()| has been
// called, but not yet the matching |MojoEndWriteData()|).
// |MOJO_RESULT_SHOULD_WAIT| if no data can currently be written (and the
// consumer is still open).
MOJO_SYSTEM_EXPORT MojoResult
MojoBeginWriteData(MojoHandle data_pipe_producer_handle,
void** buffer, // Out.
uint32_t* buffer_num_bytes, // In/out.
MojoWriteDataFlags flags);
// Ends a two-phase write that was previously initiated by
// |MojoBeginWriteData()| for the same |data_pipe_producer_handle|.
//
// |num_bytes_written| must indicate the number of bytes actually written into
// the two-phase write buffer. It must be less than or equal to the value of
// |*buffer_num_bytes| output by |MojoBeginWriteData()|, and it must be a
// multiple of the data pipe's element size.
//
// On failure, the two-phase write (if any) is ended (so the handle may become
// writable again if there's space available) but no data written to |*buffer|
// is "put into" the data pipe.
//
// Returns:
// |MOJO_RESULT_OK| on success.
// |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g.,
// |data_pipe_producer_handle| is not a handle to a data pipe producer or
// |num_bytes_written| is invalid (greater than the maximum value provided
// by |MojoBeginWriteData()| or not a multiple of the element size).
// |MOJO_RESULT_FAILED_PRECONDITION| if the data pipe producer is not in a
// two-phase write (e.g., |MojoBeginWriteData()| was not called or
// |MojoEndWriteData()| has already been called).
MOJO_SYSTEM_EXPORT MojoResult
MojoEndWriteData(MojoHandle data_pipe_producer_handle,
uint32_t num_bytes_written);
// Reads data from the data pipe consumer given by |data_pipe_consumer_handle|.
// May also be used to discard data or query the amount of data available.
//
// If |flags| has neither |MOJO_READ_DATA_FLAG_DISCARD| nor
// |MOJO_READ_DATA_FLAG_QUERY| set, this tries to read up to |*num_bytes| (which
// must be a multiple of the data pipe's element size) bytes of data to
// |elements| and set |*num_bytes| to the amount actually read. If flags has
// |MOJO_READ_DATA_FLAG_ALL_OR_NONE| set, it will either read exactly
// |*num_bytes| bytes of data or none. Additionally, if flags has
// |MOJO_READ_DATA_FLAG_PEEK| set, the data read will remain in the pipe and be
// available to future reads.
//
// If flags has |MOJO_READ_DATA_FLAG_DISCARD| set, it discards up to
// |*num_bytes| (which again must be a multiple of the element size) bytes of
// data, setting |*num_bytes| to the amount actually discarded. If flags has
// |MOJO_READ_DATA_FLAG_ALL_OR_NONE|, it will either discard exactly
// |*num_bytes| bytes of data or none. In this case, |MOJO_READ_DATA_FLAG_QUERY|
// must not be set, and |elements| is ignored (and should typically be set to
// null).
//
// If flags has |MOJO_READ_DATA_FLAG_QUERY| set, it queries the amount of data
// available, setting |*num_bytes| to the number of bytes available. In this
// case, |MOJO_READ_DATA_FLAG_DISCARD| must not be set, and
// |MOJO_READ_DATA_FLAG_ALL_OR_NONE| is ignored, as are |elements| and the input
// value of |*num_bytes|.
//
// Returns:
// |MOJO_RESULT_OK| on success (see above for a description of the different
// operations).
// |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g.,
// |data_pipe_consumer_handle| is invalid, the combination of flags in
// |flags| is invalid, etc.).
// |MOJO_RESULT_FAILED_PRECONDITION| if the data pipe producer handle has been
// closed and data (or the required amount of data) was not available to
// be read or discarded.
// |MOJO_RESULT_OUT_OF_RANGE| if |flags| has |MOJO_READ_DATA_FLAG_ALL_OR_NONE|
// set and the required amount of data is not available to be read or
// discarded (and the producer is still open).
// |MOJO_RESULT_BUSY| if there is a two-phase read ongoing with
// |data_pipe_consumer_handle| (i.e., |MojoBeginReadData()| has been
// called, but not yet the matching |MojoEndReadData()|).
// |MOJO_RESULT_SHOULD_WAIT| if there is no data to be read or discarded (and
// the producer is still open) and |flags| does *not* have
// |MOJO_READ_DATA_FLAG_ALL_OR_NONE| set.
MOJO_SYSTEM_EXPORT MojoResult MojoReadData(MojoHandle data_pipe_consumer_handle,
void* elements, // Out.
uint32_t* num_bytes, // In/out.
MojoReadDataFlags flags);
// Begins a two-phase read from the data pipe consumer given by
// |data_pipe_consumer_handle|. On success, |*buffer| will be a pointer from
// which the caller can read up to |*buffer_num_bytes| bytes of data.
//
// During a two-phase read, |data_pipe_consumer_handle| is *not* readable.
// If another caller tries to read from it by calling |MojoReadData()| or
// |MojoBeginReadData()|, their request will fail with |MOJO_RESULT_BUSY|.
//
// Once the caller has finished reading data from |*buffer|, |MojoEndReadData()|
// must be called to indicate the number of bytes read and to complete the
// two-phase read operation.
//
// |flags| must not have |MOJO_READ_DATA_FLAG_DISCARD|,
// |MOJO_READ_DATA_FLAG_QUERY|, |MOJO_READ_DATA_FLAG_PEEK|, or
// |MOJO_READ_DATA_FLAG_ALL_OR_NONE| set.
//
// Returns:
// |MOJO_RESULT_OK| on success.
// |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g.,
// |data_pipe_consumer_handle| is not a handle to a data pipe consumer,
// or |flags| has invalid flags set.)
// |MOJO_RESULT_FAILED_PRECONDITION| if the data pipe producer handle has been
// closed.
// |MOJO_RESULT_BUSY| if there is already a two-phase read ongoing with
// |data_pipe_consumer_handle| (i.e., |MojoBeginReadData()| has been
// called, but not yet the matching |MojoEndReadData()|).
// |MOJO_RESULT_SHOULD_WAIT| if no data can currently be read (and the
// producer is still open).
MOJO_SYSTEM_EXPORT MojoResult
MojoBeginReadData(MojoHandle data_pipe_consumer_handle,
const void** buffer, // Out.
uint32_t* buffer_num_bytes, // Out.
MojoReadDataFlags flags);
// Ends a two-phase read from the data pipe consumer given by
// |data_pipe_consumer_handle| that was begun by a call to |MojoBeginReadData()|
// on the same handle. |num_bytes_read| should indicate the amount of data
// actually read; it must be less than or equal to the value of
// |*buffer_num_bytes| output by |MojoBeginReadData()| and must be a multiple of
// the element size.
//
// On failure, the two-phase read (if any) is ended (so the handle may become
// readable again) but no data is "removed" from the data pipe.
//
// Returns:
// |MOJO_RESULT_OK| on success.
// |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g.,
// |data_pipe_consumer_handle| is not a handle to a data pipe consumer or
// |num_bytes_written| is greater than the maximum value provided by
// |MojoBeginReadData()| or not a multiple of the element size).
// |MOJO_RESULT_FAILED_PRECONDITION| if the data pipe consumer is not in a
// two-phase read (e.g., |MojoBeginReadData()| was not called or
// |MojoEndReadData()| has already been called).
MOJO_SYSTEM_EXPORT MojoResult
MojoEndReadData(MojoHandle data_pipe_consumer_handle,
uint32_t num_bytes_read);
#ifdef __cplusplus
} // extern "C"
#endif
#endif // MOJO_PUBLIC_C_SYSTEM_DATA_PIPE_H_