Home | History | Annotate | Download | only in cpp
      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_
    269