Update comments in system headers to include MOJO_RESULT_BUSY behavior.

mojo/public/c/system/buffer.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 buffers (and in
 // particular shared buffers).
 // TODO(vtl): Reorganize this file (etc.) to separate general buffer functions
 // from (shared) buffer creation.
 //
 // Note: This header should be compilable as C.
@@ skipping 121 matching lines @@
 // options.
 //
 // On success, |*shared_buffer_handle| will be set to the handle for the new
 // buffer handle. (On failure, it is not modified.)
 //
 // Returns:
 //   |MOJO_RESULT_OK| on success.
 //   |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g.,
 //       |buffer_handle| is not a valid buffer handle or |*options| is invalid).
 //   |MOJO_RESULT_UNIMPLEMENTED| if an unsupported flag was set in |*options|.
+//   |MOJO_RESULT_BUSY| if |buffer_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 MojoDuplicateBufferHandle(
     MojoHandle buffer_handle,  // In.
     const struct MojoDuplicateBufferHandleOptions* MOJO_RESTRICT
         options,                                   // Optional in.
     MojoHandle* MOJO_RESTRICT new_buffer_handle);  // Out.
 
 // |MojoGetBufferInformation()|: Gets information about the buffer with handle
 // |buffer_handle|. |info| should be non-null and point to a buffer of size
 // |info_num_bytes|; |info_num_bytes| should be at least 16 (the size of the
 // first, and currently only, version of |struct MojoBufferInformation|).
 
 //
 // On success, |*info| will be filled with information about the given buffer.
 // Note that if additional (larger) versions of |struct MojoBufferInformation|
 // are defined, the largest version permitted by |info_num_bytes| that is
 // supported by the implementation will be filled. Callers expecting more than
 // the first 16-byte version must check the resulting |info->struct_size|.
 //
 // Returns:
 //   |MOJO_RESULT_OK| on success.
 //   |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g.,
 //       |buffer_handle| is not a valid buffer handle, |*info| is null, or
 //       |info_num_bytes| is too small).
+//   |MOJO_RESULT_BUSY| if |buffer_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 MojoGetBufferInformation(MojoHandle buffer_handle,            // In.
                                     struct MojoBufferInformation* info,  // Out.
                                     uint32_t info_num_bytes);            // In.
 
 // |MojoMapBuffer()|: Maps the part (at offset |offset| of length |num_bytes|)
 // of the buffer given by |buffer_handle| into memory, with options specified by
 // |flags|. |offset + num_bytes| must be less than or equal to the size of the
 // buffer. On success, |*buffer| points to memory with the requested part of the
 // buffer. (On failure, it is not modified.)
 
 //
 // A single buffer handle may have multiple active mappings (possibly depending
 // on the buffer type). The permissions (e.g., writable or executable) of the
 // returned memory may depend on the properties of the buffer and properties
 // attached to the buffer handle as well as |flags|.
 //
 // Note: Though data outside the specified range may apparently be
 // available/visible/readable/writable, trying to use those extra bytes is
 // undefined behavior.
 //
 // Returns:
 //   |MOJO_RESULT_OK| on success.
 //   |MOJO_RESULT_INVALID_ARGUMENT| if some argument was invalid (e.g.,
 //       |buffer_handle| is not a valid buffer handle or the range specified by
 //       |offset| and |num_bytes| is not valid).
 //   |MOJO_RESULT_RESOURCE_EXHAUSTED| if the mapping operation itself failed
 //       (e.g., due to not having appropriate address space available).
+//   |MOJO_RESULT_BUSY| if |buffer_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 MojoMapBuffer(MojoHandle buffer_handle,   // In.
                          uint64_t offset,            // In.
                          uint64_t num_bytes,         // In.
                          void** buffer,              // Out.
                          MojoMapBufferFlags flags);  // In.
 
 // |MojoUnmapBuffer()|: Unmaps a buffer pointer that was mapped by
 // |MojoMapBuffer()|. |buffer| must have been the result of |MojoMapBuffer()|
 // (not some other pointer inside the mapped memory), and the entire mapping
 // will be removed (partial unmapping is not supported). A mapping may only be
 // unmapped once.
 //
 // Returns:
 //   |MOJO_RESULT_OK| on success.
 //   |MOJO_RESULT_INVALID_ARGUMENT| if |buffer| is invalid (e.g., is not the
 //       result of |MojoMapBuffer()| or has already been unmapped).
 MojoResult MojoUnmapBuffer(void* buffer);  // In.
 
 MOJO_END_EXTERN_C
 
 #endif  // MOJO_PUBLIC_C_SYSTEM_BUFFER_H_