ppapi/shared_impl/callback_tracker.h

   1 // Copyright (c) 2011 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_SHARED_IMPL_CALLBACK_TRACKER_H_
   6 #define PPAPI_SHARED_IMPL_CALLBACK_TRACKER_H_
   7
   8 #include <map>
   9 #include <set>
  10
  11 #include "base/basictypes.h"
  12 #include "base/memory/ref_counted.h"
  13 #include "base/synchronization/lock.h"
  14 #include "ppapi/c/pp_resource.h"
  15 #include "ppapi/shared_impl/ppapi_shared_export.h"
  16
  17 namespace ppapi {
  18
  19 class TrackedCallback;
  20
  21 // Pepper callbacks have the following semantics (unless otherwise specified;
  22 // in particular, the below apply to all completion callbacks):
  23 //  - Callbacks are always run on the thread where the plugin called a Pepper
  24 //    function providing that callback.
  25 //  - Callbacks are always called from the message loop of the thread. In
  26 //    particular, calling into Pepper will not result in the plugin being
  27 //    re-entered via a synchronously-run callback.
  28 //  - Each callback will be executed (a.k.a. completed) exactly once.
  29 //  - Each callback may be *aborted*, which means that it will be executed with
  30 //    result |PP_ERROR_ABORTED| (in the case of completion callbacks). The
  31 //    ABORT counts as the callback's one completion.
  32 //  - Before |PPP_ShutdownModule()| is called, every pending callback (for every
  33 //    instance of that module) will be aborted.
  34 //  - Callbacks are usually associated to a resource, whose "deletion" provides
  35 //    a "cancellation" (or abort) mechanism -- see below.
  36 //  - When a plugin releases its last reference to resource, all callbacks
  37 //    associated to that resource are aborted. Even if a non-abortive completion
  38 //    of such a callback had previously been scheduled (i.e., posted), that
  39 //    callback must now be aborted. The aborts should be scheduled immediately
  40 //    (upon the last reference being given up) and should not rely on anything
  41 //    else (e.g., a background task to complete or further action from the
  42 //    plugin).
  43 //  - Abortive completion gives no information about the status of the
  44 //    asynchronous operation: The operation may have not yet begun, may be in
  45 //    progress, or may be completed (successfully or not). In fact, the
  46 //    operation may still proceed after the callback has been aborted.
  47 //  - Any output data buffers provided to Pepper are associated with a resource.
  48 //    Once that resource is released, no subsequent writes to those buffers
  49 //    will occur. When operations occur on background threads, writing to the
  50 //    plugin's data buffers should be delayed to happen on the callback's thread
  51 //    to ensure that we don't write to the buffers if the callback has been
  52 //    aborted (see TrackedCallback::set_completion_task()).
  53 //
  54 // Thread-safety notes:
  55 // |CallbackTracker| uses a lock to protect its dictionary of callbacks. This
  56 // is primarily to allow the safe removal of callbacks from any thread without
  57 // requiring that the |ProxyLock| is held. Methods that may invoke a callback
  58 // need to have the |ProxyLock| (and those methods assert that it's acquired).
  59 // |TrackedCallback| is thread-safe ref-counted, so objects which live on
  60 // different threads may keep references. Releasing a reference to
  61 // |TrackedCallback| on a different thread (possibly causing destruction) is
  62 // also okay.
  63 //
  64 // |CallbackTracker| tracks pending Pepper callbacks for a single instance. It
  65 // also tracks, for each resource ID, which callbacks are pending. Just before
  66 // a callback is completed, it is removed from the tracker. We use
  67 // |CallbackTracker| for two things: (1) to ensure that all callbacks are
  68 // properly aborted before instance shutdown, and (2) to ensure that all
  69 // callbacks associated with a given resource are aborted when a plugin instance
  70 // releases its last reference to that resource.
  71 class PPAPI_SHARED_EXPORT CallbackTracker
  72     : public base::RefCountedThreadSafe<CallbackTracker> {
  73  public:
  74   CallbackTracker();
  75
  76   // Abort all callbacks (synchronously).
  77   void AbortAll();
  78
  79   // Abort all callbacks associated to the given resource ID (which must be
  80   // valid, i.e., nonzero) by posting a task (or tasks).
  81   void PostAbortForResource(PP_Resource resource_id);
  82
  83  private:
  84   friend class base::RefCountedThreadSafe<CallbackTracker>;
  85   ~CallbackTracker();
  86
  87   // |TrackedCallback| are expected to automatically add and
  88   // remove themselves from their provided |CallbackTracker|.
  89   friend class TrackedCallback;
  90   void Add(const scoped_refptr<TrackedCallback>& tracked_callback);
  91   void Remove(const scoped_refptr<TrackedCallback>& tracked_callback);
  92
  93   // For each resource ID with a pending callback, store a set with its pending
  94   // callbacks. (Resource ID 0 is used for callbacks not associated to a valid
  95   // resource.) If a resource ID is re-used for another resource, there may be
  96   // aborted callbacks corresponding to the original resource in that set; these
  97   // will be removed when they are completed (abortively).
  98   typedef std::set<scoped_refptr<TrackedCallback> > CallbackSet;
  99   typedef std::map<PP_Resource, CallbackSet> CallbackSetMap;
 100   CallbackSetMap pending_callbacks_;
 101
 102   // Used to ensure we don't add any callbacks after AbortAll.
 103   bool abort_all_called_;
 104
 105   base::Lock lock_;
 106
 107   DISALLOW_COPY_AND_ASSIGN(CallbackTracker);
 108 };
 109
 110 }  // namespace ppapi
 111
 112 #endif  // PPAPI_SHARED_IMPL_CALLBACK_TRACKER_H_