xref: /aosp_15_r20/external/fbjni/cxx/fbjni/detail/References.h (revision 65c59e023c5336bbd4a23be7af78407e3d80e7e7)

/*
 * Copyright (c) Facebook, Inc. and its affiliates.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/** @file References.h
 *
 * Functionality similar to smart pointers, but for references into the VM. Four
 * main reference types are provided: local_ref, global_ref, weak_ref, and
 * alias_ref. All are generic templates that and refer to objects in the jobject
 * hierarchy. The type of the referred objects are specified using the template
 * parameter. All reference types except alias_ref own their underlying
 * reference, just as a std smart pointer owns the underlying raw pointer. In
 * the context of std smart pointers, these references behave like unique_ptr,
 * and have basically the same interface. Thus, when the reference is
 * destructed, the plain JNI reference, i.e. the underlying JNI reference (like
 * the parameters passed directly to JNI functions), is released. The alias
 * references provides no ownership and is a simple wrapper for plain JNI
 * references.
 *
 * All but the weak references provides access to the underlying object using
 * dereferencing, and a get() method. It is also possible to convert these
 * references to booleans to test for nullity. To access the underlying object
 * of a weak reference, the reference must either be released, or the weak
 * reference can be used to create a local or global reference.
 *
 * An owning reference is created either by moving the reference from an
 * existing owned reference, by copying an existing owned reference (which
 * creates a new underlying reference), by using the default constructor which
 * initialize the reference to nullptr, or by using a helper function. The
 * helper function exist in two flavors: make_XXX or adopt_XXX.
 *
 * Adopting takes a plain JNI reference and wrap it in an owned reference. It
 * takes ownership of the plain JNI reference so be sure that no one else owns
 * the reference when you adopt it, and make sure that you know what kind of
 * reference it is.
 *
 * New owned references can be created from existing plain JNI references, alias
 * references, local references, and global references (i.e. non-weak
 * references) using the make_local, make_global, and make_weak functions.
 *
 * Alias references can be implicitly initialized using global, local and plain
 * JNI references using the wrap_alias function. Here, we don't assume ownership
 * of the passed-in reference, but rather create a separate reference that we do
 * own, leaving the passed-in reference to its fate.
 *
 * Similar rules apply for assignment. An owned reference can be copy or move
 * assigned using a smart reference of the same type. In the case of copy
 * assignment a new reference is created. Alias reference can also be assigned
 * new values, but since they are simple wrappers of plain JNI references there
 * is no move semantics involved.
 *
 * Alias references are special in that they do not own the object and can
 * therefore safely be converted to and from its corresponding plain JNI
 * reference. They are useful as parameters of functions that do not affect the
 * lifetime of a reference. Usage can be compared with using plain JNI pointers
 * as parameters where a function does not take ownership of the underlying
 * object.
 *
 * The local, global, and alias references makes it possible to access methods
 * in the underlying objects. A core set of classes are implemented in
 * CoreClasses.h, and user defined wrappers are supported (see example below).
 * The wrappers also supports inheritance so a wrapper can inherit from another
 * wrapper to gain access to its functionality. As an example the jstring
 * wrapper inherits from the jobject wrapper, so does the jclass wrapper. That
 * means that you can for example call the toString() method using the jclass
 * wrapper, or any other class that inherits from the jobject wrapper.
 *
 * Note that the wrappers are parameterized on the static type of your (jobject)
 * pointer, thus if you have a jobject that refers to a Java String you will
 * need to cast it to jstring to get the jstring wrapper. This also mean that if
 * you make a down cast that is invalid there will be no one stopping you and
 * the wrappers currently does not detect this which can cause crashes. Thus,
 * cast wisely.
 *
 * @include WrapperSample.cpp
 */

#pragma once

#include <cassert>
#include <cstddef>
#include <type_traits>

#include <jni.h>

#include "ReferenceAllocators.h"
#include "References-forward.h"
#include "TypeTraits.h"

