Introduce vecmem::metal, main branch (2024.10.27.)

.clang-format

@@ -1,7 +1,6 @@
 ---
 BasedOnStyle: Google
 IndentWidth: 4
-Language: Cpp
 AllowShortBlocksOnASingleLine: false
 AllowShortCaseLabelsOnASingleLine: false
 AllowShortFunctionsOnASingleLine: Inline

.github/check_format.sh

@@ -20,7 +20,7 @@ _binary=${CLANG_FORMAT_BINARY:-clang-format}
 $_binary --version
 
 cd $1
-find . \( -iname '*.cpp' -or -iname '*.hpp' -or -iname '*.ipp' -or -iname '*.cu' -or -iname '*.cuh' -or -iname '*.hip' -or -iname '*.sycl' \) \
+find . \( -iname '*.cpp' -or -iname '*.hpp' -or -iname '*.ipp' -or -iname '*.cu' -or -iname '*.cuh' -or -iname '*.hip' -or -iname '*.sycl' -or -iname '*.h' -or -iname '*.mm' -or -iname '*.metal' \) \
        -and -not -path "./*build*/*" \
        -and -not -path "./thirdparty/*" \
   | xargs $_binary -i -style=file
@@ -32,9 +32,9 @@ if ! [ -z $CI ] || ! [ -z $GITHUB_ACTIONS ]; then
     cp --parents $f changed
   done
 fi
-    
+
 echo "clang-format done"
-    
+
 set +e
 git diff --exit-code --stat
 result=$?

CMakeLists.txt

@@ -49,6 +49,9 @@ endif()
 if( VECMEM_BUILD_SYCL_LIBRARY )
    add_subdirectory( sycl )
 endif()
+if( VECMEM_BUILD_METAL_LIBRARY )
+   add_subdirectory( metal )
+endif()
 
 # Set up the test(s).
 if( BUILD_TESTING AND VECMEM_BUILD_TESTING )

cmake/vecmem-options.cmake

@@ -40,6 +40,9 @@ vecmem_lib_option( HIP "Build the vecmem::hip library" )
 # Flag specifying whether SYCL support should be built.
 vecmem_lib_option( SYCL "Build the vecmem::sycl library" )
 
+# Flag specifying whether Metal support should be built.
+option( VECMEM_BUILD_METAL_LIBRARY "Build the vecmem::metal library" ${APPLE} )
+
 # Use folders for organizing targets in IDEs.
 set_property( GLOBAL PROPERTY USE_FOLDERS ON )
 

metal/CMakeLists.txt

@@ -0,0 +1,34 @@
+# VecMem project, part of the ACTS project (R&D line)
+#
+# (c) 2024 CERN for the benefit of the ACTS project
+#
+# Mozilla Public License Version 2.0
+
+# OBJCXX support requires CMake 3.16.
+cmake_minimum_required( VERSION 3.16 )
+
+# Enable the OBJCXX language.
+enable_language( OBJCXX )
+
+# Set up the build of the VecMem Metal library.
+vecmem_add_library( vecmem_metal metal
+   # Memory management.
+   "include/vecmem/memory/metal/shared_memory_resource.hpp"
+   "src/memory/shared_memory_resource.mm"
+   # Utilities.
+   "include/vecmem/utils/metal/device_wrapper.hpp"
+   "src/utils/device_wrapper.mm"
+   "src/utils/opaque_device.h"
+   "src/utils/get_device.h"
+   "src/utils/get_device.mm" )
+target_link_libraries( vecmem_metal PUBLIC vecmem::core )
+
+# Hide the library's symbols by default.
+set_target_properties( vecmem_metal PROPERTIES
+   OBJCXX_VISIBILITY_PRESET "hidden" )
+
+# Link against the necessary macOS framework(s).
+find_library( VECMEM_FOUNDATION_FRAMEWORK "Foundation" REQUIRED )
+find_library( VECMEM_METAL_FRAMEWORK "Metal" REQUIRED )
+target_link_libraries( vecmem_metal
+   PRIVATE ${VECMEM_FOUNDATION_FRAMEWORK} ${VECMEM_METAL_FRAMEWORK} )

metal/include/vecmem/memory/metal/shared_memory_resource.hpp

@@ -0,0 +1,67 @@
+/*
+ * VecMem project, part of the ACTS project (R&D line)
+ *
+ * (c) 2024 CERN for the benefit of the ACTS project
+ *
+ * Mozilla Public License Version 2.0
+ */
+
+#pragma once
+
+// Local include(s).
+#include "vecmem/memory/memory_resource.hpp"
+#include "vecmem/utils/metal/device_wrapper.hpp"
+#include "vecmem/vecmem_metal_export.hpp"
+
+// System include(s).
+#include <memory>
+
+/// @brief Namespace holding types that work with Metal
+namespace vecmem::metal {
+
+// Forward declaration(s).
+namespace details {
+struct shared_memory_resource_data;
+}
+
+/**
+ * @brief Memory resource that exposes Metal shared memory allocations.
+ *
+ * This is an allocator-type memory resource (that is to say, it only
+ * allocates, it does not try to manage memory in a smart way) that works
+ * for Metal shared memory. Each instance is bound to a specific device.
+ */
+class shared_memory_resource final : public memory_resource {
+
+public:
+    /// Default constructor
+    VECMEM_METAL_EXPORT
+    shared_memory_resource(const device_wrapper& device = {});
+    /// Destructor
+    VECMEM_METAL_EXPORT
+    ~shared_memory_resource();
+
+private:
+    /// @name Function(s) implementing @c vecmem::memory_resource
+    /// @{
+
+    /// Allocate memory on the selected device
+    VECMEM_METAL_EXPORT
+    virtual void* do_allocate(std::size_t, std::size_t) override final;
+    /// De-allocate a previously allocated memory block on the selected device
+    VECMEM_METAL_EXPORT
+    virtual void do_deallocate(void* p, std::size_t,
+                               std::size_t) override final;
+    /// Compares @c *this for equality with @c other
+    VECMEM_METAL_EXPORT
+    virtual bool do_is_equal(
+        const memory_resource& other) const noexcept override final;
+
+    /// @}
+
+    /// Internal state of the memory resource
+    std::unique_ptr<details::shared_memory_resource_data> m_data;
+
+};  // class shared_memory_resource
+
+}  // namespace vecmem::metal

