Update comments in system headers to include MOJO_RESULT_BUSY behavior.

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 110 matching lines @@
 //   |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
+//   |MOJO_RESULT_BUSY| if |data_pipe_producer_handle| is currently in use in
+//       some transaction (that, e.g., may result in it being invalidated, such
+//       as being sent in a message), or 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?
 MojoResult MojoWriteData(MojoHandle data_pipe_producer_handle,  // In.
                          const void* MOJO_RESTRICT elements,    // In.
                          uint32_t* MOJO_RESTRICT num_bytes,     // In/out.
                          MojoWriteDataFlags flags);             // In.
@@ skipping 13 matching lines @@
 // specify the amount written and to complete the two-phase write.
 // |MojoEndWriteData()| need not be called for other return values.
 //
 // 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_BUSY| if |data_pipe_producer_handle| is currently in use in
+//       some transaction (that, e.g., may result in it being invalidated, such
+//       as being sent in a message), or 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).
 MojoResult MojoBeginWriteData(MojoHandle data_pipe_producer_handle,      // In.
                               void** MOJO_RESTRICT buffer,               // Out.
                               uint32_t* MOJO_RESTRICT buffer_num_bytes,  // Out.
                               MojoWriteDataFlags flags);                 // In.
 
 // |MojoEndWriteData()|: 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_RESULT_BUSY| if |data_pipe_producer_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 MojoEndWriteData(MojoHandle data_pipe_producer_handle,  // In.
                             uint32_t num_bytes_written);           // In.
 
 // |MojoReadData()|: 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
@@ skipping 22 matching lines @@
 //       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
+//   |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), or 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.
 MojoResult MojoReadData(MojoHandle data_pipe_consumer_handle,  // In.
                         void* MOJO_RESTRICT elements,          // Out.
                         uint32_t* MOJO_RESTRICT num_bytes,     // In/out.
                         MojoReadDataFlags flags);              // In.
 
 // |MojoBeginReadData()|: Begins a two-phase read from the data pipe consumer
@@ skipping 10 matching lines @@
 // |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,
 //       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_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), or 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).
 MojoResult MojoBeginReadData(MojoHandle data_pipe_consumer_handle,      // In.
                              const void** MOJO_RESTRICT buffer,         // Out.
                              uint32_t* MOJO_RESTRICT buffer_num_bytes,  // Out.
                              MojoReadDataFlags flags);                  // In.
 
 // |MojoEndReadData()|: 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_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_