Add JNI ownership types

wilhuff · a-maurice · commit 30f9b9e1bc42 · 2020-07-21T19:19:09.000-07:00
These generate local and global reference subtypes of a given JNI wrapper that
make it possible to automatically emit DeleteLocalRef and DeleteGlobalRef
calls in the course of regular usage.

PiperOrigin-RevId: 321175591
diff --git a/firestore/src/android/firestore_android.cc b/firestore/src/android/firestore_android.cc
@@ -38,6 +38,7 @@
 #include "firestore/src/android/wrapper.h"
 #include "firestore/src/android/write_batch_android.h"
 #include "firestore/src/include/firebase/firestore.h"
+#include "firestore/src/jni/jni.h"
 
 namespace firebase {
 namespace firestore {
@@ -144,6 +145,8 @@ FirestoreInternal::FirestoreInternal(App* app) {
 bool FirestoreInternal::Initialize(App* app) {
   MutexLock init_lock(init_mutex_);
   if (initialize_count_ == 0) {
+    jni::Initialize(app->java_vm());
+
     JNIEnv* env = app->GetJNIEnv();
     jobject activity = app->activity();
     if (!(firebase_firestore::CacheMethodIds(env, activity) &&
diff --git a/firestore/src/jni/jni.cc b/firestore/src/jni/jni.cc
@@ -0,0 +1,91 @@
+#include "firestore/src/jni/jni.h"
+
+#include <pthread.h>
+
+#include "app/src/assert.h"
+
+namespace firebase {
+namespace firestore {
+namespace jni {
+namespace {
+
+pthread_key_t jni_env_key;
+
+JavaVM* g_jvm = nullptr;
+
+/**
+ * Reinterprets `JNIEnv**` out parameters to `void**` on platforms where that's
+ * required.
+ */
+void** EnvOut(JNIEnv** env) { return reinterpret_cast<void**>(env); }
+
+JavaVM* GetGlobalJavaVM() {
+  // TODO(mcg): Use dlsym to call JNI_GetCreatedJavaVMs.
+  FIREBASE_ASSERT_MESSAGE(
+      g_jvm != nullptr,
+      "Global JVM is unset; missing call to jni::Initialize()");
+  return g_jvm;
+}
+
+/**
+ * A callback used by `pthread_key_create` to clean up thread-specific storage
+ * when a thread is destroyed.
+ */
+void DetachCurrentThread(void* env) {
+  JavaVM* jvm = g_jvm;
+  if (jvm == nullptr || env == nullptr) {
+    return;
+  }
+
+  jint result = jvm->DetachCurrentThread();
+  if (result != JNI_OK) {
+    LogWarning("DetachCurrentThread failed to detach (result=%d)", result);
+  }
+}
+
+}  // namespace
+
+void Initialize(JavaVM* jvm) {
+  g_jvm = jvm;
+
+  static pthread_once_t initialized = PTHREAD_ONCE_INIT;
+  pthread_once(&initialized, [] {
+    int err = pthread_key_create(&jni_env_key, DetachCurrentThread);
+    FIREBASE_ASSERT_MESSAGE(err == 0, "pthread_key_create failed (errno=%d)",
+                            err);
+  });
+}
+
+JNIEnv* GetEnv() {
+  JavaVM* jvm = GetGlobalJavaVM();
+
+  JNIEnv* env = nullptr;
+  jint result = jvm->GetEnv(EnvOut(&env), JNI_VERSION_1_6);
+  if (result == JNI_OK) {
+    // Called from a JVM-managed thread or from a thread that was previously
+    // attached. In either case, there's no work to be done.
+    return env;
+  }
+
+  // The only other documented error is JNI_EVERSION, but all supported Android
+  // implementations support JNI 1.6 so this shouldn't happen.
+  FIREBASE_ASSERT_MESSAGE(result == JNI_EDETACHED,
+                          "GetEnv failed with an unexpected error (result=%d)",
+                          result);
+
+  // If we've gotten here, the current thread is a native thread that has not
+  // been attached, so we need to attach it and set up a thread-local
+  // destructor.
+  result = jvm->AttachCurrentThread(&env, nullptr);
+  FIREBASE_ASSERT_MESSAGE(result == JNI_OK,
+                          "JNI AttachCurrentThread failed (result=%d)", result);
+
+  result = pthread_setspecific(jni_env_key, env);
+  FIREBASE_ASSERT_MESSAGE(result == 0,
+                          "JNI pthread_setspecific failed (errno=%d)", result);
+  return env;
+}
+
+}  // namespace jni
+}  // namespace firestore
+}  // namespace firebase
diff --git a/firestore/src/jni/jni.h b/firestore/src/jni/jni.h
@@ -0,0 +1,25 @@
+#ifndef FIREBASE_FIRESTORE_CLIENT_CPP_SRC_JNI_JNI_H_
+#define FIREBASE_FIRESTORE_CLIENT_CPP_SRC_JNI_JNI_H_
+
+#include <jni.h>
+
+namespace firebase {
+namespace firestore {
+namespace jni {
+
+/**
+ * Initializes the global `JavaVM` pointer. Should be called once per process
+ * execution.
+ */
+void Initialize(JavaVM* vm);
+
+/**
+ * Returns the `JNIEnv` pointer for the current thread.
+ */
+JNIEnv* GetEnv();
+
+}  // namespace jni
+}  // namespace firestore
+}  // namespace firebase
+
+#endif  // FIREBASE_FIRESTORE_CLIENT_CPP_SRC_JNI_JNI_H_
diff --git a/firestore/src/jni/jni_fwd.h b/firestore/src/jni/jni_fwd.h
@@ -0,0 +1,27 @@
+#ifndef FIREBASE_FIRESTORE_CLIENT_CPP_SRC_JNI_JNI_FWD_H_
+#define FIREBASE_FIRESTORE_CLIENT_CPP_SRC_JNI_JNI_FWD_H_
+
+namespace firebase {
+namespace firestore {
+namespace jni {
+
+/**
+ * Returns the `JNIEnv` pointer for the current thread.
+ */
+JNIEnv* GetEnv();
+
+// Reference types
+template <typename T>
+class Local;
+template <typename T>
+class Global;
+template <typename T>
+class NonOwning;
+
+class Object;
+
+}  // namespace jni
+}  // namespace firestore
+}  // namespace firebase
+
+#endif  // FIREBASE_FIRESTORE_CLIENT_CPP_SRC_JNI_JNI_FWD_H_
diff --git a/firestore/src/jni/ownership.h b/firestore/src/jni/ownership.h
@@ -0,0 +1,224 @@
+#ifndef FIREBASE_FIRESTORE_CLIENT_CPP_SRC_JNI_OWNERSHIP_H_
+#define FIREBASE_FIRESTORE_CLIENT_CPP_SRC_JNI_OWNERSHIP_H_
+
+#include <jni.h>
+
+#include <string>
+
+#include "firestore/src/jni/jni_fwd.h"
+#include "firestore/src/jni/traits.h"
+
+namespace firebase {
+namespace firestore {
+namespace jni {
+
+/**
+ * An RAII wrapper for a local JNI reference that automatically deletes the JNI
+ * local reference when it goes out of scope. Copies and moves are handled by
+ * creating additional references as required.
+ *
+ * @tparam T A JNI reference wrapper, usually a subclass of `Object`.
+ */
+template <typename T>
+class Local : public T {
+ public:
+  using jni_type = JniType<T>;
+
+  Local() = default;
+
+  /**
+   * Adopts a local reference that is the result of a JNI invocation.
+   */
+  Local(JNIEnv* env, jni_type value) : T(value), env_(env) {}
+
+  Local(const Local& other) = delete;
+  Local& operator=(const Local&) = delete;
+
+  Local(Local&& other) noexcept : T(other.release()), env_(other.env_) {}
+
+  Local& operator=(Local&& other) noexcept {
+    if (T::object_ != other.get()) {
+      EnsureEnv(other.env());
+      env_->DeleteLocalRef(T::object_);
+      T::object_ = other.release();
+    }
+    return *this;
+  }
+
+  Local(const Global<T>& other) {
+    EnsureEnv();
+    T::object_ = env_->NewLocalRef(other.get());
+  }
+
+  Local& operator=(const Global<T>& other) {
+    EnsureEnv();
+    env_->DeleteLocalRef(T::object_);
+    T::object_ = env_->NewLocalRef(other.get());
+    return *this;
+  }
+
+  Local(Global<T>&& other) noexcept {
+    EnsureEnv();
+    T::object_ = env_->NewLocalRef(other.get());
+    env_->DeleteGlobalRef(other.release());
+  }
+
+  Local& operator=(Global<T>&& other) noexcept {
+    EnsureEnv();
+    env_->DeleteLocalRef(T::object_);
+    T::object_ = env_->NewLocalRef(other.get());
+    env_->DeleteGlobalRef(other.release());
+    return *this;
+  }
+
+  ~Local() {
+    if (env_ && T::object_) {
+      env_->DeleteLocalRef(T::object_);
+    }
+  }
+
+  jni_type get() const override { return static_cast<jni_type>(T::object_); }
+
+  jni_type release() {
+    jobject result = T::object_;
+    T::object_ = nullptr;
+    return static_cast<jni_type>(result);
+  }
+
+  JNIEnv* env() const { return env_; }
+
+ private:
+  void EnsureEnv(JNIEnv* other = nullptr) {
+    if (env_ == nullptr) {
+      if (other != nullptr) {
+        env_ = other;
+      } else {
+        env_ = GetEnv();
+      }
+    }
+  }
+
+  JNIEnv* env_ = nullptr;
+};
+
+/**
+ * Global references are almost always created by promoting local references.
+ * Aside from `NewGlobalRef`, there are no JNI APIs that return global
+ * references. You can construct a `Global` wrapper with `AdoptExisting::kYes`
+ * in the rare case that you're interoperating with other APIs that produce
+ * global JNI references.
+ */
+enum class AdoptExisting { kYes };
+
+/**
+ * An RAII wrapper for a global JNI reference, that automatically deletes the
+ * JNI global reference when it goes out of scope. Copies and moves are handled
+ * by creating additional references as required.
+ *
+ * @tparam T A JNI reference wrapper, usually a subclass of `Object`.
+ */
+template <typename T>
+class Global : public T {
+ public:
+  using jni_type = JniType<T>;
+
+  Global() = default;
+
+  Global(jni_type object, AdoptExisting) : T(object) {}
+
+  Global(const Local<T>& other) {
+    JNIEnv* env = EnsureEnv(other.env());
+    T::object_ = env->NewGlobalRef(other.get());
+  }
+
+  Global& operator=(const Local<T>& other) {
+    JNIEnv* env = EnsureEnv(other.env());
+    env->DeleteGlobalRef(T::object_);
+    T::object_ = env->NewGlobalRef(other.get());
+    return *this;
+  }
+
+  Global(const T& other) {
+    JNIEnv* env = GetEnv();
+    T::object_ = env->NewGlobalRef(other.get());
+  }
+
+  Global& operator=(const T& other) {
+    if (T::object_ != other.get()) {
+      JNIEnv* env = GetEnv();
+      env->DeleteGlobalRef(T::object_);
+      T::object_ = env->NewGlobalRef(other.get());
+    }
+    return *this;
+  }
+
+  // Explicitly declare a copy constructor and copy assignment operator because
+  // there's an explicitly declared move constructor for this type.
+  //
+  // Without this, the implicitly-defined copy constructor would be deleted, and
+  // during overload resolution the deleted copy constructor would take priority
+  // over the looser match above that takes `const T&`.
+  Global(const Global& other) : Global(static_cast<const T&>(other)) {}
+
+  Global& operator=(const Global& other) {
+    *this = static_cast<const T&>(other);
+    return *this;
+  }
+
+  Global(Global&& other) noexcept : T(other.release()) {}
+
+  Global& operator=(Global&& other) noexcept {
+    if (T::object_ != other.get()) {
+      if (T::object_) {
+        JNIEnv* env = GetEnv();
+        env->DeleteGlobalRef(T::object_);
+      }
+      T::object_ = other.release();
+    }
+    return *this;
+  }
+
+  Global(Local<T>&& other) noexcept {
+    JNIEnv* env = EnsureEnv(other.env());
+    T::object_ = env->NewGlobalRef(other.get());
+    env->DeleteLocalRef(other.release());
+  }
+
+  Global& operator=(Local<T>&& other) noexcept {
+    JNIEnv* env = EnsureEnv(other.env());
+    env->DeleteGlobalRef(T::object_);
+    T::object_ = env->NewGlobalRef(other.get());
+    env->DeleteLocalRef(other.release());
+    return *this;
+  }
+
+  ~Global() {
+    if (T::object_) {
+      JNIEnv* env = GetEnv();
+      env->DeleteGlobalRef(T::object_);
+    }
+  }
+
+  jni_type get() const override { return static_cast<jni_type>(T::object_); }
+
+  jni_type release() {
+    jobject result = T::object_;
+    T::object_ = nullptr;
+    return static_cast<jni_type>(result);
+  }
+
+ private:
+  JNIEnv* EnsureEnv(JNIEnv* other = nullptr) {
+    if (other != nullptr) {
+      return other;
+    } else {
+      return GetEnv();
+    }
+  }
+};
+
+}  // namespace jni
+}  // namespace firestore
+}  // namespace firebase
+
+#endif  // FIREBASE_FIRESTORE_CLIENT_CPP_SRC_JNI_OWNERSHIP_H_
diff --git a/firestore/src/jni/traits.h b/firestore/src/jni/traits.h
diff --git a/firestore/src/tests/jni/ownership_test.cc b/firestore/src/tests/jni/ownership_test.cc