namespace facebook {
namespace jni {

/// Convenience function to wrap an existing local reference
template <typename T>
local_ref<T> adopt_local(T ref) noexcept;

/// Convenience function to wrap an existing global reference
template <typename T>
global_ref<T> adopt_global(T ref) noexcept;

/// Convenience function to wrap an existing weak reference
template <typename T>
weak_ref<T> adopt_weak_global(T ref) noexcept;

/// Swaps two owning references of the same type
template <typename T>
void swap(weak_ref<T>& a, weak_ref<T>& b) noexcept;

/// Swaps two owning references of the same type
template <typename T, typename Alloc>
void swap(
    basic_strong_ref<T, Alloc>& a,
    basic_strong_ref<T, Alloc>& b) noexcept;

/**
 * Retrieve the plain reference from a plain reference.
 */
template <typename T>
enable_if_t<IsPlainJniReference<T>(), T> getPlainJniReference(T ref);

/**
 * Retrieve the plain reference from an alias reference.
 */
template <typename T>
JniType<T> getPlainJniReference(alias_ref<T> ref);

/**
 * Retrieve the plain JNI reference from any reference owned reference.
 */
template <typename T, typename Alloc>
JniType<T> getPlainJniReference(const base_owned_ref<T, Alloc>& ref);

class JObject;
class JClass;

namespace detail {

template <typename T>
constexpr bool IsJavaClassType() {
  return std::is_base_of<JObject, T>::value;
}

template <typename T, typename Enable = void>
struct HasJniRefRepr : std::false_type {};

template <typename T>
struct HasJniRefRepr<
    T,
    typename std::enable_if<
        !std::is_same<typename T::JniRefRepr, void>::value,
        void>::type> : std::true_type {
  using type = typename T::JniRefRepr;
};

template <typename T>
struct RefReprType<T*> {
  static_assert(HasJniRefRepr<T>::value, "Repr type missing JniRefRepr.");
  using type = typename HasJniRefRepr<T>::type;
  static_assert(IsJavaClassType<type>(), "Repr type missing JObject base.");
  static_assert(
      std::is_same<type, typename RefReprType<type>::type>::value,
      "RefReprType<T> not idempotent");
};

template <typename T>
struct RefReprType<
    T,
    typename std::enable_if<IsJavaClassType<T>(), void>::type> {
  using type = T;
  static_assert(IsJavaClassType<type>(), "Repr type missing JObject base.");
  static_assert(
      std::is_same<type, typename RefReprType<type>::type>::value,
      "RefReprType<T> not idempotent");
};

template <typename T>
struct JavaObjectType {
  using type = typename RefReprType<T>::type::javaobject;
  static_assert(
      IsPlainJniReference<type>(),
      "JavaObjectType<T> not a plain jni reference");
  static_assert(
      std::is_same<type, typename JavaObjectType<type>::type>::value,
      "JavaObjectType<T> not idempotent");
};

template <typename T>
struct JavaObjectType<T*> {
  using type = T*;
  static_assert(
      IsPlainJniReference<type>(),
      "JavaObjectType<T> not a plain jni reference");
  static_assert(
      std::is_same<type, typename JavaObjectType<type>::type>::value,
      "JavaObjectType<T> not idempotent");
};

template <typename T>
struct PrimitiveOrJavaObjectType<T, enable_if_t<IsJniPrimitive<T>(), void>> {
  using type = T;
  static_assert(
      IsJniPrimitive<type>(),
      "PrimitiveOrJavaObjectType<T> not a jni primitive");
  static_assert(
      std::is_same<type, typename PrimitiveOrJavaObjectType<type>::type>::value,
      "PrimitiveOrJavaObjectType<T> not idempotent");
};

template <typename T>
struct PrimitiveOrJavaObjectType<
    T,
    enable_if_t<IsPlainJniReference<T>(), void>> {
  using type = T;
  static_assert(
      IsPlainJniReference<type>(),
      "PrimitiveOrJavaObjectType<T> not a plain jni reference");
  static_assert(
      std::is_same<type, typename PrimitiveOrJavaObjectType<type>::type>::value,
      "PrimitiveOrJavaObjectType<T> not idempotent");
};

template <typename T>
struct PrimitiveOrJavaObjectType<T, enable_if_t<IsJavaClassType<T>(), void>> {
  using type = JniType<T>;
  static_assert(
      IsPlainJniReference<type>(),
      "PrimitiveOrJavaObjectType<T> not a plain jni reference");
  static_assert(
      std::is_same<type, typename PrimitiveOrJavaObjectType<type>::type>::value,
      "PrimitiveOrJavaObjectType<T> not idempotent");
};

template <typename Repr>
struct ReprStorage {
  explicit ReprStorage(JniType<Repr> obj) noexcept;

