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_CPP_INSTANCE_HANDLE_H_ 65821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define PPAPI_CPP_INSTANCE_HANDLE_H_ 75821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 85821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include "ppapi/c/pp_instance.h" 95821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// @file 125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// This file defines an instance handle used to identify an instance in a 135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// constructor for a resource. 145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)namespace pp { 155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class Instance; 175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// An instance handle identifies an instance in a constructor for a resource. 195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// This class solves two different problems: 205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// 215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// 1. A pp::Instance object's lifetime is managed by the system on the main 225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// pepper thread of the module. This means that it may get destroyed at any 235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// time based on something that happens on the web page. Therefore, it's not 245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// safe to refer to a <code>pp::Instance</code> object on a background thread. 255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// Instead, we need to pass some kind of identifier to resource constructors 265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// so that they may safely be used on background threads. If the instance 275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// becomes invalid, the resource creation will fail on the background thread, 285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// but it won't crash. 295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// 305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// 2. <code>PP_Instance</code> would be a good identifier to use for this case. 315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// However, using <code>PP_Instance</code> in the constructor to resources is 325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// problematic because it is just a typedef for an integer, as is a 335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// <code>PP_Resource</code>. Many resources have alternate constructors that 345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// just take an existing <code>PP_Resource</code>, so the constructors would 355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// be ambiguous. Having this wrapper around a <code>PP_Instance</code> 365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// prevents this ambiguity, and also provides a nice place to consolidate an 375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// implicit conversion from <code>pp::Instance*</code> for prettier code on 385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// the main thread (you can just pass "this" to resource constructors in your 395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// instance objects). 405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// 415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// You should always pass an <code>InstanceHandle</code> to background threads 425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// instead of a <code>pp::Instance</code>, and use them in resource 435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)/// constructors and code that may be used from background threads. 445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class InstanceHandle { 455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) public: 465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// Implicit constructor for converting a <code>pp::Instance</code> to an 475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// instance handle. 485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @param[in] instance The instance with which this 505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// <code>InstanceHandle</code> will be associated. 515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) InstanceHandle(Instance* instance); 525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// This constructor explicitly converts a <code>PP_Instance</code> to an 545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// instance handle. This should not be implicit because it can make some 555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// resource constructors ambiguous. <code>PP_Instance</code> is just a 565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// typedef for an integer, as is <code>PP_Resource</code>, so the compiler 575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// can get confused between the two. 585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @param[in] pp_instance The instance with which this 605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// <code>InstanceHandle</code> will be associated. 615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) explicit InstanceHandle(PP_Instance pp_instance) 625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) : pp_instance_(pp_instance) {} 635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// The pp_instance() function returns the <code>PP_Instance</code>. 655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// 665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) /// @return A <code>PP_Instance</code> internal instance handle. 675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PP_Instance pp_instance() const { return pp_instance_; } 685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) private: 705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PP_Instance pp_instance_; 715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)}; 725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)} // namespace pp 745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#endif // PPAPI_CPP_INSTANCE_HANDLE_H_ 76