capi: add HarfBuzz C++ ownership helpers for core objects

.github/workflows/main.yml

@@ -61,6 +61,24 @@ jobs:
           -o /tmp/hr-subset
         /tmp/hr-subset harfrust/tests/fonts/rb_custom/PT_Sans-Caption-Web-Regular.ttf
 
+    - name: HarfBuzz C++ ownership helpers
+      run: |
+        for standard in c++11 c++17; do
+          for order in CORE SUBSET_FIRST SUBSET_LAST; do
+            library_directory=target/debug
+            if [ "$order" = CORE ]; then
+              library_directory=target/capi-default/debug
+            fi
+            c++ -std="$standard" -pedantic-errors -Wall -Wextra -Werror \
+              -D"HR_TEST_$order" \
+              -Iharfrust_capi/include \
+              harfrust_capi/tests/cplusplus.cc -L"$library_directory" \
+              -lharfrust_c -Wl,-rpath,"$PWD/$library_directory" \
+              -o /tmp/hr-cplusplus
+            /tmp/hr-cplusplus harfrust/tests/fonts/rb_custom/PT_Sans-Caption-Web-Regular.ttf
+          done
+        done
+
     - name: Rustfmt
       run: cargo fmt --all -- --check
 

harfrust_capi/README.md

@@ -256,3 +256,14 @@ Enable the optional `subset` feature for Skera-backed subsetting in the same
 C library, using the existing face, blob, and set handles. Include `hr-subset.h`
 for the native API or `hr-hb-subset.h` for HarfBuzz spellings. See
 [SUBSETTING.md](SUBSETTING.md) for building, supported flags, and validation.
+
+## HarfBuzz C++ helpers
+
+Include `hr-hb-cplusplus.hh` in place of HarfBuzz's `hb-cplusplus.hh` for
+the C++11 `hb::shared_ptr<T>` and `hb::unique_ptr<T>` ownership helpers,
+their traits, and hash specializations. They adopt an existing reference;
+copying a shared pointer acquires another reference. Supported core types
+are blobs, buffers, faces, fonts, font functions, maps, sets, and shape plans.
+
+Subset input and plan ownership helpers are provided separately with the
+extended subset APIs.

harfrust_capi/include/hr-hb-cplusplus.hh

