Remove support for "all or none" two-phase data pipe read/write.

mojo/public/c/system/data_pipe.h

 // 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_
@@ skipping 121 matching lines @@
 
 // Writes the given data to the data pipe producer given by
 // |data_pipe_producer_handle|. |elements| points to data of size |*num_bytes|;
 // |*num_bytes| should 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
 // will be written or none is.
 //
 // On success, |*num_bytes| is set to the amount of data that was actually
 // written.
 //
-// Note: If the data pipe has the "may discard" option flag (specified on
-// creation), this will discard as much data as required to write the given
-// data, starting with the earliest written data that has not been consumed.
-// However, even with "may discard", if |*num_bytes| is greater than the data
-// pipe's capacity (and |MOJO_WRITE_DATA_FLAG_ALL_OR_NONE| is not set), this
-// will write the maximum amount possible (namely, the data pipe's capacity) and
-// set |*num_bytes| to that amount. It will *not* discard data from |elements|.
-//
 // 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.
 //
 // TODO(vtl): Should there be a way of querying how much data can be written?
 MOJO_SYSTEM_EXPORT MojoResult
-    MojoWriteData(MojoHandle data_pipe_producer_handle,
-                  const void* elements,
-                  uint32_t* num_bytes,  // In/out.
-                  MojoWriteDataFlags flags);
+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 |*buffer_num_bytes| bytes of data. If flags has
-// |MOJO_WRITE_DATA_FLAG_ALL_OR_NONE| set, then the output value
-// |*buffer_num_bytes| will be at least as large as its input value, which must
-// also be a multiple of the element size (if |MOJO_WRITE_DATA_FLAG_ALL_OR_NONE|
-// is not set, the input value of |*buffer_num_bytes| is ignored).
+// the caller can write |*buffer_num_bytes| bytes of data. There are currently
+// no flags allowed, so |flags| should be |MOJO_WRITE_DATA_FLAG_NONE|.
 //
 // During a two-phase write, |data_pipe_producer_handle| is *not* writable.
 // E.g., if another thread tries to write to it, it will get |MOJO_RESULT_BUSY|;
 // that thread can then wait for |data_pipe_producer_handle| to become writable
 // again.
 //
-// When |MojoBeginWriteData()| returns MOJO_RESULT_OK, and the caller has
+// When |MojoBeginWriteData()| returns |MOJO_RESULT_OK|, and the caller has
 // finished writing data to |*buffer|, it should call |MojoEndWriteData()| to
 // specify the amount written and to complete the two-phase write.
 // |MojoEndWriteData()| need not be called for other return values.
 //
-// Note: If the data pipe has the "may discard" option flag (specified on
-// creation) and |flags| has |MOJO_WRITE_DATA_FLAG_ALL_OR_NONE| set, this may
-// discard some data.
-//
 // 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 and
-//       |*buffer_num_bytes| is not a multiple of the element size).
+//       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_OUT_OF_RANGE| if |flags| has
-//       |MOJO_WRITE_DATA_FLAG_ALL_OR_NONE| set and the required amount of data
-//       (specified by |*buffer_num_bytes|) cannot be written contiguously at
-//       this time. (Note that there may be space available for the required
-//       amount of data, but the "next" write position may not be large enough.)
 //   |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);
+MojoBeginWriteData(MojoHandle data_pipe_producer_handle,
+                   void** buffer,               // Out.
+                   uint32_t* buffer_num_bytes,  // Out.
+                   MojoWriteDataFlags flags);
 
 // Ends a two-phase write to the data pipe producer given by
 // |data_pipe_producer_handle| that was begun by a call to
 // |MojoBeginWriteData()| on the same handle. |num_bytes_written| should
 // indicate the amount of data actually written; it must be less than or equal
 // to the value of |*buffer_num_bytes| output by |MojoBeginWriteData()| and must
 // be a multiple of the element size. The buffer given by |*buffer| from
 // |MojoBeginWriteData()| must have been filled with exactly |num_bytes_written|
 // bytes of data.
 //
 // 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);
+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
@@ skipping 32 matching lines @@
 //   |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 |*buffer_num_bytes| bytes of data. If flags has
-// |MOJO_READ_DATA_FLAG_ALL_OR_NONE| set, then the output value
-// |*buffer_num_bytes| will be at least as large as its input value, which must
-// also be a multiple of the element size (if |MOJO_READ_DATA_FLAG_ALL_OR_NONE|
-// is not set, the input value of |*buffer_num_bytes| is ignored). |flags| must
-// not have |MOJO_READ_DATA_FLAG_DISCARD|, |MOJO_READ_DATA_FLAG_QUERY|, or
-// |MOJO_READ_DATA_FLAG_PEEK| set.
+// which the caller can read |*buffer_num_bytes| bytes of data. There are
+// currently no valid flags, so |flags| must be |MOJO_READ_DATA_FLAG_NONE|.
 //
 // During a two-phase read, |data_pipe_consumer_handle| is *not* readable.
 // E.g., if another thread tries to read from it, it will get
 // |MOJO_RESULT_BUSY|; that thread can then wait for |data_pipe_consumer_handle|
 // to become readable again.
 //
 // Once the caller has finished reading data from |*buffer|, it should call
 // |MojoEndReadData()| to specify the amount read and to complete the two-phase
 // read.
 //
 // 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,
-//       |flags| has |MOJO_READ_DATA_FLAG_ALL_OR_NONE| set and
-//       |*buffer_num_bytes| is not a multiple of the element size, or |flags|
-//       has invalid flags set).
+//       or |flags| has invalid flags set).
 //   |MOJO_RESULT_FAILED_PRECONDITION| if the data pipe producer handle has been
 //       closed.
-//   |MOJO_RESULT_OUT_OF_RANGE| if |flags| has |MOJO_READ_DATA_FLAG_ALL_OR_NONE|
-//       set and the required amount of data (specified by |*buffer_num_bytes|)
-//       cannot be read from a contiguous buffer at this time. (Note that there
-//       may be the required amount of data, but it may not be contiguous.)
 //   |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,  // In/out.
-                      MojoReadDataFlags flags);
+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);
+MojoEndReadData(MojoHandle data_pipe_consumer_handle, uint32_t num_bytes_read);
 
 #ifdef __cplusplus
 }  // extern "C"
 #endif
 
 #endif  // MOJO_PUBLIC_C_SYSTEM_DATA_PIPE_H_