  void set(JniType<Repr> obj) noexcept;

  Repr& get() noexcept;
  const Repr& get() const noexcept;
  JniType<Repr> jobj() const noexcept;

  void swap(ReprStorage& other) noexcept;

  ReprStorage() = delete;
  ReprStorage(const ReprStorage&) = delete;
  ReprStorage(ReprStorage&&) = delete;
  ReprStorage& operator=(const ReprStorage&) = delete;
  ReprStorage& operator=(ReprStorage&&) = delete;

 private:
  using Storage = typename std::
      aligned_storage<sizeof(JObjectBase), alignof(JObjectBase)>::type;
  Storage storage_;
};

} // namespace detail

/**
 * Create a new local reference from an existing reference
 *
 * @param ref a plain JNI, alias, or strong reference
 * @return an owned local reference (referring to null if the input does)
 * @throws std::bad_alloc if the JNI reference could not be created
 */
template <typename T>
enable_if_t<IsNonWeakReference<T>(), local_ref<plain_jni_reference_t<T>>>
make_local(const T& ref);

/**
 * Create a new global reference from an existing reference
 *
 * @param ref a plain JNI, alias, or strong reference
 * @return an owned global reference (referring to null if the input does)
 * @throws std::bad_alloc if the JNI reference could not be created
 */
template <typename T>
enable_if_t<IsNonWeakReference<T>(), global_ref<plain_jni_reference_t<T>>>
make_global(const T& ref);

/**
 * Create a new weak global reference from an existing reference
 *
 * @param ref a plain JNI, alias, or strong reference
 * @return an owned weak global reference (referring to null if the input does)
 * @throws std::bad_alloc if the returned reference is null
 */
template <typename T>
enable_if_t<IsNonWeakReference<T>(), weak_ref<plain_jni_reference_t<T>>>
make_weak(const T& ref);

/**
 * Compare two references to see if they refer to the same object
 */
template <typename T1, typename T2>
enable_if_t<IsNonWeakReference<T1>() && IsNonWeakReference<T2>(), bool>
operator==(const T1& a, const T2& b);

/**
 * Compare two references to see if they don't refer to the same object
 */
template <typename T1, typename T2>
enable_if_t<IsNonWeakReference<T1>() && IsNonWeakReference<T2>(), bool>
operator!=(const T1& a, const T2& b);

/**
 * Compare references against nullptr
 */
template <typename T1>
enable_if_t<IsNonWeakReference<T1>(), bool> operator==(
    const T1& a,
    std::nullptr_t);

template <typename T1>
enable_if_t<IsNonWeakReference<T1>(), bool> operator==(
    std::nullptr_t,
    const T1& a);

template <typename T1>
enable_if_t<IsNonWeakReference<T1>(), bool> operator!=(
    const T1& a,
    std::nullptr_t);

template <typename T1>
enable_if_t<IsNonWeakReference<T1>(), bool> operator!=(
    std::nullptr_t,
    const T1& a);

template <typename T, typename Alloc>
class base_owned_ref {
 public:
  using javaobject = JniType<T>;

