15821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Copyright (c) 2012 The Chromium Authors. All rights reserved. 25821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Use of this source code is governed by a BSD-style license that can be 35821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// found in the LICENSE file. 45821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 55821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#ifndef PPAPI_SHARED_IMPL_TRACKED_CALLBACK_H_ 65821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define PPAPI_SHARED_IMPL_TRACKED_CALLBACK_H_ 75821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 85821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include <map> 95821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include <set> 105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "base/basictypes.h" 12ba5b9a6411cb1792fd21f0a078d7a25cd1ceec16Ben Murdoch#include "base/callback.h" 135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "base/memory/ref_counted.h" 145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "base/memory/scoped_ptr.h" 155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "base/synchronization/condition_variable.h" 165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "ppapi/c/pp_completion_callback.h" 175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "ppapi/c/pp_instance.h" 185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "ppapi/c/pp_resource.h" 195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "ppapi/shared_impl/ppapi_shared_export.h" 205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "ppapi/shared_impl/ppb_message_loop_shared.h" 215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)namespace ppapi { 235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class CallbackTracker; 255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class MessageLoopShared; 265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class Resource; 275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)namespace thunk { 295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)namespace subtle { 305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// For a friend declaration below. 315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class EnterBase; 325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)} 335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)} 345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// |TrackedCallback| represents a tracked Pepper callback (from the browser to 365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// the plugin), typically still pending. Such callbacks have the standard Pepper 375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// callback semantics. Execution (i.e., completion) of callbacks happens through 385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// objects of subclasses of |TrackedCallback|. Two things are ensured: (1) that 395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// the callback is executed at most once, and (2) once a callback is marked to 405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// be aborted, any subsequent completion is abortive (even if a non-abortive 415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// completion had previously been scheduled). 425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// 435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// The details of non-abortive completion depend on the type of callback (e.g., 445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// different parameters may be required), but basic abort functionality is core. 455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// The ability to post aborts is needed in many situations to ensure that the 465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// plugin is not re-entered into. (Note that posting a task to just run 475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// |Abort()| is different and not correct; calling |PostAbort()| additionally 485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// guarantees that all subsequent completions will be abortive.) 495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// 505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// This class is reference counted so that different things can hang on to it, 515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// and not worry too much about ensuring Pepper callback semantics. Note that 525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// the "owning" |CallbackTracker| will keep a reference until the callback is 535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// completed. 545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// 555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Subclasses must do several things: 565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// - They must ensure that the callback is executed at most once (by looking at 575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// |completed()| before running the callback). 585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// - They must ensure that the callback is run abortively if it is marked as to 595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// be aborted (by looking at |aborted()| before running the callback). 605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// - They must call |MarkAsCompleted()| immediately before actually running the 615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// callback; see the comment for |MarkAsCompleted()| for a caveat. 625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class PPAPI_SHARED_EXPORT TrackedCallback 635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) : public base::RefCountedThreadSafe<TrackedCallback> { 645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) public: 655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Create a tracked completion callback and register it with the tracker. The 665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // resource pointer is not stored. If |resource| is NULL, this callback will 675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // not be added to the callback tracker. 685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) TrackedCallback(Resource* resource, const PP_CompletionCallback& callback); 695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // These run the callback in an abortive manner, or post a task to do so (but 715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // immediately marking the callback as to be aborted). 725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) void Abort(); 735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) void PostAbort(); 745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Run the callback with the given result. If the callback had previously been 765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // marked as to be aborted (by |PostAbort()|), |result| will be ignored and 775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // the callback will be run with result |PP_ERROR_ABORTED|. 785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // 795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Run() will invoke the call immediately, if invoked from the target thread 805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // (as determined by target_loop_). If invoked on a different thread, the 815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // callback will be scheduled to run later on target_loop_. 825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) void Run(int32_t result); 835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // PostRun is like Run(), except it guarantees that the callback will be run 845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // later. In particular, if you invoke PostRun on the same thread on which the 855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // callback is targeted to run, it will *not* be run immediately. 865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) void PostRun(int32_t result); 875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 88ba5b9a6411cb1792fd21f0a078d7a25cd1ceec16Ben Murdoch // A task to perform cleanup or write output parameters before the callback 89ba5b9a6411cb1792fd21f0a078d7a25cd1ceec16Ben Murdoch // returns a result to the plugin. The |result| parameter has the result so 90ba5b9a6411cb1792fd21f0a078d7a25cd1ceec16Ben Murdoch // far, e.g. whether the callback has been aborted. If the callback hasn't 91ba5b9a6411cb1792fd21f0a078d7a25cd1ceec16Ben Murdoch // been aborted the return value of the task will become the callback result. 92ba5b9a6411cb1792fd21f0a078d7a25cd1ceec16Ben Murdoch // The task is always called on the same thread as the callback to the plugin. 93ba5b9a6411cb1792fd21f0a078d7a25cd1ceec16Ben Murdoch typedef base::Callback<int32_t(int32_t /* result */)> CompletionTask; 94ba5b9a6411cb1792fd21f0a078d7a25cd1ceec16Ben Murdoch 95ba5b9a6411cb1792fd21f0a078d7a25cd1ceec16Ben Murdoch // Sets a task that is run just before calling back into the plugin. This 96ba5b9a6411cb1792fd21f0a078d7a25cd1ceec16Ben Murdoch // should only be called once. 97ba5b9a6411cb1792fd21f0a078d7a25cd1ceec16Ben Murdoch void set_completion_task(const CompletionTask& completion_task); 985821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 995821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Returns the ID of the resource which "owns" the callback, or 0 if the 1005821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // callback is not associated with any resource. 1015821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PP_Resource resource_id() const { return resource_id_; } 1025821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1035821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Returns true if the callback was completed (possibly aborted). 1045821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) bool completed() const { return completed_; } 1055821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1065821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Returns true if the callback was or should be aborted; this will be the 1075821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // case whenever |Abort()| or |PostAbort()| is called before a non-abortive 1085821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // completion. 1095821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) bool aborted() const { return aborted_; } 1105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 111bb1529ce867d8845a77ec7cdf3e3003ef1771a40Ben Murdoch // Returns true if this is a blocking callback. 112a1401311d1ab56c4ed0a474bd38c108f75cb0cd9Torne (Richard Coles) bool is_blocking() { return !callback_.func; } 113bb1529ce867d8845a77ec7cdf3e3003ef1771a40Ben Murdoch 114a1401311d1ab56c4ed0a474bd38c108f75cb0cd9Torne (Richard Coles) MessageLoopShared* target_loop() const { return target_loop_.get(); } 1155d1f7b1de12d16ceb2c938c56701a3e8bfa558f7Torne (Richard Coles) 116fb250657ef40d7500f20882d5c9909c1013367d3Ben Murdoch // Determines if the given callback is pending. A callback is pending if it 117fb250657ef40d7500f20882d5c9909c1013367d3Ben Murdoch // has not completed and has not been aborted. When receiving a plugin call, 118fb250657ef40d7500f20882d5c9909c1013367d3Ben Murdoch // use this to detect if |callback| represents an operation in progress. When 119fb250657ef40d7500f20882d5c9909c1013367d3Ben Murdoch // finishing a plugin call, use this to determine whether to write 'out' 120fb250657ef40d7500f20882d5c9909c1013367d3Ben Murdoch // params and Run |callback|. 121fb250657ef40d7500f20882d5c9909c1013367d3Ben Murdoch // NOTE: an aborted callback has not necessarily completed, so a false result 122fb250657ef40d7500f20882d5c9909c1013367d3Ben Murdoch // doesn't imply that the callback has completed. 123fb250657ef40d7500f20882d5c9909c1013367d3Ben Murdoch // As a convenience, if |callback| is null, this returns false. 1245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) static bool IsPending(const scoped_refptr<TrackedCallback>& callback); 1255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 126558790d6acca3451cf3a6b497803a5f07d0bec58Ben Murdoch // Helper to determine if the given callback is scheduled to run on another 127558790d6acca3451cf3a6b497803a5f07d0bec58Ben Murdoch // message loop. 128558790d6acca3451cf3a6b497803a5f07d0bec58Ben Murdoch static bool IsScheduledToRun(const scoped_refptr<TrackedCallback>& callback); 129558790d6acca3451cf3a6b497803a5f07d0bec58Ben Murdoch 1305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) protected: 1315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) bool is_required() { 1325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) return (callback_.func && 1335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) !(callback_.flags & PP_COMPLETIONCALLBACK_FLAG_OPTIONAL)); 1345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) } 1355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) bool is_optional() { 1365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) return (callback_.func && 1375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) (callback_.flags & PP_COMPLETIONCALLBACK_FLAG_OPTIONAL)); 1385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) } 139868fa2fe829687343ffae624259930155e16dbd8Torne (Richard Coles) bool has_null_target_loop() const { return target_loop_.get() == NULL; } 1405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) private: 1425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // TrackedCallback and EnterBase manage dealing with how to invoke callbacks 1435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // appropriately. Pepper interface implementations and proxies should not have 1445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // to check the type of callback, block, or mark them complete explicitly. 1455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) friend class ppapi::thunk::subtle::EnterBase; 1465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Block until the associated operation has completed. Returns the result. 1485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // This must only be called on a non-main thread on a blocking callback. 1495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) int32_t BlockUntilComplete(); 1505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Mark this object as complete and remove it from the tracker. This must only 1525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // be called once. Note that running this may result in this object being 1535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // deleted (so keep a reference if it'll still be needed). 1545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) void MarkAsCompleted(); 1555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // This class is ref counted. 1575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) friend class base::RefCountedThreadSafe<TrackedCallback>; 1585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) virtual ~TrackedCallback(); 1595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Flag used by |PostAbort()| and |PostRun()| to check that we don't schedule 1615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // the callback more than once. 1625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) bool is_scheduled_; 1635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) scoped_refptr<CallbackTracker> tracker_; 1655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PP_Resource resource_id_; 1665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) bool completed_; 1675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) bool aborted_; 1685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PP_CompletionCallback callback_; 1695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 170ba5b9a6411cb1792fd21f0a078d7a25cd1ceec16Ben Murdoch // Task to run just before calling back into the plugin. 171ba5b9a6411cb1792fd21f0a078d7a25cd1ceec16Ben Murdoch CompletionTask completion_task_; 172ba5b9a6411cb1792fd21f0a078d7a25cd1ceec16Ben Murdoch 1735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // The MessageLoopShared on which this callback should be run. This will be 1745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // NULL if we're in-process. 1755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) scoped_refptr<MessageLoopShared> target_loop_; 1765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) int32_t result_for_blocked_callback_; 1785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // Used for pausing/waking the blocked thread if this is a blocking completion 1795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // callback. Note that in-process, there is no lock, blocking callbacks are 1805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // not allowed, and therefore this pointer will be NULL. 1815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) scoped_ptr<base::ConditionVariable> operation_completed_condvar_; 1825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) DISALLOW_IMPLICIT_CONSTRUCTORS(TrackedCallback); 1845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)}; 1855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)} // namespace ppapi 1875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#endif // PPAPI_SHARED_IMPL_TRACKED_CALLBACK_H_ 189