mojo/embedder/embedder.h

   1 // Copyright 2014 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef MOJO_EMBEDDER_EMBEDDER_H_
   6 #define MOJO_EMBEDDER_EMBEDDER_H_
   7
   8 #include "base/callback.h"
   9 #include "base/memory/ref_counted.h"
  10 #include "base/memory/scoped_ptr.h"
  11 #include "base/task_runner.h"
  12 #include "mojo/embedder/scoped_platform_handle.h"
  13 #include "mojo/public/cpp/system/core.h"
  14 #include "mojo/system/system_impl_export.h"
  15
  16 namespace mojo {
  17 namespace embedder {
  18
  19 class PlatformSupport;
  20
  21 // Must be called first to initialize the (global, singleton) system.
  22 MOJO_SYSTEM_IMPL_EXPORT void Init(scoped_ptr<PlatformSupport> platform_support);
  23
  24 // A "channel" is a connection on top of an OS "pipe", on top of which Mojo
  25 // message pipes (etc.) can be multiplexed. It must "live" on some I/O thread.
  26 //
  27 // There are two "channel" creation/destruction APIs: the synchronous
  28 // |CreateChannelOnIOThread()|/|DestroyChannelOnIOThread()|, which must be
  29 // called from the I/O thread, and the asynchronous
  30 // |CreateChannel()|/|DestroyChannel()|, which may be called from any thread.
  31 //
  32 // Both creation functions have a |platform_handle| argument, which should be an
  33 // OS-dependent handle to one side of a suitable bidirectional OS "pipe" (e.g.,
  34 // a file descriptor to a socket on POSIX, a handle to a named pipe on Windows);
  35 // this "pipe" should be connected and ready for operation (e.g., to be written
  36 // to or read from).
  37 //
  38 // Both (synchronously) return a handle to the bootstrap message pipe on the
  39 // channel that was (or is to be) created, or |MOJO_HANDLE_INVALID| on error
  40 // (but note that this will happen only if, e.g., the handle table is full).
  41 // This message pipe may be used immediately, but since channel operation
  42 // actually begins asynchronously, other errors may still occur (e.g., if the
  43 // other end of the "pipe" is closed) and be reported in the usual way to the
  44 // returned handle.
  45 //
  46 // (E.g., a message written immediately to the returned handle will be queued
  47 // and the handle immediately closed, before the channel begins operation. In
  48 // this case, the channel should connect as usual, send the queued message, and
  49 // report that the handle was closed to the other side. The message sent may
  50 // have other handles, so there may still be message pipes "on" this channel.)
  51 //
  52 // Both also produce a |ChannelInfo*| (a pointer to an opaque object) -- the
  53 // first synchronously and second asynchronously.
  54 //
  55 // The destruction functions are similarly synchronous and asynchronous,
  56 // respectively, and take the |ChannelInfo*| produced by the creation function.
  57 // (Note: One may call |DestroyChannelOnIOThread()| with the result of
  58 // |CreateChannel()|, but not |DestroyChannel()| with the result of
  59 // |CreateChannelOnIOThread()|.)
  60 //
  61 // TODO(vtl): Figure out channel teardown.
  62 struct ChannelInfo;
  63
  64 // Creates a channel; must only be called from the I/O thread. |platform_handle|
  65 // should be a handle to a connected OS "pipe". Eventually (even on failure),
  66 // the "out" value |*channel_info| should be passed to
  67 // |DestroyChannelOnIOThread()| to tear down the channel. Returns a handle to
  68 // the bootstrap message pipe.
  69 MOJO_SYSTEM_IMPL_EXPORT ScopedMessagePipeHandle
  70     CreateChannelOnIOThread(ScopedPlatformHandle platform_handle,
  71                             ChannelInfo** channel_info);
  72
  73 typedef base::Callback<void(ChannelInfo*)> DidCreateChannelCallback;
  74 // Creates a channel asynchronously; may be called from any thread.
  75 // |platform_handle| should be a handle to a connected OS "pipe".
  76 // |io_thread_task_runner| should be the |TaskRunner| for the I/O thread.
  77 // |callback| should be the callback to call with the |ChannelInfo*|, which
  78 // should eventually be passed to |DestroyChannel()| (or
  79 // |DestroyChannelOnIOThread()|) to tear down the channel; the callback will be
  80 // called using |callback_thread_task_runner| if that is non-null, or otherwise
  81 // it will be called using |io_thread_task_runner|. Returns a handle to the
  82 // bootstrap message pipe.
  83 MOJO_SYSTEM_IMPL_EXPORT ScopedMessagePipeHandle
  84     CreateChannel(ScopedPlatformHandle platform_handle,
  85                   scoped_refptr<base::TaskRunner> io_thread_task_runner,
  86                   DidCreateChannelCallback callback,
  87                   scoped_refptr<base::TaskRunner> callback_thread_task_runner);
  88
  89 // Destroys a channel that was created using either |CreateChannelOnIOThread()|
  90 // or |CreateChannel()|; must only be called from the I/O thread. |channel_info|
  91 // should be the "out" value from |CreateChannelOnIOThread()| or the value
  92 // provided to the callback to |CreateChannel()|.
  93 MOJO_SYSTEM_IMPL_EXPORT void DestroyChannelOnIOThread(
  94     ChannelInfo* channel_info);
  95
  96 // Destroys a channel (asynchronously) that was created using |CreateChannel()|
  97 // (note: NOT |CreateChannelOnIOThread()|); may be called from any thread.
  98 // |channel_info| should be the value provided to the callback to
  99 // |CreateChannel()|.
 100 MOJO_SYSTEM_IMPL_EXPORT void DestroyChannel(ChannelInfo* channel_info);
 101
 102 // Inform the channel that it will soon be destroyed (doing so is optional).
 103 // This may be called from any thread, but the caller must ensure that this is
 104 // called before |DestroyChannel()| or |DestroyChannelOnIOThread()|.
 105 MOJO_SYSTEM_IMPL_EXPORT void WillDestroyChannelSoon(ChannelInfo* channel_info);
 106
 107 // Creates a |MojoHandle| that wraps the given |PlatformHandle| (taking
 108 // ownership of it). This |MojoHandle| can then, e.g., be passed through message
 109 // pipes. Note: This takes ownership (and thus closes) |platform_handle| even on
 110 // failure, which is different from what you'd expect from a Mojo API, but it
 111 // makes for a more convenient embedder API.
 112 MOJO_SYSTEM_IMPL_EXPORT MojoResult
 113     CreatePlatformHandleWrapper(ScopedPlatformHandle platform_handle,
 114                                 MojoHandle* platform_handle_wrapper_handle);
 115 // Retrieves the |PlatformHandle| that was wrapped into a |MojoHandle| (using
 116 // |CreatePlatformHandleWrapper()| above). Note that the |MojoHandle| must still
 117 // be closed separately.
 118 MOJO_SYSTEM_IMPL_EXPORT MojoResult
 119     PassWrappedPlatformHandle(MojoHandle platform_handle_wrapper_handle,
 120                               ScopedPlatformHandle* platform_handle);
 121
 122 }  // namespace embedder
 123 }  // namespace mojo
 124
 125 #endif  // MOJO_EMBEDDER_EMBEDDER_H_