layout/android/jni

scoped_java_ref.h

// Generic base class for ScopedJavaLocalRef and ScopedJavaGlobalRef. Useful
// for allowing functions to accept a reference without having to mandate
// whether it is a local or global type.
// ScopedJavaLocalRef和ScopedJavaGlobalRef的通用基类
// 用于无论是本地类型还是全局类型，允许函数接受引用而无需授权
template <typename T>
class JavaRef : public JavaRef<jobject> {
 public:
  JavaRef() {}
  explicit JavaRef(std::nullptr_t) : JavaRef<jobject>(nullptr) {}
  ~JavaRef() {}

  T obj() const { return static_cast<T>(JavaRef<jobject>::obj()); }

 protected:
  JavaRef(JNIEnv* env, T obj) : JavaRef<jobject>(env, obj) {}

 private:
  // DISALLOW_COPY_AND_ASSIGN(JavaRef);
};

// Holds a local reference to a JNI method parameter.
// Method parameters should not be deleted, and so this class exists purely to
// wrap them as a JavaRef<T> in the JNI binding generator. Do not create
// instances manually.
// 保存对 JNI 方法参数的本地引用。
// 不应删除方法参数，
// 因此此类存在纯粹是为了将它们包装为 JNI 绑定生成器中的 JavaRef<T>。
// 不要手动创建实例。
template <typename T>
class JavaParamRef : public JavaRef<T> {
 public:
  // Assumes that |obj| is a parameter passed to a JNI method from Java.
  // Does not assume ownership as parameters should not be deleted.
  // 假设 |obj| 是从 Java 传递给 JNI 方法的参数。
  // 不承担所有权，因为参数不应被删除。
  JavaParamRef(JNIEnv* env, T obj) : JavaRef<T>(env, obj) {}

  // Allow nullptr to be converted to JavaParamRef. Some unit tests call JNI
  // methods directly from C++ and pass null for objects which are not actually
  // used by the implementation (e.g. the caller object); allow this to keep
  // working.
  // 允许将 nullptr 转换为 JavaParamRef。
  // 一些单元测试直接从 C++ 调用 JNI 方法，
  // 并为实现实际上没有使用的对象（例如调用者对象）传递 null；
  // 允许它继续工作。
  explicit JavaParamRef(std::nullptr_t) : JavaRef<T>(nullptr) {}

  ~JavaParamRef() {}

  // TODO(torne): remove this cast once we're using JavaRef consistently.
  // http://crbug.com/506850
  operator T() const { return JavaRef<T>::obj(); }

 private:
  // DISALLOW_COPY_AND_ASSIGN(JavaParamRef);
};

// Holds a local reference to a Java object. The local reference is scoped
// to the lifetime of this object.
// Instances of this class may hold onto any JNIEnv passed into it until
// destroyed. Therefore, since a JNIEnv is only suitable for use on a single
// thread, objects of this class must be created, used, and destroyed, on a
// single thread.
// Therefore, this class should only be used as a stack-based object and from a
// single thread. If you wish to have the reference outlive the current
// callstack (e.g. as a class member) or you wish to pass it across threads,
// use a ScopedJavaGlobalRef instead.
// 保存对 Java 对象的本地引用。
// 本地引用的范围是此对象的生命周期。
// 这个类的实例可以保留任何传入它的 JNIEnv 直到销毁。
// 因此，由于 JNIEnv 只适合在单个线程上使用，因此必须在单个线程上创建、使用和销毁此类的对象。
// 因此，此类应仅用作基于堆栈的对象并从单个线程使用。
// 如果您希望引用比当前调用堆栈更有效（例如作为类成员）或您希望跨线程传递它，
// 请使用 ScopedJavaGlobalRef替代。
template <typename T>
class ScopedJavaLocalRef : public JavaRef<T> {
 public:
  ScopedJavaLocalRef() : env_(nullptr) {}
  explicit ScopedJavaLocalRef(std::nullptr_t) : env_(nullptr) {}

  // Non-explicit copy constructor, to allow ScopedJavaLocalRef to be returned
  // by value as this is the normal usage pattern.
  ScopedJavaLocalRef(const ScopedJavaLocalRef<T>& other) : env_(other.env_) {
    this->SetNewLocalRef(env_, other.obj());
  }

  ScopedJavaLocalRef(ScopedJavaLocalRef<T>&& other) : env_(other.env_) { this->swap(other); }

  explicit ScopedJavaLocalRef(const JavaRef<T>& other) : env_(nullptr) { this->Reset(other); }

  // Assumes that |obj| is a local reference to a Java object and takes
  // ownership  of this local reference.
  // 假设 |obj| 是对 Java 对象的本地引用，并拥有此本地引用的所有权。 
  // TODO(torne): this shouldn't be used outside of JNI helper functions but
  // there are currently some cases where there aren't helpers for things.
  // TODO(torne)：这不应该在 JNI 辅助函数之外使用，但目前在某些情况下没有辅助函数。
  ScopedJavaLocalRef(JNIEnv* env, T obj) : JavaRef<T>(env, obj), env_(env) {}

  ~ScopedJavaLocalRef() { this->Reset(); }

  // Overloaded assignment operator defined for consistency with the implicit
  // copy constructor.
  // 为与隐式复制构造函数保持一致而定义的重载赋值运算符。
  void operator=(const ScopedJavaLocalRef<T>& other) { this->Reset(other); }

  void operator=(ScopedJavaLocalRef<T>&& other) {
    env_ = other.env_;
    this->swap(other);
  }

  void Reset() { this->ResetLocalRef(env_); }

