[mojo-edk] Simplify multiprocess pipe bootstrap

mojo/edk/embedder/embedder.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.
 
 #ifndef MOJO_EDK_EMBEDDER_EMBEDDER_H_
 #define MOJO_EDK_EMBEDDER_EMBEDDER_H_
 
 #include <stddef.h>
 
 #include <string>
@@ skipping 100 matching lines @@
 // called on the I/O thread (given to |InitIPCSupport()|). This completes
 // synchronously and does not result in a call to the process delegate's
 // |OnShutdownComplete()|.
 MOJO_SYSTEM_IMPL_EXPORT void ShutdownIPCSupportOnIOThread();
 
 // Like |ShutdownIPCSupportOnIOThread()|, but may be called from any thread,
 // signalling shutdown completion via the process delegate's
 // |OnShutdownComplete()|.
 MOJO_SYSTEM_IMPL_EXPORT void ShutdownIPCSupport();
 
-// Unused. Crashes. Only here for linking.
+// Creates a message pipe over an arbitrary platform channel. The other end of
+// the channel must also be passed to this function. Either endpoint can be in
+// any process.
+//
+// Note that the channel is only used to negotiate pipe connection, not as the
+// transport for messages on the pipe.
 MOJO_SYSTEM_IMPL_EXPORT ScopedMessagePipeHandle
 CreateMessagePipe(ScopedPlatformHandle platform_handle);
 
 // Creates a message pipe over an arbitrary platform channel. In order for this
 // to work properly each end of the channel must be passed to this function: one
 // end in a parent process and one end in a child process. In a child process,
 // either PreInitializeChildProcess() or SetParentPipe() must have been been
 // called at least once already.
 //
-// Note: This only exists for backwards compatibility with embedders that rely
-// on mojo::embedder::CreateChannel() behavior. If you have a means of passing
-// platform handles around, you can probably also pass strings around. If you
-// can pass strings around, use CreateParentMessagePipe() and
-// CreateChlidMessagePipe() instead (see below.)
+// |callback| must be safe to call from any thread.
 //
-// |callback| must be safe to call from any thread.
+// DEPRECATED: Please don't use this. Use the synchronous version above. This
+// is now merely an inconvenient wrapper for that.
 MOJO_SYSTEM_IMPL_EXPORT void
 CreateMessagePipe(
     ScopedPlatformHandle platform_handle,
     const base::Callback<void(ScopedMessagePipeHandle)>& callback);
 
 // Creates a message pipe from a token. A child embedder must also have this
 // token and call CreateChildMessagePipe() with it in order for the pipe to get
 // connected.
+MOJO_SYSTEM_IMPL_EXPORT ScopedMessagePipeHandle
+CreateParentMessagePipe(const std::string& token);
+
+// Creates a message pipe from a token. A child embedder must also have this
+// token and call CreateChildMessagePipe() with it in order for the pipe to get
+// connected.
 //
 // |callback| must be safe to call from any thread.
+//
+// DEPRECATED: Please don't use this. Use the synchronous version above. This
+// is now merely an inconvenient wrapper for that.
 MOJO_SYSTEM_IMPL_EXPORT void
 CreateParentMessagePipe(
     const std::string& token,
     const base::Callback<void(ScopedMessagePipeHandle)>& callback);
 
 // Creates a message pipe from a token in a child process. The parent must also
 // have this token and call CreateParentMessagePipe() with it in order for the
 // pipe to get connected.
+MOJO_SYSTEM_IMPL_EXPORT ScopedMessagePipeHandle
+CreateChildMessagePipe(const std::string& token);
+
+// Creates a message pipe from a token in a child process. The parent must also
+// have this token and call CreateParentMessagePipe() with it in order for the
+// pipe to get connected.
 //
 // |callback| must be safe to call from any thread.
+//
+// DEPRECATED: Please don't use this. Use the synchronous version above. This
+// is now merely an inconvenient wrapper for that.
 MOJO_SYSTEM_IMPL_EXPORT void
 CreateChildMessagePipe(
     const std::string& token,
     const base::Callback<void(ScopedMessagePipeHandle)>& callback);
 
 // Generates a random ASCII token string for use with CreateParentMessagePipe()
 // and CreateChildMessagePipe() above. The generated token is suitably random so
 // as to not have to worry about collisions with other generated tokens.
 MOJO_SYSTEM_IMPL_EXPORT std::string GenerateRandomToken();
 
 }  // namespace edk
 }  // namespace mojo
 
 #endif  // MOJO_EDK_EMBEDDER_EMBEDDER_H_