  /**
   * Release the ownership and set the reference to null. Thus no deleter is
   * invoked.
   * @return Returns the reference
   */
  javaobject release() noexcept;

  /**
   * Reset the reference to refer to nullptr.
   */
  void reset() noexcept;

 protected:
  using Repr = ReprType<T>;
  detail::ReprStorage<Repr> storage_;

  javaobject get() const noexcept;
  void set(javaobject ref) noexcept;

  /*
   * Wrap an existing reference and transfers its ownership to the newly created
   * unique reference. NB! Does not create a new reference
   */
  explicit base_owned_ref(javaobject reference) noexcept;

  /// Create a null reference
  base_owned_ref() noexcept;

  /// Create a null reference
  explicit base_owned_ref(std::nullptr_t) noexcept;

  /// Copy constructor (note creates a new reference)
  base_owned_ref(const base_owned_ref& other);
  template <typename U>
  base_owned_ref(const base_owned_ref<U, Alloc>& other);

  /// Transfers ownership of an underlying reference from one unique reference
  /// to another
  base_owned_ref(base_owned_ref&& other) noexcept;
  template <typename U>
  base_owned_ref(base_owned_ref<U, Alloc>&& other) noexcept;

  /// The delete the underlying reference if applicable
  ~base_owned_ref() noexcept;

  /// Assignment operator (note creates a new reference)
  base_owned_ref& operator=(const base_owned_ref& other);

  /// Assignment by moving a reference thus not creating a new reference
  base_owned_ref& operator=(base_owned_ref&& rhs) noexcept;

  void reset(javaobject reference) noexcept;

  friend javaobject jni::getPlainJniReference<>(
      const base_owned_ref<T, Alloc>& ref);

  template <typename U, typename UAlloc>
  friend class base_owned_ref;
};

/**
 * A smart reference that owns its underlying JNI reference. The class provides
 * basic functionality to handle a reference but gives no access to it unless
 * the reference is released, thus no longer owned. The API is stolen with pride
 * from unique_ptr and the semantics should be basically the same. This class
 * should not be used directly, instead use
 * @ref weak_ref
 */
template <typename T>
class weak_ref : public base_owned_ref<T, WeakGlobalReferenceAllocator> {
 public:
  using javaobject = JniType<T>;

  using Allocator = WeakGlobalReferenceAllocator;

  // This inherits non-default, non-copy, non-move ctors.
  using base_owned_ref<T, Allocator>::base_owned_ref;

  /// Create a null reference
  weak_ref() noexcept : base_owned_ref<T, Allocator>{} {}

  /// Create a null reference
  /* implicit */ weak_ref(std::nullptr_t) noexcept
      : base_owned_ref<T, Allocator>{nullptr} {}

  /// Copy constructor (note creates a new reference)
  weak_ref(const weak_ref& other) : base_owned_ref<T, Allocator>{other} {}

  // This needs to be explicit to change its visibility.
  template <typename U>
  weak_ref(const weak_ref<U>& other) : base_owned_ref<T, Allocator>{other} {}

  /// Transfers ownership of an underlying reference from one unique reference
  /// to another
  weak_ref(weak_ref&& other) noexcept
      : base_owned_ref<T, Allocator>{std::move(other)} {}

  // Move from ref to compatible type.
  template <typename U>
  weak_ref(weak_ref<U>&& other)
      : base_owned_ref<T, Allocator>{std::move(other)} {}

  /// Assignment operator (note creates a new reference)
  weak_ref& operator=(const weak_ref& other);

  /// Assignment by moving a reference thus not creating a new reference
  weak_ref& operator=(weak_ref&& rhs) noexcept;

  // Creates an owned local reference to the referred object or to null if the
  // object is reclaimed
  local_ref<T> lockLocal() const;

