[mojo] Implement pipe fusion API

mojo/public/c/system/message_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 message pipes.
 //
 // Note: This header should be compilable as C.
 
 #ifndef MOJO_PUBLIC_C_SYSTEM_MESSAGE_PIPE_H_
 #define MOJO_PUBLIC_C_SYSTEM_MESSAGE_PIPE_H_
@@ skipping 163 matching lines @@
 // TODO(vtl): Reconsider the |MOJO_RESULT_RESOURCE_EXHAUSTED| error code; should
 // distinguish this from the hitting-system-limits case.
 MOJO_SYSTEM_EXPORT MojoResult
     MojoReadMessage(MojoHandle message_pipe_handle,
                     void* bytes,            // Optional out.
                     uint32_t* num_bytes,    // Optional in/out.
                     MojoHandle* handles,    // Optional out.
                     uint32_t* num_handles,  // Optional in/out.
                     MojoReadMessageFlags flags);
 
+// Fuses two message pipe endpoints together. Given two pipes:
+//
+//     A <-> B    and    C <-> D
+//
+// Fusing handle B and handle C results in a single pipe:
+//
+//     A <-> D
+//
+// Handles B and C are closed. Any unread messages at C will eventually be
+// delivered to A, and any unread messages at B will eventually be delivered to
+// D.
+//
+// NOTE: A handle may only be fused as long as it is open and has not been
+// written to.
+//
+// Returns:
+//   |MOJO_RESULT_OK| on success.
+//   |MOJO_RESULT_FAILED_PRECONDITION| if both handles were valid message pipe
+//       handles but could not be merged (e.g. one of them has been written to).
+//       In this case the pipes are not fused and both handles are closed.
+//   |MOJO_INVALID_ARGUMENT| if either handle is not a fusable message pipe
+//       handle. In this case both handles remain unaffected.

[yzshen1, 2016/03/10 23:49:03]

Is it easier if we always close the handles? That is one less thing to consider
for the users, and invalid argument is pretty rare. WDYT?

[Ken Rockot(use gerrit already), 2016/03/11 00:32:46]

SGTM - I considered both and didn't feel strongly about it, but it makes the C++
APIs much cleaner IMHO. So done.

+MOJO_SYSTEM_EXPORT MojoResult
+    MojoFuseMessagePipes(MojoHandle handle0, MojoHandle handle1);
+
+
 #ifdef __cplusplus
 }  // extern "C"
 #endif
 
 #endif  // MOJO_PUBLIC_C_SYSTEM_MESSAGE_PIPE_H_