  void Reset(const ScopedJavaLocalRef<T>& other) {
    // We can copy over env_ here as |other| instance must be from the same
    // thread as |this| local ref. (See class comment for multi-threading
    // limitations, and alternatives).
    // 我们可以在这里复制 env_ ，
    // 因为 |other| 实例必须来自与 |this|local ref 相同的线程
    //（有关多线程限制和替代方案，请参阅类注释）。
    this->Reset(other.env_, other.obj());
  }

  void Reset(const JavaRef<T>& other) {
    // If |env_| was not yet set (is still null) it will be attached to the
    // current thread in SetNewLocalRef().
    // 如果 |env_| 尚未设置（仍为空），它将附加到 SetNewLocalRef() 中的当前线程。
    this->Reset(env_, other.obj());
  }

  // Creates a new local reference to the Java object, unlike the constructor
  // with the same parameters that takes ownership of the existing reference.
  // TODO(torne): these should match as this is confusing.
  // 创建对 Java 对象的新本地引用，
  // 这与具有相同参数的构造函数不同，该构造函数获取现有引用的所有权。
  // TODO（torne）：这些应该匹配，因为这令人困惑。
  void Reset(JNIEnv* env, T obj) { env_ = this->SetNewLocalRef(env, obj); }

  // Releases the local reference to the caller. The caller *must* delete the
  // local reference when it is done with it. Note that calling a Java method
  // is *not* a transfer of ownership and Release() should not be used.
  // 释放对调用者的本地引用。
  // 调用者*必须*在完成后删除本地引用。
  // 注意，调用Java方法*不是*所有权转移，不应使用Release()。
  T Release() { return static_cast<T>(this->ReleaseInternal()); }

 private:
  // This class is only good for use on the thread it was created on so
  // it's safe to cache the non-threadsafe JNIEnv* inside this object.
  // 此类仅适用于创建它的线程，因此在此对象中缓存非线程安全 JNIEnv* 是安全的。
  JNIEnv* env_;

  // Prevent ScopedJavaLocalRef(JNIEnv*, T obj) from being used to take
  // ownership of a JavaParamRef's underlying object - parameters are not
  // allowed to be deleted and so should not be owned by ScopedJavaLocalRef.
  // 防止 ScopedJavaLocalRef(JNIEnv*, T obj) 
  // 被用于获取 JavaParamRef 的底层对象的所有权 - 不允许删除参数，
  // 因此不应由 ScopedJavaLocalRef 拥有。
  // TODO(torne): this can be removed once JavaParamRef no longer has an
  // implicit conversion back to T.
  // TODO(torne)：一旦 JavaParamRef 不再隐式转换回 T，就可以删除它。
  ScopedJavaLocalRef(JNIEnv* env, const JavaParamRef<T>& other);
};

// Holds a global reference to a Java object. The global reference is scoped
// to the lifetime of this object. This class does not hold onto any JNIEnv*
// passed to it, hence it is safe to use across threads (within the constraints
// imposed by the underlying Java object that it references).
// 持有对 Java 对象的全局引用。
// 全局引用的范围限定为该对象的生命周期。
// 此类不持有传递给它的任何 JNIEnv*，
// 因此跨线程使用是安全的（在底层施加的约束范围内）它引用的 Java 对象）。
template <typename T>
class ScopedJavaGlobalRef : public JavaRef<T> {
 public:
  ScopedJavaGlobalRef() {}
  explicit ScopedJavaGlobalRef(std::nullptr_t) {}

  ScopedJavaGlobalRef(const ScopedJavaGlobalRef<T>& other) { this->Reset(other); }

  ScopedJavaGlobalRef(ScopedJavaGlobalRef<T>&& other) { this->swap(other); }

  ScopedJavaGlobalRef(JNIEnv* env, T obj) { this->Reset(env, obj); }

  explicit ScopedJavaGlobalRef(const JavaRef<T>& other) { this->Reset(other); }

  ~ScopedJavaGlobalRef() { this->Reset(); }

  // Overloaded assignment operator defined for consistency with the implicit
  // copy constructor.
  // 重载赋值运算符定义为与隐式一致
  // 复制构造函数。
  void operator=(const ScopedJavaGlobalRef<T>& other) { this->Reset(other); }

  void operator=(ScopedJavaGlobalRef<T>&& other) { this->swap(other); }

  void Reset() { this->ResetGlobalRef(); }

  void Reset(const JavaRef<T>& other) { this->Reset(nullptr, other.obj()); }

  void Reset(JNIEnv* env, const JavaParamRef<T>& other) { this->Reset(env, other.obj()); }

  void Reset(JNIEnv* env, T obj) { this->SetNewGlobalRef(env, obj); }

  // Releases the global reference to the caller. The caller *must* delete the
  // global reference when it is done with it. Note that calling a Java method
  // is *not* a transfer of ownership and Release() should not be used.
  // 释放对调用者的全局引用。
  // 调用者*必须*在使用它时删除全局引用。
  // 注意，调用Java方法*不是*所有权转移，不应使用Release()。
  T Release() { return static_cast<T>(this->ReleaseInternal()); }
};

// Temporary type for parameters to Java functions, to allow incremental
// migration from bare jobject to JavaRef. Don't use outside JNI generator.
// Java 函数参数的临时类型，以允许从进工作对象到 JavaRef 的增量迁移。
// 不要在 JNI 生成器之外使用。
template <typename T>
class JavaRefOrBare {
 public:
  explicit JavaRefOrBare(std::nullptr_t) : obj_(nullptr) {}
  explicit JavaRefOrBare(const JavaRef<T>& ref) : obj_(ref.obj()) {}
  explicit JavaRefOrBare(T obj) : obj_(obj) {}
  T obj() const { return obj_; }

 private:
  T obj_;

  // DISALLOW_COPY_AND_ASSIGN(JavaRefOrBare);
};

}  // namespace android
}  // namespace base