Device: added makeShared(), returns auto-unmaking device shared_ptrs

* Bumped ABI version to 0.8-4

include/SoapySDR/Device.hpp

@@ -6,7 +6,7 @@
 /// \copyright
 /// Copyright (c) 2014-2019 Josh Blum
 /// Copyright (c) 2016-2016 Bastille Networks
-///                    2021 Nicholas Corgan
+///               2021-2023 Nicholas Corgan
 /// SPDX-License-Identifier: BSL-1.0
 ///
 
@@ -19,6 +19,7 @@
 #include <string>
 #include <complex>
 #include <cstddef> //size_t
+#include <memory>
 
 namespace SoapySDR
 {
@@ -33,6 +34,8 @@ class SOAPY_SDR_API Device
 {
 public:
 
+    using SPtr = std::shared_ptr<Device>;
+
     //! virtual destructor for inheritance
     virtual ~Device(void);
 
@@ -73,6 +76,30 @@ class SOAPY_SDR_API Device
      */
     static Device *make(const std::string &args);
 
+    /*!
+     * Make a new Device object given device construction args.
+     * The device pointer will be stored in a table so subsequent calls
+     * with the same arguments will produce the same device.
+     * On destruction of the shared_ptr, unmake() will automatically be
+     * called.
+     *
+     * \param args a markup string of key/value arguments
+     * \return a shared pointer to a new Device object
+     */
+    static SPtr makeShared(const Kwargs &args = Kwargs());
+
+    /*!
+     * Make a new Device object given device construction args.
+     * The device pointer will be stored in a table so subsequent calls
+     * with the same arguments will produce the same device.
+     * On destruction of the shared_ptr, unmake() will automatically be
+     * called.
+     *
+     * \param args a markup string of key/value arguments
+     * \return a shared pointer to a new Device object
+     */
+    static SPtr makeShared(const std::string &args);
+
     /*!
      * Unmake or release a device object handle.
      *
@@ -104,6 +131,30 @@ class SOAPY_SDR_API Device
      */
     static std::vector<Device *> make(const std::vector<std::string> &argsList);
 
+    /*!
+     * Create a list of devices from a list of construction arguments.
+     * This is a convenience call to parallelize device construction,
+     * and is fundamentally a parallel for loop of makeShared(Kwargs).
+     * On destruction of the vector, unmake() will automatically be
+     * called for each device.
+     *
+     * \param argsList a list of device arguments per each device
+     * \return a list of shared device pointers per each specified argument
+     */
+    static std::vector<SPtr> makeShared(const KwargsList &argsList);
+
+    /*!
+     * Create a list of devices from a list of construction arguments.
+     * This is a convenience call to parallelize device construction,
+     * and is fundamentally a parallel for loop of makeShared(Kwargs).
+     * On destruction of the vector, unmake() will automatically be
+     * called for each device.
+     *
+     * \param argsList a list of device arguments per each device
+     * \return a list of shared device pointers per each specified argument
+     */
+    static std::vector<SPtr> makeShared(const std::vector<std::string> &argsList);
+
     /*!
      * Unmake or release a list of device handles.
      * This is a convenience call to parallelize device destruction,

include/SoapySDR/Version.h

@@ -36,7 +36,7 @@
  * And <i>extra</i> is empty for releases but set on development branches.
  * The ABI should remain constant across patch releases of the library.
  */
-#define SOAPY_SDR_ABI_VERSION "0.8-3"
+#define SOAPY_SDR_ABI_VERSION "0.8-4"
 
 /*!
  * Compatibility define for GPIO access API with masks
@@ -173,6 +173,10 @@
  */
 #define SOAPY_SDR_API_HAS_GET_LOG_LEVEL
 
+/*!
+ * Compatibility define for shared_ptr factory functions
+ */
+
 #ifdef __cplusplus
 extern "C" {
 #endif

lib/Factory.cpp

@@ -36,6 +36,16 @@ static DeviceCounts &getDeviceCounts(void)
     return table;
 }
 
+using Deleter = void(*)(SoapySDR::Device *);
+
+static inline Deleter getDeviceDeleter(void)
+{
+    return [](SoapySDR::Device *device)
+    {
+        SoapySDR::Device::unmake(device);
+    };
+}
+
 void automaticLoadModules(void);
 
 SoapySDR::KwargsList SoapySDR::Device::enumerate(const Kwargs &args)
@@ -204,6 +214,29 @@ SoapySDR::Device *SoapySDR::Device::make(const std::string &args)
     return make(KwargsFromString(args));
 }
 
+//
+// makeShared
+//
+
+template <typename Args>
+static inline SoapySDR::Device::SPtr makeSharedCommon(const Args &args)
+{
+    return SoapySDR::Device::SPtr(
+        SoapySDR::Device::make(args),
+        getDeviceDeleter()
+    );
+}
+
+SoapySDR::Device::SPtr SoapySDR::Device::makeShared(const Kwargs &args)
+{
+    return makeSharedCommon(args);
+}
+
+SoapySDR::Device::SPtr SoapySDR::Device::makeShared(const std::string &args)
+{
+    return makeSharedCommon(args);
+}
+
 void SoapySDR::Device::unmake(Device *device)
 {
     if (device == nullptr) return; //safe to unmake a null device
@@ -280,6 +313,40 @@ std::vector<SoapySDR::Device *> SoapySDR::Device::make(const std::vector<std::st
     return make(kwargsList);
 }
 
+//
+// Parallel makeShared
+//
+
+template <typename Args>
+static inline std::vector<SoapySDR::Device::SPtr> makeSharedParallelCommon(const std::vector<Args> &argsList)
+{
+    auto rawPtrs = SoapySDR::Device::make(argsList);
+    std::vector<SoapySDR::Device::SPtr> sharedPtrs;
+    std::transform(
+        rawPtrs.begin(),
+        rawPtrs.end(),
+        std::back_inserter(sharedPtrs),
+        [](SoapySDR::Device *device)
+        {
+            return SoapySDR::Device::SPtr(
+                device,
+                getDeviceDeleter()
+            );
+        });
+
+    return sharedPtrs;
+}
+
+std::vector<SoapySDR::Device::SPtr> SoapySDR::Device::makeShared(const KwargsList &argsList)
+{
+    return makeSharedParallelCommon(argsList);
+}
+
+std::vector<SoapySDR::Device::SPtr> SoapySDR::Device::makeShared(const std::vector<std::string> &argsList)
+{
+    return makeSharedParallelCommon(argsList);
+}
+
 void SoapySDR::Device::unmake(const std::vector<Device *> &devices)
 {
     std::vector<std::future<void>> futures;

swig/soapy_common.i

@@ -1,4 +1,4 @@
-// Copyright (c) 2021-2022 Nicholas Corgan
+// Copyright (c) 2021-2023 Nicholas Corgan
 // SPDX-License-Identifier: BSL-1.0
 
 ////////////////////////////////////////////////////////////////////////
@@ -18,6 +18,9 @@
 // Common ignores
 ////////////////////////////////////////////////////////////////////////
 
+// SoapySDR/Device.hpp
+%ignore SoapySDR::Device::makeShared;
+
 // SoapySDR/Errors.h
 %ignore SoapySDR_errToStr;