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