// Copyright (c) 2012 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

#ifndef PPAPI_CPP_INSTANCE_HANDLE_H_
#define PPAPI_CPP_INSTANCE_HANDLE_H_

#include "ppapi/c/pp_instance.h"

namespace pp {

class Instance;

/// An instance handle identifies an instance in a constructor for a resource.
/// Its existence solves two different problems:
///
/// A pp::Instance objects' lifetime is managed by the system on the main thread
/// of the plugin. This means that it may get destroyed at any time based on
/// something that happens on the web page. This means that it's never OK to
/// refer to a pp::Instance object on a background thread. So we need to pass
/// some kind of identifier instead to resource constructors so that they may
/// safely be used on background threads. If the instance becomes invalid, the
/// resource creation will fail on the background thread, but it won't crash.
///
/// Background: PP_Instance would be a good identifier to use for this case.
/// However, using it in the constructor to resources is problematic.
/// PP_Instance is just a typedef for an integer, as is a PP_Resource. Many
/// resources have alternate constructors that just take an existing
/// PP_Resource, so the constructors would be ambiguous. Having this wrapper
/// around a PP_Instance prevents this ambiguity, and also gives us a nice
/// place to consolidate an implicit conversion from pp::Instance* for prettier
/// code on the main thread (you can just pass "this" to resource constructors
/// in your instance objects).
///
/// So you should always pass InstanceHandles to background threads instead of
/// a pp::Instance, and use them in resource constructors and code that may be
/// used from background threads.
class InstanceHandle {
 public:
  /// Implicit constructor for converting a pp::Instance to an instance handle.
  InstanceHandle(Instance* instance);

  /// Explicitly convert a PP_Instance to an instance handle. This should not
  /// be implicit because it can make some resource constructors ambiguous.
  /// PP_Instance is just a typedef for an integer, as is PP_Resource, so the
  /// compiler can get confused between the two.
  explicit InstanceHandle(PP_Instance pp_instance)
      : pp_instance_(pp_instance) {}

  PP_Instance pp_instance() const { return pp_instance_; }

 private:
  PP_Instance pp_instance_;
};

}  // namespace pp

#endif  // PPAPI_CPP_INSTANCE_HANDLE_H_