metal/include/vecmem/utils/metal/device_wrapper.hpp

@@ -0,0 +1,74 @@
+/* VecMem project, part of the ACTS project (R&D line)
+ *
+ * (c) 2024 CERN for the benefit of the ACTS project
+ *
+ * Mozilla Public License Version 2.0
+ */
+#pragma once
+
+// Local include(s).
+#include "vecmem/vecmem_metal_export.hpp"
+
+// System include(s).
+#include <memory>
+
+namespace vecmem::metal {
+
+// Forward declaration(s).
+namespace details {
+class opaque_device;
+}
+
+/// Wrapper class for @c MTLDevice
+///
+/// It is necessary for passing around Metal device objects in
+/// non-Objective-C(++) code.
+///
+class device_wrapper {
+
+public:
+    /// Construct a default device
+    VECMEM_METAL_EXPORT
+    device_wrapper();
+    /// Wrap an existing @c MTLDevice object
+    ///
+    /// Without taking ownership of it!
+    ///
+    VECMEM_METAL_EXPORT
+    device_wrapper(void* device);
+
+    /// Copy constructor
+    VECMEM_METAL_EXPORT
+    device_wrapper(const device_wrapper& parent);
+    /// Move constructor
+    VECMEM_METAL_EXPORT
+    device_wrapper(device_wrapper&& parent);
+
+    /// Destructor
+    VECMEM_METAL_EXPORT
+    ~device_wrapper();
+
+    /// Copy assignment
+    VECMEM_METAL_EXPORT
+    device_wrapper& operator=(const device_wrapper& rhs);
+    /// Move assignment
+    VECMEM_METAL_EXPORT
+    device_wrapper& operator=(device_wrapper&& rhs);
+
+    /// Access a typeless pointer to the managed @c MTLDevice object
+    VECMEM_METAL_EXPORT
+    void* device();
+    /// Access a typeless pointer to the managed @c MTLDevice object
+    VECMEM_METAL_EXPORT
+    const void* device() const;
+
+private:
+    /// Bare pointer to the wrapped @c MTLDevice object
+    void* m_device;
+
+    /// Smart pointer to the managed @c MTLDevice object
+    std::unique_ptr<details::opaque_device> m_managedDevice;
+
+};  // class device_wrapper
+
+}  // namespace vecmem::metal

metal/src/memory/shared_memory_resource.mm

@@ -0,0 +1,80 @@
+/*
+ * VecMem project, part of the ACTS project (R&D line)
+ *
+ * (c) 2024 CERN for the benefit of the ACTS project
+ *
+ * Mozilla Public License Version 2.0
+ */
+
+// Local include(s).
+#include "vecmem/memory/metal/shared_memory_resource.hpp"
+#include "../utils/get_device.h"
+
+// System import(s).
+#import <Metal/Metal.h>
+
+// System include(s).
+#include <cassert>
+#include <map>
+#include <stdexcept>
+
+namespace vecmem::metal {
+namespace details {
+
+/// Internal state for the shared memory resource.
+struct shared_memory_resource_data {
+    /// The Metal device.
+    device_wrapper m_device;
+    /// Memory buffers allocated on the device.
+    std::map<void*, id<MTLBuffer> > m_buffers;
+};
+
+}  // namespace details
+
+shared_memory_resource::shared_memory_resource(const device_wrapper& device)
+    : m_data(std::make_unique<details::shared_memory_resource_data>()) {
+
+    // Save the device wrapper object.
+    m_data->m_device = device;
+}
+
+shared_memory_resource::~shared_memory_resource() {}
+
+void* shared_memory_resource::do_allocate(std::size_t bytes, std::size_t) {
+
+    // Create a new shared buffer.
+    id<MTLBuffer> buffer = [details::get_device(m_data->m_device)
+        newBufferWithLength:bytes
+                    options:MTLResourceStorageModeShared];
+    // If the buffer was created successfully, store it in the map, and return
+    // its pointer.
+    if (buffer != nil) {
+        void* ptr = buffer.contents;
+        assert(m_data);
+        m_data->m_buffers[ptr] = buffer;
+        return ptr;
+    }
+
+    // If the buffer could not be created, throw an exception.
+    throw std::bad_alloc();
+}
+
+void shared_memory_resource::do_deallocate(void* p, std::size_t, std::size_t) {
+
+    // Find the buffer, and release it. It's undefined behaviour to deallocate
+    // a buffer that was not allocated by this memory resource. So we might as
+    // well crash when that happens.
+    assert(m_data);
+    auto it = m_data->m_buffers.find(p);
+    assert(it != m_data->m_buffers.end());
+    m_data->m_buffers.erase(it);
+}
+
+bool shared_memory_resource::do_is_equal(
+    const memory_resource& other) const noexcept {
+
+    // The memory resource manages buffers itself. It is only equal to itself.
+    return this == &other;
+}
+
+}  // namespace vecmem::metal