Implement a MOJO_READ_DATA_FLAG_PEEK flag for data pipes.

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 65 matching lines @@
 // |MojoBeginReadData()|.
 //   |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.
 //   |MOJO_READ_DATA_FLAG_DISCARD| - Discard (up to) the requested number of
 //        elements.
 //   |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
@@ skipping 138 matching lines @@
                      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.
+// |*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 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
@@ skipping 25 matching lines @@
                                            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| or |MOJO_READ_DATA_FLAG_QUERY| set.
+// not have |MOJO_READ_DATA_FLAG_DISCARD|, |MOJO_READ_DATA_FLAG_QUERY|, or
+// |MOJO_READ_DATA_FLAG_PEEK| set.
 //
 // 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.
 //
@@ skipping 42 matching lines @@
 //       |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_