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
16namespace ppapi {
17
18class 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.
64class 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