@@ -0,0 +1,217 @@
+/*
+ * Copyright © 2022 Behdad Esfahbod
+ *
+ *  This is part of HarfBuzz, a text shaping library.
+ *
+ * Permission is hereby granted, without written agreement and without
+ * license or royalty fees, to use, copy, modify, and distribute this
+ * software and its documentation for any purpose, provided that the
+ * above copyright notice and the following two paragraphs appear in
+ * all copies of this software.
+ *
+ * IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE TO ANY PARTY FOR
+ * DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
+ * ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN
+ * IF THE COPYRIGHT HOLDER HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
+ * DAMAGE.
+ *
+ * THE COPYRIGHT HOLDER SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING,
+ * BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+ * FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
+ * ON AN "AS IS" BASIS, AND THE COPYRIGHT HOLDER HAS NO OBLIGATION TO
+ * PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
+ */
+
+#ifndef HARFRUST_HB_CPLUSPLUS_HH
+#define HARFRUST_HB_CPLUSPLUS_HH
+
+/* Adapted from HarfBuzz's hb-cplusplus.hh. Ownership helpers retain the
+ * hb namespace; user-data adapters accommodate HarfRust's const signatures.
+ * Only objects with the required HarfRust lifetime API are specialized.
+ */
+#include "hr-hb.h"
+
+#ifdef __cplusplus
+
+#include <functional>
+#include <utility>
+#include <type_traits>
+
+#if 0
+#if !(__cplusplus >= 201103L)
+#error "HarfBuzz C++ helpers require C++11"
+#endif
+#endif
+
+namespace hb {
+
+
+template <typename T>
+struct vtable;
+
+template <typename T>
+struct shared_ptr
+{
+  using element_type = T;
+
+  using v = vtable<T>;
+
+  explicit shared_ptr (T *p = nullptr) : p (p) {}
+  shared_ptr (const shared_ptr &o) : p (v::reference (o.p)) {}
+  shared_ptr (shared_ptr &&o)  noexcept : p (o.p) { o.p = nullptr; }
+  shared_ptr& operator = (const shared_ptr &o) { if (p != o.p) { destroy (); p = o.p; reference (); } return *this; }
+  shared_ptr& operator = (shared_ptr &&o)  noexcept { v::destroy (p); p = o.p; o.p = nullptr; return *this; }
+  ~shared_ptr () { v::destroy (p); p = nullptr; }
+
+  T* get() const { return p; }
+
+  void swap (shared_ptr &o)  noexcept { std::swap (p, o.p); }
+  friend void swap (shared_ptr &a, shared_ptr &b)  noexcept { std::swap (a.p, b.p); }
+
+  operator T * () const { return p; }
+  T& operator * () const { return *get (); }
+  T* operator -> () const { return get (); }
+  operator bool () const { return p; }
+  bool operator == (const shared_ptr &o) const { return p == o.p; }
+  bool operator != (const shared_ptr &o) const { return p != o.p; }
+
+  static T* get_empty() { return v::get_empty (); }
+  T* reference() { return v::reference (p); }
+  void destroy() { v::destroy (p); }
+  void set_user_data (hb_user_data_key_t *key,
+		      void *value,
+		      hb_destroy_func_t destroy,
+		      hb_bool_t replace) { v::set_user_data (p, key, value, destroy, replace); }
+  void * get_user_data (hb_user_data_key_t *key) { return v::get_user_data (p, key); }
+
+  private:
+  T *p;
+};
+
+template<typename T> struct is_shared_ptr : std::false_type {};
+template<typename T> struct is_shared_ptr<shared_ptr<T>> : std::true_type {};
+
+template <typename T>
+struct unique_ptr
+{
+  using element_type = T;
+
+  using v = vtable<T>;
+
+  explicit unique_ptr (T *p = nullptr) : p (p) {}
+  unique_ptr (const unique_ptr &o) = delete;
+  unique_ptr (unique_ptr &&o)  noexcept : p (o.p) { o.p = nullptr; }
+  unique_ptr& operator = (const unique_ptr &o) = delete;
+  unique_ptr& operator = (unique_ptr &&o)  noexcept { v::destroy (p); p = o.p; o.p = nullptr; return *this; }
+  ~unique_ptr () { v::destroy (p); p = nullptr; }
+
+  T* get() const { return p; }
+  T* release () { T* v = p; p = nullptr; return v; }
+
+  void swap (unique_ptr &o)  noexcept { std::swap (p, o.p); }
+  friend void swap (unique_ptr &a, unique_ptr &b)  noexcept { std::swap (a.p, b.p); }
+
+  operator T * () const { return p; }
+  T& operator * () const { return *get (); }
+  T* operator -> () const { return get (); }
+  operator bool () { return p; }
+
+  private:
+  T *p;
+};
+
+template<typename T> struct is_unique_ptr : std::false_type {};
+template<typename T> struct is_unique_ptr<unique_ptr<T>> : std::true_type {};
+
+template <typename T,
+	  T * (*_get_empty) (void),
+	  T * (*_reference) (T *),
+	  void (*_destroy) (T *),
+	  hb_bool_t (*_set_user_data) (T *,
+				       hb_user_data_key_t *,
+				       void *,
+				       hb_destroy_func_t,
+				       hb_bool_t),
+	  void * (*_get_user_data) (const T *,
+				    hb_user_data_key_t *)>
+struct vtable_t
+{
+  static constexpr auto get_empty = _get_empty;
+  static constexpr auto reference = _reference;
+  static constexpr auto destroy = _destroy;
+  static constexpr auto set_user_data = _set_user_data;
+  static constexpr auto get_user_data = _get_user_data;
+};
+
+/* HarfRust's key parameters are const, while several core user-data getters
+ * take a mutable object. Preserve the HarfBuzz vtable_t signature using these
+ * forwarding functions; they never modify the key or object themselves. */
+template <typename T>
+struct vtable_user_data;
+
+#define HB_DEFINE_VTABLE(name, empty) \
+        template<> \
+        struct vtable_user_data<hb_##name##_t> \
+        { \
+          static hb_bool_t set (hb_##name##_t *p, hb_user_data_key_t *key, \
+                               void *value, hb_destroy_func_t destroy, \
+                               hb_bool_t replace) \
+          { return hb_##name##_set_user_data (p, key, value, destroy, replace); } \
+          static void * get (const hb_##name##_t *p, hb_user_data_key_t *key) \
+          { return hb_##name##_get_user_data (const_cast<hb_##name##_t *> (p), key); } \
+        }; \
+        template<> \
+        struct vtable<hb_##name##_t> \
+             : vtable_t<hb_##name##_t, \
+                        empty, \
+                        &hb_##name##_reference, \
+                        &hb_##name##_destroy, \
+                        &vtable_user_data<hb_##name##_t>::set, \
+                        &vtable_user_data<hb_##name##_t>::get> {}
+
+HB_DEFINE_VTABLE (buffer, &hb_buffer_get_empty);
+HB_DEFINE_VTABLE (blob, &hb_blob_get_empty);
+HB_DEFINE_VTABLE (face, &hb_face_get_empty);
+HB_DEFINE_VTABLE (font, &hb_font_get_empty);
+HB_DEFINE_VTABLE (font_funcs, &hb_font_funcs_get_empty);
+HB_DEFINE_VTABLE (map, &hb_map_get_empty);
+HB_DEFINE_VTABLE (set, &hb_set_get_empty);
+HB_DEFINE_VTABLE (shape_plan, &hb_shape_plan_get_empty);
+
+
+#undef HB_DEFINE_VTABLE
+
+} // namespace hb
+
+/* Workaround for GCC < 7, see:
+ * https://gcc.gnu.org/bugzilla/show_bug.cgi?id=56480
+ * https://stackoverflow.com/a/25594741 */
+namespace std {
+
+
+template<typename T>
+struct hash<hb::shared_ptr<T>>
+{
+    std::size_t operator()(const hb::shared_ptr<T>& v) const noexcept
+    {
+        std::size_t h = std::hash<decltype (v.get ())>{}(v.get ());
+        return h;
+    }
+};
+
+template<typename T>
+struct hash<hb::unique_ptr<T>>
+{
+    std::size_t operator()(const hb::unique_ptr<T>& v) const noexcept
+    {
+        std::size_t h = std::hash<decltype (v.get ())>{}(v.get ());
+        return h;
+    }
+};
+
+
+} // namespace std
+
+#endif /* __cplusplus */
+
+#endif /* HARFRUST_HB_CPLUSPLUS_HH */

harfrust_capi/tests/cplusplus.cc

@@ -0,0 +1,127 @@
+// Exercise the HarfBuzz C++ ownership helpers against the actual C ABI.
+#ifdef HR_TEST_SUBSET_FIRST
+#include "hr-hb-subset.h"
+#endif
+#include "hr-hb-cplusplus.hh"
+#ifdef HR_TEST_SUBSET_LAST
+#include "hr-hb-subset.h"
+#endif
+// Repeated includes and both subset include orders must remain valid.
+#include "hr-hb-cplusplus.hh"
+#if defined(HR_TEST_SUBSET_FIRST) || defined(HR_TEST_SUBSET_LAST)
+#include "hr-hb-subset.h"
+#endif
+
+#include <cassert>
+#include <unordered_set>
+
+static hb_user_data_key_t key;
+static unsigned destroyed;
+
+static void count_destroy(void *data)
+{
+  assert(data == &destroyed);
+  ++destroyed;
+}
+
+template <typename T>
+static void check_ownership(T *object)
+{
+  const unsigned before = destroyed;
+  assert(object);
+  {
+    hb::shared_ptr<T> owner(object);
+    owner.set_user_data(&key, &destroyed, count_destroy, true);
+    assert(owner.get_user_data(&key) == &destroyed);
+    {
+      hb::shared_ptr<T> copy(owner);
+      hb::shared_ptr<T> assigned;
+      assigned = copy;
+      hb::shared_ptr<T> moved(std::move(copy));
+      assert(!copy);
+      assert(moved == owner);
+      copy = std::move(assigned);
+      assert(!assigned);
+      assert(copy == owner);
+      std::unordered_set<hb::shared_ptr<T>> set;
+      set.insert(owner);
+      set.insert(moved);
+      assert(set.size() == 1);
+      assert(destroyed == before);
+    }
+    assert(destroyed == before);
+    hb::unique_ptr<T> unique(owner.reference());
+    hb::unique_ptr<T> moved(std::move(unique));
+    assert(!unique);
+    unique = std::move(moved);
+    assert(!moved);
+    hb::unique_ptr<T> released(unique.release());
+    assert(!unique);
+    hb::unique_ptr<T> empty;
+    swap(released, empty);
+    assert(!released);
+    assert(empty.get() == owner.get());
+    assert(std::hash<hb::unique_ptr<T>>{}(empty) ==
+           std::hash<T *>{}(empty.get()));
+  }
+  assert(destroyed == before + 1);
+}
+
+template <typename T>
+static void check_empty()
+{
+  hb::shared_ptr<T> empty(hb::shared_ptr<T>::get_empty());
+  assert(empty);
+  hb::shared_ptr<T> copy(empty);
+  assert(copy == empty);
+}
+
+int main(int argc, char **argv)
+{
+  static_assert(hb::is_shared_ptr<hb::shared_ptr<hb_blob_t>>::value, "shared trait");
+  static_assert(hb::is_unique_ptr<hb::unique_ptr<hb_blob_t>>::value, "unique trait");
+  static_assert(!hb::is_shared_ptr<hb_blob_t *>::value, "raw pointer trait");
+  static_assert(!std::is_copy_constructible<hb::unique_ptr<hb_blob_t>>::value,
+                "unique ownership");
+  static_assert(std::is_nothrow_move_constructible<hb::shared_ptr<hb_blob_t>>::value,
+                "noexcept move");
+
+  check_empty<hb_blob_t>();
+  check_empty<hb_buffer_t>();
+  check_empty<hb_face_t>();
+  check_empty<hb_font_t>();
+  check_empty<hb_font_funcs_t>();
+  check_empty<hb_map_t>();
+  check_empty<hb_set_t>();
+  check_empty<hb_shape_plan_t>();
+
+  check_ownership(hb_blob_create("abc", 3, HB_MEMORY_MODE_DUPLICATE, nullptr, nullptr));
+  check_ownership(hb_buffer_create());
+  check_ownership(hb_font_funcs_create());
+  check_ownership(hb_map_create());
+  check_ownership(hb_set_create());
+
+  assert(argc == 2);
+  hb::shared_ptr<hb_blob_t> blob(hb_blob_create_from_file_or_fail(argv[1]));
+  assert(blob && hb_blob_get_length(blob));
+  hb::shared_ptr<hb_face_t> face(hb_face_create(blob, 0));
+  assert(hb_face_get_glyph_count(face));
+  check_ownership(hb_face_create(blob, 0));
+  check_ownership(hb_font_create(face));
+
+  hb_segment_properties_t props = HB_SEGMENT_PROPERTIES_DEFAULT;
+  props.direction = HB_DIRECTION_LTR;
+  props.script = HB_SCRIPT_LATIN;
+  check_ownership(hb_shape_plan_create(face, &props, nullptr, 0, nullptr));
+
+#if defined(HR_TEST_SUBSET_FIRST) || defined(HR_TEST_SUBSET_LAST)
+  hb_subset_input_t *input = hb_subset_input_create_or_fail();
+  assert(input);
+  hb_set_add(hb_subset_input_unicode_set(input), 'A');
+  hb::shared_ptr<hb_face_t> result(hb_subset_or_fail(face, input));
+  hb_subset_input_destroy(input);
+  assert(result && hb_face_get_glyph_count(result));
+  hb::unique_ptr<hb_blob_t> subset_blob(hb_face_reference_blob(result));
+  assert(subset_blob && hb_blob_get_length(subset_blob));
+#endif
+}