Allow data pipe producer/consumer handles to be transferred during two-phase operations.

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 248 matching lines @@
 // 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
 // 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: After a successful |MojoBeginWriteData()| on a given handle and before
+// a corresponding |MojoEndWriteData()|, any operation that invalidates the
+// handle (such as closing the handle, replacing the handle with one with
+// reduced rights, or transferring the handle over a message pipe) will abort
+// the two-phase write. That is, the behavior is equivalent to ending the
+// two-phase write with no data written. That operation will also invalidate the
+// buffer pointer: the behavior if data continues to be written to the buffer is
+// undefined.
+//
 // 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_PERMISSION_DENIED| if |data_pipe_producer_handle| does not
 //       have the |MOJO_HANDLE_RIGHT_WRITE| right.
 //   |MOJO_RESULT_FAILED_PRECONDITION| if the data pipe consumer handle has been
 //       closed.
 //   |MOJO_RESULT_BUSY| if |data_pipe_producer_handle| is currently in use in
@@ skipping 154 matching lines @@
 //
 // 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.
 //
+// Note: After a successful |MojoBeginReadData()| on a given handle and before a
+// corresponding |MojoEndReadData()|, any operation that invalidates the handle
+// (such as closing the handle, replacing the handle with one with reduced
+// rights, or transferring the handle over a message pipe) will abort the
+// two-phase read. That is, the behavior is equivalent to ending the two-phase
+// read with no data consumed. That operation will also invalidate the buffer
+// pointer: the behavior if data continues to be read from the buffer is
+// undefined.
+//
 // 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_PERMISSION_DENIED| if |data_pipe_consumer_handle| does not
 //       have the |MOJO_HANDLE_RIGHT_READ| right.
 //   |MOJO_RESULT_FAILED_PRECONDITION| if the data pipe producer handle has been
 //       closed.
 //   |MOJO_RESULT_BUSY| if |data_pipe_consumer_handle| is currently in use in
@@ skipping 31 matching lines @@
 //       |MojoEndReadData()| has already been called).
 //   |MOJO_RESULT_BUSY| if |data_pipe_consumer_handle| is currently in use in
 //       some transaction (that, e.g., may result in it being invalidated, such
 //       as being sent in a message).
 MojoResult MojoEndReadData(MojoHandle data_pipe_consumer_handle,  // In.
                            uint32_t num_bytes_read);              // In.
 
 MOJO_END_EXTERN_C
 
 #endif  // MOJO_PUBLIC_C_SYSTEM_DATA_PIPE_H_