Home | History | Annotate | Download | only in shared_impl
      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_SHARED_IMPL_TRACKED_CALLBACK_H_
      6 #define PPAPI_SHARED_IMPL_TRACKED_CALLBACK_H_
      7 
      8 #include <map>
      9 #include <set>
     10 
     11 #include "base/basictypes.h"
     12 #include "base/callback.h"
     13 #include "base/memory/ref_counted.h"
     14 #include "base/memory/scoped_ptr.h"
     15 #include "base/synchronization/condition_variable.h"
     16 #include "ppapi/c/pp_completion_callback.h"
     17 #include "ppapi/c/pp_instance.h"
     18 #include "ppapi/c/pp_resource.h"
     19 #include "ppapi/shared_impl/ppapi_shared_export.h"
     20 #include "ppapi/shared_impl/ppb_message_loop_shared.h"
     21 
     22 namespace ppapi {
     23 
     24 class CallbackTracker;
     25 class MessageLoopShared;
     26 class Resource;
     27 
     28 namespace thunk {
     29 namespace subtle {
     30 // For a friend declaration below.
     31 class EnterBase;
     32 }
     33 }
     34 
     35 // |TrackedCallback| represents a tracked Pepper callback (from the browser to
     36 // the plugin), typically still pending. Such callbacks have the standard Pepper
     37 // callback semantics. Execution (i.e., completion) of callbacks happens through
     38 // objects of subclasses of |TrackedCallback|. Two things are ensured: (1) that
     39 // the callback is executed at most once, and (2) once a callback is marked to
     40 // be aborted, any subsequent completion is abortive (even if a non-abortive
     41 // completion had previously been scheduled).
     42 //
     43 // The details of non-abortive completion depend on the type of callback (e.g.,
     44 // different parameters may be required), but basic abort functionality is core.
     45 // The ability to post aborts is needed in many situations to ensure that the
     46 // plugin is not re-entered into. (Note that posting a task to just run
     47 // |Abort()| is different and not correct; calling |PostAbort()| additionally
     48 // guarantees that all subsequent completions will be abortive.)
     49 //
     50 // This class is reference counted so that different things can hang on to it,
     51 // and not worry too much about ensuring Pepper callback semantics. Note that
     52 // the "owning" |CallbackTracker| will keep a reference until the callback is
     53 // completed.
     54 //
     55 // Subclasses must do several things:
     56 //  - They must ensure that the callback is executed at most once (by looking at
     57 //    |completed()| before running the callback).
     58 //  - They must ensure that the callback is run abortively if it is marked as to
     59 //    be aborted (by looking at |aborted()| before running the callback).
     60 //  - They must call |MarkAsCompleted()| immediately before actually running the
     61 //    callback; see the comment for |MarkAsCompleted()| for a caveat.
     62 class PPAPI_SHARED_EXPORT TrackedCallback
     63     : public base::RefCountedThreadSafe<TrackedCallback> {
     64  public:
     65   // Create a tracked completion callback and register it with the tracker. The
     66   // resource pointer is not stored. If |resource| is NULL, this callback will
     67   // not be added to the callback tracker.
     68   TrackedCallback(Resource* resource, const PP_CompletionCallback& callback);
     69 
     70   // These run the callback in an abortive manner, or post a task to do so (but
     71   // immediately marking the callback as to be aborted).
     72   void Abort();
     73   void PostAbort();
     74 
     75   // Run the callback with the given result. If the callback had previously been
     76   // marked as to be aborted (by |PostAbort()|), |result| will be ignored and
     77   // the callback will be run with result |PP_ERROR_ABORTED|.
     78   //
     79   // Run() will invoke the call immediately, if invoked from the target thread
     80   // (as determined by target_loop_). If invoked on a different thread, the
     81   // callback will be scheduled to run later on target_loop_.
     82   void Run(int32_t result);
     83   // PostRun is like Run(), except it guarantees that the callback will be run
     84   // later. In particular, if you invoke PostRun on the same thread on which the
     85   // callback is targeted to run, it will *not* be run immediately.
     86   void PostRun(int32_t result);
     87 
     88   // A task to perform cleanup or write output parameters before the callback
     89   // returns a result to the plugin. The |result| parameter has the result so
     90   // far, e.g. whether the callback has been aborted. If the callback hasn't
     91   // been aborted the return value of the task will become the callback result.
     92   // The task is always called on the same thread as the callback to the plugin.
     93   typedef base::Callback<int32_t(int32_t /* result */)> CompletionTask;
     94 
     95   // Sets a task that is run just before calling back into the plugin. This
     96   // should only be called once.
     97   void set_completion_task(const CompletionTask& completion_task);
     98 
     99   // Returns the ID of the resource which "owns" the callback, or 0 if the
    100   // callback is not associated with any resource.
    101   PP_Resource resource_id() const { return resource_id_; }
    102 
    103   // Returns true if the callback was completed (possibly aborted).
    104   bool completed() const { return completed_; }
    105 
    106   // Returns true if the callback was or should be aborted; this will be the
    107   // case whenever |Abort()| or |PostAbort()| is called before a non-abortive
    108   // completion.
    109   bool aborted() const { return aborted_; }
    110 
    111   // Returns true if this is a blocking callback.
    112   bool is_blocking() {
    113     return !callback_.func;
    114   }
    115 
    116   // Determines if the given callback is pending. A callback is pending if it
    117   // has not completed and has not been aborted. When receiving a plugin call,
    118   // use this to detect if |callback| represents an operation in progress. When
    119   // finishing a plugin call, use this to determine whether to write 'out'
    120   // params and Run |callback|.
    121   // NOTE: an aborted callback has not necessarily completed, so a false result
    122   // doesn't imply that the callback has completed.
    123   // As a convenience, if |callback| is null, this returns false.
    124   static bool IsPending(const scoped_refptr<TrackedCallback>& callback);
    125 
    126   // Helper to determine if the given callback is scheduled to run on another
    127   // message loop.
    128   static bool IsScheduledToRun(const scoped_refptr<TrackedCallback>& callback);
    129 
    130  protected:
    131   bool is_required() {
    132     return (callback_.func &&
    133             !(callback_.flags & PP_COMPLETIONCALLBACK_FLAG_OPTIONAL));
    134   }
    135   bool is_optional() {
    136     return (callback_.func &&
    137             (callback_.flags & PP_COMPLETIONCALLBACK_FLAG_OPTIONAL));
    138   }
    139   bool has_null_target_loop() const { return target_loop_.get() == NULL; }
    140 
    141  private:
    142   // TrackedCallback and EnterBase manage dealing with how to invoke callbacks
    143   // appropriately. Pepper interface implementations and proxies should not have
    144   // to check the type of callback, block, or mark them complete explicitly.
    145   friend class ppapi::thunk::subtle::EnterBase;
    146 
    147   // Block until the associated operation has completed. Returns the result.
    148   // This must only be called on a non-main thread on a blocking callback.
    149   int32_t BlockUntilComplete();
    150 
    151   // Mark this object as complete and remove it from the tracker. This must only
    152   // be called once. Note that running this may result in this object being
    153   // deleted (so keep a reference if it'll still be needed).
    154   void MarkAsCompleted();
    155 
    156   // This class is ref counted.
    157   friend class base::RefCountedThreadSafe<TrackedCallback>;
    158   virtual ~TrackedCallback();
    159 
    160   // Flag used by |PostAbort()| and |PostRun()| to check that we don't schedule
    161   // the callback more than once.
    162   bool is_scheduled_;
    163 
    164   scoped_refptr<CallbackTracker> tracker_;
    165   PP_Resource resource_id_;
    166   bool completed_;
    167   bool aborted_;
    168   PP_CompletionCallback callback_;
    169 
    170   // Task to run just before calling back into the plugin.
    171   CompletionTask completion_task_;
    172 
    173   // The MessageLoopShared on which this callback should be run. This will be
    174   // NULL if we're in-process.
    175   scoped_refptr<MessageLoopShared> target_loop_;
    176 
    177   int32_t result_for_blocked_callback_;
    178   // Used for pausing/waking the blocked thread if this is a blocking completion
    179   // callback. Note that in-process, there is no lock, blocking callbacks are
    180   // not allowed, and therefore this pointer will be NULL.
    181   scoped_ptr<base::ConditionVariable> operation_completed_condvar_;
    182 
    183   DISALLOW_IMPLICIT_CONSTRUCTORS(TrackedCallback);
    184 };
    185 
    186 }  // namespace ppapi
    187 
    188 #endif  // PPAPI_SHARED_IMPL_TRACKED_CALLBACK_H_
    189