  // Creates an owned global reference to the referred object or to null if the
  // object is reclaimed
  global_ref<T> lockGlobal() const;

 private:
  // get/release/reset on weak_ref are not exposed to users.
  using base_owned_ref<T, Allocator>::get;
  using base_owned_ref<T, Allocator>::release;
  using base_owned_ref<T, Allocator>::reset;
  /*
   * Wrap an existing reference and transfers its ownership to the newly created
   * unique reference. NB! Does not create a new reference
   */
  explicit weak_ref(javaobject reference) noexcept
      : base_owned_ref<T, Allocator>{reference} {}

  template <typename T2>
  friend class weak_ref;
  friend weak_ref<javaobject> adopt_weak_global<javaobject>(
      javaobject ref) noexcept;
  friend void swap<T>(weak_ref& a, weak_ref& b) noexcept;
};

/**
 * A class representing owned strong references to Java objects. This class
 * should not be used directly, instead use @ref local_ref, or @ref global_ref.
 */
template <typename T, typename Alloc>
class basic_strong_ref : public base_owned_ref<T, Alloc> {
  using typename base_owned_ref<T, Alloc>::Repr;

 public:
  using javaobject = JniType<T>;

  using Allocator = Alloc;

  // This inherits non-default, non-copy, non-move ctors.
  using base_owned_ref<T, Alloc>::base_owned_ref;
  using base_owned_ref<T, Alloc>::release;
  using base_owned_ref<T, Alloc>::reset;

  /// Create a null reference
  basic_strong_ref() noexcept : base_owned_ref<T, Alloc>{} {}

  /// Create a null reference
  /* implicit */ basic_strong_ref(std::nullptr_t) noexcept
      : base_owned_ref<T, Alloc>{nullptr} {}

  /// Copy constructor (note creates a new reference)
  basic_strong_ref(const basic_strong_ref& other)
      : base_owned_ref<T, Alloc>{other} {}

  // This needs to be explicit to change its visibility.
  template <typename U>
  basic_strong_ref(const basic_strong_ref<U, Alloc>& other)
      : base_owned_ref<T, Alloc>{other} {}

  // Move from ref to compatible type.
  template <typename U>
  basic_strong_ref(basic_strong_ref<U, Alloc>&& other)
      : base_owned_ref<T, Alloc>{std::move(other)} {}

  /// Transfers ownership of an underlying reference from one unique reference
  /// to another
  basic_strong_ref(basic_strong_ref&& other) noexcept
      : base_owned_ref<T, Alloc>{std::move(other)} {}

  /// Assignment operator (note creates a new reference)
  basic_strong_ref& operator=(const basic_strong_ref& other);

  /// Assignment by moving a reference thus not creating a new reference
  basic_strong_ref& operator=(basic_strong_ref&& rhs) noexcept;

  /// Get the plain JNI reference
  using base_owned_ref<T, Allocator>::get;

  /// Release the ownership of the reference and return the wrapped reference in
  /// an alias
  alias_ref<T> releaseAlias() noexcept;

  /// Checks if the reference points to a non-null object
  explicit operator bool() const noexcept;

  /// Access the functionality provided by the object wrappers
  Repr* operator->() noexcept;

  /// Access the functionality provided by the object wrappers
  const Repr* operator->() const noexcept;

  /// Provide a reference to the underlying wrapper (be sure that it is non-null
  /// before invoking)
  Repr& operator*() noexcept;

  /// Provide a const reference to the underlying wrapper (be sure that it is
  /// non-null before invoking)
  const Repr& operator*() const noexcept;

 private:
  using base_owned_ref<T, Alloc>::storage_;

  /*
   * Wrap an existing reference and transfers its ownership to the newly created
   * unique reference. NB! Does not create a new reference
   */
  explicit basic_strong_ref(javaobject reference) noexcept
      : base_owned_ref<T, Alloc>{reference} {}

