ppapi/cpp/message_loop.h

   1 // Copyright (c) 2012 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 PPAPI_CPP_MESSAGE_LOOP_H_
   6 #define PPAPI_CPP_MESSAGE_LOOP_H_
   7
   8 #include "ppapi/cpp/resource.h"
   9
  10 /// @file
  11 /// This file defines the PPB_MessageLoop API.
  12
  13 namespace pp {
  14
  15 class CompletionCallback;
  16 class InstanceHandle;
  17
  18 /// A message loop allows PPAPI calls to be issued on a thread. You may not
  19 /// issue any API calls on a thread without creating a message loop. It also
  20 /// allows you to post work to the message loop for a thread.
  21 ///
  22 /// To process work posted to the message loop, as well as completion callbacks
  23 /// for asynchronous operations, you must run the message loop via Run().
  24 ///
  25 /// Note the system manages the lifetime of the instance (and all associated
  26 /// resources). If the instance is deleted from the page, background threads may
  27 /// suddenly see their PP_Resource handles become invalid. In this case, calls
  28 /// will fail with PP_ERROR_BADRESOURCE. If you need to access data associated
  29 /// with your instance, you will probably want to create some kind of threadsafe
  30 /// proxy object that can handle asynchronous destruction of the instance
  31 /// object.
  32 ///
  33 /// Typical usage:
  34 ///   On the main thread:
  35 ///    - Create the thread yourself (using pthreads).
  36 ///    - Create the message loop resource.
  37 ///    - Pass the message loop resource to your thread's main function.
  38 ///    - Call PostWork() on the message loop to run functions on the thread.
  39 ///
  40 ///   From the background thread's main function:
  41 ///    - Call AttachToCurrentThread() with the message loop resource.
  42 ///    - Call Run() with the message loop resource.
  43 ///
  44 ///   Your callbacks should look like this:
  45 ///   @code
  46 ///   void DoMyWork(void* user_data, int32_t status) {
  47 ///     if (status != PP_OK) {
  48 ///       Cleanup();  // e.g. free user_data.
  49 ///       return;
  50 ///     }
  51 ///     ... do your work...
  52 ///   }
  53 ///   @endcode
  54 /// For a C++ example, see ppapi/utility/threading/simple_thread.h
  55 ///
  56 /// (You can also create the message loop resource on the background thread,
  57 /// but then the main thread will have no reference to it should you want to
  58 /// call PostWork()).
  59 ///
  60 ///
  61 /// THREAD HANDLING
  62 ///
  63 /// The main thread has an implicitly created message loop. The main thread is
  64 /// the thread where PPP_InitializeModule and PPP_Instance functions are called.
  65 /// You can retrieve a reference to this message loop by calling
  66 /// GetForMainThread() or, if your code is on the main thread, GetCurrent() will
  67 /// also work.
  68 ///
  69 /// Some special threads created by the system can not have message loops. In
  70 /// particular, the background thread created for audio processing has this
  71 /// requirement because it's intended to be highly responsive to keep up with
  72 /// the realtime requirements of audio processing. You can not make PPAPI calls
  73 /// from these threads.
  74 ///
  75 /// Once you associate a message loop with a thread, you don't have to keep a
  76 /// reference to it. The system will hold a reference to the message loop for as
  77 /// long as the thread is running. The current message loop can be retrieved
  78 /// using the GetCurrent() function.
  79 ///
  80 /// It is legal to create threads in your plugin without message loops, but
  81 /// PPAPI calls will fail unless explicitly noted in the documentation.
  82 ///
  83 /// You can create a message loop object on a thread and never actually run the
  84 /// message loop. This will allow you to call blocking PPAPI calls (via
  85 /// PP_BlockUntilComplete()). If you make any asynchronous calls, the callbacks
  86 /// from those calls will be queued in the message loop and never run. The same
  87 /// thing will happen if work is scheduled after the message loop exits and
  88 /// the message loop is not run again.
  89 ///
  90 ///
  91 /// DESTRUCTION AND ERROR HANDLING
  92 ///
  93 /// Often, your application will associate memory with completion callbacks. For
  94 /// example, the C++ CompletionCallbackFactory has a small amount of
  95 /// heap-allocated memory for each callback. This memory will be leaked if the
  96 /// callback is never run. To avoid this memory leak, you need to be careful
  97 /// about error handling and shutdown.
  98 ///
  99 /// There are a number of cases where posted callbacks will never be run:
 100 ///
 101 ///  - You tear down the thread (via pthreads) without "destroying" the message
 102 ///    loop (via PostQuit with should_destroy = PP_TRUE). In this case, any
 103 ///    tasks in the message queue will be lost.
 104 ///
 105 ///  - You create a message loop, post callbacks to it, and never run it.
 106 ///
 107 ///  - You quit the message loop via PostQuit with should_destroy set to
 108 ///    PP_FALSE. In this case, the system will assume the message loop will be
 109 ///    run again later and keep your tasks.
 110 ///
 111 /// To do proper shutdown, call PostQuit with should_destroy = PP_TRUE. This
 112 /// will prohibit future work from being posted, and will allow the message loop
 113 /// to run until all pending tasks are run.
 114 ///
 115 /// If you post a callback to a message loop that's been destroyed, or to an
 116 /// invalid message loop, PostWork will return an error and will not run the
 117 /// callback. This is true even for callbacks with the "required" flag set,
 118 /// since the system may not even know what thread to issue the error callback
 119 /// on.
 120 ///
 121 /// Therefore, you should check for errors from PostWork and destroy any
 122 /// associated memory to avoid leaks. If you're using the C++
 123 /// CompletionCallbackFactory, use the following pattern:
 124 /// @code
 125 /// pp::CompletionCallback callback = factory_.NewOptionalCallback(...);
 126 /// int32_t result = message_loop.PostWork(callback);
 127 /// if (result != PP_OK)
 128 ///   callback.Run(result);
 129 /// @endcode
 130 /// This will run the callback with an error value, and assumes that the
 131 /// implementation of your callback checks the "result" argument and returns
 132 /// immediately on error.
 133 class MessageLoop : public Resource {
 134  public:
 135   /// Creates an is_null() MessageLoop resource.
 136   MessageLoop();
 137
 138   /// Creates a message loop associated with the given instance. The resource
 139   /// will be is_null() on failure.
 140   ///
 141   /// This may be called from any thread. After your thread starts but before
 142   /// issuing any other PPAPI calls on it, you must associate it with a message
 143   /// loop by calling AttachToCurrentThread.
 144   explicit MessageLoop(const InstanceHandle& instance);
 145
 146   MessageLoop(const MessageLoop& other);
 147
 148   /// Takes an additional ref to the resource.
 149   explicit MessageLoop(PP_Resource pp_message_loop);
 150
 151   static MessageLoop GetForMainThread();
 152   static MessageLoop GetCurrent();
 153
 154   /// Sets the given message loop resource as being the associated message loop
 155   /// for the currently running thread.
 156   ///
 157   /// You must call this function exactly once on a thread before making any
 158   /// PPAPI calls. A message loop can only be attached to one thread, and the
 159   /// message loop can not be changed later. The message loop will be attached
 160   /// as long as the thread is running or until you quit with should_destroy
 161   /// set to PP_TRUE.
 162   ///
 163   /// If this function fails, attempting to run the message loop will fail.
 164   /// Note that you can still post work to the message loop: it will get queued
 165   /// up should the message loop eventually be successfully attached and run.
 166   ///
 167   /// @return
 168   ///   - PP_OK: The message loop was successfully attached to the thread and is
 169   ///     ready to use.
 170   ///   - PP_ERROR_BADRESOURCE: The given message loop resource is invalid.
 171   ///   - PP_ERROR_INPROGRESS: The current thread already has a message loop
 172   ///     attached. This will always be the case for the main thread, which has
 173   ///     an implicit system-created message loop attached.
 174   ///   - PP_ERROR_WRONG_THREAD: The current thread type can not have a message
 175   ///     loop attached to it. See the interface level discussion about these
 176   ///     special threads, which include realtime audio threads.
 177   int32_t AttachToCurrentThread();
 178
 179   /// Runs the thread message loop. Running the message loop is required for
 180   /// you to get issued completion callbacks on the thread.
 181   ///
 182   /// The message loop identified by the argument must have been previously
 183   /// successfully attached to the current thread.
 184   ///
 185   /// You may not run nested message loops. Since the main thread has an
 186   /// implicit message loop that the system runs, you may not call Run on the
 187   /// main thread.
 188   ///
 189   /// @return
 190   ///   - PP_OK: The message loop was successfully run. Note that on
 191   ///     success, the message loop will only exit when you call PostQuit().
 192   ///   - PP_ERROR_BADRESOURCE: The given message loop resource is invalid.
 193   ///   - PP_ERROR_WRONG_THREAD: You are attempting to run a message loop that
 194   ///     has not been successfully attached to the current thread. Call
 195   ///     AttachToCurrentThread().
 196   ///   - PP_ERROR_INPROGRESS: You are attempting to call Run in a nested
 197   ///     fashion (Run is already on the stack). This will occur if you attempt
 198   ///     to call run on the main thread's message loop (see above).
 199   int32_t Run();
 200
 201   /// Schedules work to run on the given message loop. This may be called from
 202   /// any thread. Posted work will be executed in the order it was posted when
 203   /// the message loop is Run().
 204   ///
 205   /// @param callback A pointer to the completion callback to execute from the
 206   /// message loop.
 207   ///
 208   /// @param delay_ms The number of milliseconds to delay execution of the given
 209   /// completion callback. Passing 0 means it will get queued normally and
 210   /// executed in order.
 211   ///
 212   ///
 213   /// The completion callback will be called with PP_OK as the "result"
 214   /// parameter if it is run normally. It is good practice to check for PP_OK
 215   /// and return early otherwise.
 216   ///
 217   /// The "required" flag on the completion callback is ignored. If there is an
 218   /// error posting your callback, the error will be returned from PostWork and
 219   /// the callback will never be run (because there is no appropriate place to
 220   /// run your callback with an error without causing unexpected threading
 221   /// problems). If you associate memory with the completion callback (for
 222   /// example, you're using the C++ CompletionCallbackFactory), you will need to
 223   /// free this or manually run the callback. See "Desctruction and error
 224   /// handling" above.
 225   ///
 226   ///
 227   /// You can call this function before the message loop has started and the
 228   /// work will get queued until the message loop is run. You can also post
 229   /// work after the message loop has exited as long as should_destroy was
 230   /// PP_FALSE. It will be queued until the next invocation of Run().
 231   ///
 232   /// @return
 233   ///   - PP_OK: The work was posted to the message loop's queue. As described
 234   ///     above, this does not mean that the work has been or will be executed
 235   ///     (if you never run the message loop after posting).
 236   ///   - PP_ERROR_BADRESOURCE: The given message loop resource is invalid.
 237   ///   - PP_ERROR_BADARGUMENT: The function pointer for the completion callback
 238   ///     is null (this will be the case if you pass PP_BlockUntilComplete()).
 239   ///   - PP_ERROR_FAILED: The message loop has been destroyed.
 240   int32_t PostWork(const CompletionCallback& callback,
 241                    int64_t delay_ms = 0);
 242
 243   /// Posts a quit message to the given message loop's work queue. Work posted
 244   /// before that point will be processed before quitting.
 245   ///
 246   /// This may be called on the message loop registered for the current thread,
 247   /// or it may be called on the message loop registered for another thread. It
 248   /// is an error to attempt to quit the main thread loop.
 249   ///
 250   /// @param should_destroy Marks the message loop as being in a destroyed
 251   /// state and prevents further posting of messages.
 252   ///
 253   /// If you quit a message loop without setting should_destroy, it will still
 254   /// be attached to the thread and you can still run it again by calling Run()
 255   /// again. If you destroy it, it will be detached from the current thread.
 256   ///
 257   /// @return
 258   ///   - PP_OK: The request to quit was successfully posted.
 259   ///   - PP_ERROR_BADRESOURCE: The message loop was invalid.
 260   ///   - PP_ERROR_WRONG_THREAD: You are attempting to quit the main thread.
 261   ///     The main thread's message loop is managed by the system and can't be
 262   ///     quit.
 263   int32_t PostQuit(bool should_destroy);
 264 };
 265
 266 }  // namespace pp
 267
 268 #endif  // PPAPI_CPP_MESSAGE_LOOP_H_