| // Copyright (c) 2011 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 PPAPI_SHARED_IMPL_CALLBACK_TRACKER_H_ |
| #define PPAPI_SHARED_IMPL_CALLBACK_TRACKER_H_ |
| |
| #include <map> |
| #include <set> |
| |
| #include "base/macros.h" |
| #include "base/memory/ref_counted.h" |
| #include "base/synchronization/lock.h" |
| #include "ppapi/c/pp_resource.h" |
| #include "ppapi/shared_impl/ppapi_shared_export.h" |
| |
| namespace ppapi { |
| |
| class TrackedCallback; |
| |
| // Pepper callbacks have the following semantics (unless otherwise specified; |
| // in particular, the below apply to all completion callbacks): |
| // - Callbacks are always run on the thread where the plugin called a Pepper |
| // function providing that callback. |
| // - Callbacks are always called from the message loop of the thread. In |
| // particular, calling into Pepper will not result in the plugin being |
| // re-entered via a synchronously-run callback. |
| // - Each callback will be executed (a.k.a. completed) exactly once. |
| // - Each callback may be *aborted*, which means that it will be executed with |
| // result |PP_ERROR_ABORTED| (in the case of completion callbacks). The |
| // ABORT counts as the callback's one completion. |
| // - Before |PPP_ShutdownModule()| is called, every pending callback (for every |
| // instance of that module) will be aborted. |
| // - Callbacks are usually associated to a resource, whose "deletion" provides |
| // a "cancellation" (or abort) mechanism -- see below. |
| // - When a plugin releases its last reference to resource, all callbacks |
| // associated to that resource are aborted. Even if a non-abortive completion |
| // of such a callback had previously been scheduled (i.e., posted), that |
| // callback must now be aborted. The aborts should be scheduled immediately |
| // (upon the last reference being given up) and should not rely on anything |
| // else (e.g., a background task to complete or further action from the |
| // plugin). |
| // - Abortive completion gives no information about the status of the |
| // asynchronous operation: The operation may have not yet begun, may be in |
| // progress, or may be completed (successfully or not). In fact, the |
| // operation may still proceed after the callback has been aborted. |
| // - Any output data buffers provided to Pepper are associated with a resource. |
| // Once that resource is released, no subsequent writes to those buffers |
| // will occur. When operations occur on background threads, writing to the |
| // plugin's data buffers should be delayed to happen on the callback's thread |
| // to ensure that we don't write to the buffers if the callback has been |
| // aborted (see TrackedCallback::set_completion_task()). |
| // |
| // Thread-safety notes: |
| // |CallbackTracker| uses a lock to protect its dictionary of callbacks. This |
| // is primarily to allow the safe removal of callbacks from any thread without |
| // requiring that the |ProxyLock| is held. Methods that may invoke a callback |
| // need to have the |ProxyLock| (and those methods assert that it's acquired). |
| // |TrackedCallback| is thread-safe ref-counted, so objects which live on |
| // different threads may keep references. Releasing a reference to |
| // |TrackedCallback| on a different thread (possibly causing destruction) is |
| // also okay. |
| // |
| // |CallbackTracker| tracks pending Pepper callbacks for a single instance. It |
| // also tracks, for each resource ID, which callbacks are pending. Just before |
| // a callback is completed, it is removed from the tracker. We use |
| // |CallbackTracker| for two things: (1) to ensure that all callbacks are |
| // properly aborted before instance shutdown, and (2) to ensure that all |
| // callbacks associated with a given resource are aborted when a plugin instance |
| // releases its last reference to that resource. |
| class PPAPI_SHARED_EXPORT CallbackTracker |
| : public base::RefCountedThreadSafe<CallbackTracker> { |
| public: |
| CallbackTracker(); |
| |
| // Abort all callbacks (synchronously). |
| void AbortAll(); |
| |
| // Abort all callbacks associated to the given resource ID (which must be |
| // valid, i.e., nonzero) by posting a task (or tasks). |
| void PostAbortForResource(PP_Resource resource_id); |
| |
| private: |
| friend class base::RefCountedThreadSafe<CallbackTracker>; |
| ~CallbackTracker(); |
| |
| // |TrackedCallback| are expected to automatically add and |
| // remove themselves from their provided |CallbackTracker|. |
| friend class TrackedCallback; |
| void Add(const scoped_refptr<TrackedCallback>& tracked_callback); |
| void Remove(const scoped_refptr<TrackedCallback>& tracked_callback); |
| |
| // For each resource ID with a pending callback, store a set with its pending |
| // callbacks. (Resource ID 0 is used for callbacks not associated to a valid |
| // resource.) If a resource ID is re-used for another resource, there may be |
| // aborted callbacks corresponding to the original resource in that set; these |
| // will be removed when they are completed (abortively). |
| typedef std::set<scoped_refptr<TrackedCallback> > CallbackSet; |
| typedef std::map<PP_Resource, CallbackSet> CallbackSetMap; |
| CallbackSetMap pending_callbacks_; |
| |
| // Used to ensure we don't add any callbacks after AbortAll. |
| bool abort_all_called_; |
| |
| base::Lock lock_; |
| |
| DISALLOW_COPY_AND_ASSIGN(CallbackTracker); |
| }; |
| |
| } // namespace ppapi |
| |
| #endif // PPAPI_SHARED_IMPL_CALLBACK_TRACKER_H_ |