  friend local_ref<T> adopt_local<T>(T ref) noexcept;
  friend global_ref<T> adopt_global<T>(T ref) noexcept;
  friend void swap<T, Alloc>(basic_strong_ref& a, basic_strong_ref& b) noexcept;
};

template <typename T>
enable_if_t<IsPlainJniReference<T>(), alias_ref<T>> wrap_alias(T ref) noexcept;

/// Swaps to alias reference of the same type
template <typename T>
void swap(alias_ref<T>& a, alias_ref<T>& b) noexcept;

/**
 * A non-owning variant of the smart references (a dumb
 * reference). Use this representation when you don't want to claim
 * ownership of the underlying reference (compare to using raw
 * pointers instead of smart pointers.)
 */
template <typename T>
class alias_ref {
  using Repr = ReprType<T>;

 public:
  using javaobject = JniType<T>;

  /// Create a null reference
  alias_ref() noexcept;

  /// Create a null reference
  /* implicit */ alias_ref(std::nullptr_t) noexcept;

  /// Copy constructor
  alias_ref(const alias_ref& other) noexcept;

  /// Wrap an existing plain JNI reference
  /* implicit */ alias_ref(javaobject ref) noexcept;

  /// Wrap an existing smart reference of any type convertible to T
  template <
      typename TOther,
      typename = enable_if_t<IsConvertible<JniType<TOther>, javaobject>(), T>>
  alias_ref(alias_ref<TOther> other) noexcept;

  /// Wrap an existing alias reference of a type convertible to T
  template <
      typename TOther,
      typename AOther,
      typename = enable_if_t<IsConvertible<JniType<TOther>, javaobject>(), T>>
  alias_ref(const basic_strong_ref<TOther, AOther>& other) noexcept;

  /// Assignment operator
  alias_ref& operator=(alias_ref other) noexcept;

  /// Checks if the reference points to a non-null object
  explicit operator bool() const noexcept;

  /// Converts back to a plain JNI reference
  javaobject get() const noexcept;

  /// Access the functionality provided by the object wrappers
  Repr* operator->() noexcept;

  /// Access the functionality provided by the object wrappers
  const Repr* operator->() const noexcept;

  /// Provide a guaranteed non-null reference (be sure that it is non-null
  /// before invoking)
  Repr& operator*() noexcept;

  /// Provide a guaranteed non-null reference (be sure that it is non-null
  /// before invoking)
  const Repr& operator*() const noexcept;

 private:
  void set(javaobject ref) noexcept;

  detail::ReprStorage<Repr> storage_;

  friend void swap<T>(alias_ref& a, alias_ref& b) noexcept;
};

/**
 * RAII object to create a local JNI frame, using PushLocalFrame/PopLocalFrame.
 *
 * This is useful when you have a call which is initiated from C++-land, and
 * therefore doesn't automatically get a local JNI frame managed for you by the
 * JNI framework.
 */
class JniLocalScope {
 public:
  JniLocalScope(JNIEnv* p_env, jint capacity);
  ~JniLocalScope();

 private:
  JNIEnv* env_;
  bool hasFrame_;
};

template <typename T, typename U>
enable_if_t<IsPlainJniReference<JniType<T>>(), local_ref<T>> static_ref_cast(
    const local_ref<U>& ref) noexcept;

template <typename T, typename U>
enable_if_t<IsPlainJniReference<JniType<T>>(), global_ref<T>> static_ref_cast(
    const global_ref<U>& ref) noexcept;

template <typename T, typename U>
enable_if_t<IsPlainJniReference<JniType<T>>(), alias_ref<T>> static_ref_cast(
    const alias_ref<U>& ref) noexcept;

template <typename T, typename RefType>
auto dynamic_ref_cast(const RefType& ref)
    -> enable_if_t<
        IsPlainJniReference<JniType<T>>(),
        decltype(static_ref_cast<T>(ref))>;

} // namespace jni
} // namespace facebook

#include "References-inl.h"