Make spice kernel (un)loading faster and safe in parallel sims

Author: juan-g-bonilla

src/simulation/environment/spiceInterface/spiceInterface.cpp

@@ -23,6 +23,49 @@
 #include "architecture/utilities/simDefinitions.h"
 #include "architecture/utilities/macroDefinitions.h"
 #include "architecture/utilities/rigidBodyKinematics.h"
+#include "spiceInterface.h"
+
+namespace {
+    /**
+     * RAII guard for SPICE error mode.
+     *
+     * Sets SPICE error action to RETURN while the guard is alive so that
+     * calls report failures via failed_c() instead of aborting. Restores
+     * the previous error action and print settings on destruction.
+     */
+    struct SpiceErrorModeGuard
+    {
+        char oldAction[32];
+        char oldPrint[32];
+
+        SpiceErrorModeGuard()
+        {
+            erract_c("GET", sizeof(oldAction), oldAction);
+            errprt_c("GET", sizeof(oldPrint),  oldPrint);
+
+            // Only override the abort behavior
+            erract_c("SET", 0, const_cast<char*>("RETURN"));
+            // DO NOT suppress printing: errprt is left untouched
+        }
+
+        ~SpiceErrorModeGuard()
+        {
+            erract_c("SET", 0, oldAction);
+            errprt_c("SET", 0, oldPrint);
+        }
+    };
+
+    /**
+     * Normalize a file system path to a canonical absolute string.
+     *
+     * Used to key kernels so that one physical file maps to a single
+     * cache entry even if referenced through different relative paths.
+     */
+    std::string absolutize(const std::filesystem::path& path)
+    {
+        return std::filesystem::absolute(path).lexically_normal().string();
+    }
+}
 
 /*! This constructor initializes the variables that spice uses.  Most of them are
  not intended to be changed, but a couple are user configurable.
@@ -74,11 +117,6 @@ SpiceInterface::~SpiceInterface()
         delete this->transRefStateOutMsgs.at(c);
     }
     delete [] this->spiceBuffer;
-//    if(this->SPICELoaded)
-//    {
-//        this->clearKeeper();
-//    }
-    return;
 }
 
 void SpiceInterface::clearKeeper()
@@ -426,63 +464,46 @@ void SpiceInterface::pullSpiceData(std::vector<SpicePlanetStateMsgPayload> *spic
     }
 }
 
-/*! This method loads a requested SPICE kernel into the system memory.  It is
- its own method because we have to load several SPICE kernels in for our
- application.  Note that they are stored in the SPICE library and are not
- held locally in this object.
- @return int Zero for success one for failure
- @param kernelName The name of the kernel we are loading
- @param dataPath The path to the data area on the filesystem
+/**
+ * Load a SPICE kernel for use by this interface.
+ *
+ * This function takes a kernel file name and a base directory and
+ * ensures that the corresponding SPICE kernel is available to the
+ * simulation. Internally the module keeps track of which kernels it
+ * has already loaded so that the same file is not loaded multiple
+ * times.
+ *
+ * @param kernelName File name of the kernel inside dataPath.
+ * @param dataPath   Directory where the kernel is located.
+ * @return 0 on success, 1 if loading the kernel failed.
  */
 int SpiceInterface::loadSpiceKernel(char *kernelName, const char *dataPath)
 {
-    char *fileName = new char[this->charBufferSize];
-    SpiceChar *name = new SpiceChar[this->charBufferSize];
-
-    //! - The required calls come from the SPICE documentation.
-    //! - The most critical call is furnsh_c
-    strcpy(name, "REPORT");
-    erract_c("SET", this->charBufferSize, name);
-    strcpy(fileName, dataPath);
-    strcat(fileName, kernelName);
-    furnsh_c(fileName);
-
-    //! - Check to see if we had trouble loading a kernel and alert user if so
-    strcpy(name, "DEFAULT");
-    erract_c("SET", this->charBufferSize, name);
-    delete[] fileName;
-    delete[] name;
-    if(failed_c()) {
-        return 1;
-    }
+    std::filesystem::path base(dataPath);
+    std::filesystem::path fullPath = base / kernelName;
+    auto kernel = SpiceKernel::request(fullPath.string());
+    if (!kernel->wasLoadSuccesful()) return 1;
+    this->loadedKernels[kernel->getPath()] = kernel;
     return 0;
 }
 
-/*! This method unloads a requested SPICE kernel into the system memory.  It is
- its own method because we have to load several SPICE kernels in for our
- application.  Note that they are stored in the SPICE library and are not
- held locally in this object.
- @return int Zero for success one for failure
- @param kernelName The name of the kernel we are unloading
- @param dataPath The path to the data area on the filesystem
+/**
+ * Tell this interface that a SPICE kernel is no longer needed.
+ *
+ * This function removes the kernel from the set of kernels managed
+ * by this interface. Once no users remain, the underlying kernel is
+ * also removed from SPICE so it no longer affects future queries.
+ *
+ * @param kernelName File name of the kernel inside dataPath.
+ * @param dataPath   Directory where the kernel is located.
+ * @return always 0.
  */
 int SpiceInterface::unloadSpiceKernel(char *kernelName, const char *dataPath)
 {
-    char *fileName = new char[this->charBufferSize];
-    SpiceChar *name = new SpiceChar[this->charBufferSize];
-
-    //! - The required calls come from the SPICE documentation.
-    //! - The most critical call is furnsh_c
-    strcpy(name, "REPORT");
-    erract_c("SET", this->charBufferSize, name);
-    strcpy(fileName, dataPath);
-    strcat(fileName, kernelName);
-    unload_c(fileName);
-    delete[] fileName;
-    delete[] name;
-    if(failed_c()) {
-        return 1;
-    }
+    std::filesystem::path base(dataPath);
+    std::filesystem::path fullPath = base / kernelName;
+    auto key = absolutize(fullPath);
+    this->loadedKernels.erase(key);
     return 0;
 }
 
@@ -506,3 +527,61 @@ std::string SpiceInterface::getCurrentTimeString()
 	delete[] spiceOutputBuffer;
 	return(returnTimeString);
 }
+
+std::mutex SpiceKernel::mutex;
+std::unordered_map<std::string, std::weak_ptr<SpiceKernel>> SpiceKernel::cache;
+
+std::shared_ptr<SpiceKernel>
+SpiceKernel::request(const std::filesystem::path& path)
+{
+    const std::string key = absolutize(path);
+
+    std::lock_guard<std::mutex> lock(mutex);
+
+    auto it = cache.find(key);
+    if (it != cache.end())
+    {
+        if (auto existing = it->second.lock())
+        {
+            // Already have a live handle to this kernel
+            return existing;
+        }
+        // Weak pointer expired - fall through and create a new one
+    }
+
+    // First live handle for this absolute path in this process
+    auto handle = std::shared_ptr<SpiceKernel>(new SpiceKernel(key));
+
+    if (handle->loadSucceeded) cache[key] = handle;
+
+    return handle;
+}
+
+SpiceKernel::~SpiceKernel() noexcept
+{
+    if (!loadSucceeded) return;
+
+    SpiceErrorModeGuard guard;
+    unload_c(path.c_str());
+    if (failed_c())
+    {
+        reset_c();   // SPICE printed its own messages already
+    }
+}
+
+SpiceKernel::SpiceKernel(std::string path_)
+    : path(std::move(path_))
+{
+    SpiceErrorModeGuard guard;
+    furnsh_c(path.c_str());
+
+    if (failed_c())
+    {
+        reset_c();             // SPICE already printed diagnostics
+        loadSucceeded = false; // destructor will not unload
+    }
+    else
+    {
+        loadSucceeded = true;
+    }
+}

src/simulation/environment/spiceInterface/spiceInterface.h

@@ -22,6 +22,11 @@
 
 #include <vector>
 #include <map>
+#include <filesystem>
+#include <memory>
+#include <mutex>
+#include <string>
+#include <unordered_map>
 #include "architecture/_GeneralModuleFiles/sys_model.h"
 #include "architecture/utilities/linearAlgebra.h"
 #include "architecture/utilities/bskLogging.h"
@@ -35,6 +40,79 @@
 #include "architecture/msgPayloadDefC/TransRefMsgPayload.h"
 #include "architecture/messaging/messaging.h"
 
+/**
+ * Thin RAII wrapper around a single SPICE kernel.
+ *
+ * The class furnishes a kernel on construction and unloads it on
+ * destruction, and provides a static request function that caches
+ * instances by canonical absolute path so that a given kernel file is
+ * not furnished multiple times.
+ */
+class SpiceKernel
+{
+public:
+    /**
+     * Request a shared handle for the kernel at the given path.
+     *
+     * The first call for a canonical path constructs a SpiceKernel, which
+     * furnishes the kernel once. Later calls for the same path reuse the
+     * existing instance as long as it is still alive.
+     */
+    static std::shared_ptr<SpiceKernel> request(const std::filesystem::path& path);
+
+    /**
+     * Destructor unloads the kernel from SPICE if the load succeeded.
+     *
+     * This runs once when the last shared_ptr owning this SpiceKernel
+     * instance is destroyed.
+     */
+    ~SpiceKernel();
+
+    /// Canonical absolute path used as the cache key and SPICE file name.
+    const std::string& getPath() const { return path; }
+
+    /// True if furnsh_c succeeded for this kernel.
+    bool wasLoadSuccesful() const {return loadSucceeded; };
+
+    // avoid copy operations
+    SpiceKernel(const SpiceKernel&) = delete;
+    SpiceKernel& operator=(const SpiceKernel&) = delete;
+
+private:
+    /**
+     * Construct a SpiceKernel by furnishing the given canonical path.
+     *
+     * The constructor switches SPICE into RETURN mode, calls furnsh_c,
+     * checks failed_c, and records the load status. The destructor will
+     * unload only if loadSucceeded is true.
+     */
+    explicit SpiceKernel(std::string path);
+
+    /// Canonical absolute path used as the cache key and SPICE file name.
+    std::string path;
+
+    /// True if furnsh_c succeeded for this kernel.
+    bool loadSucceeded;
+
+    /**
+     * Static mutex guarding the shared kernel cache.
+     *
+     * All access to SpiceKernel::cache must take this lock so that repeated
+     * calls to request from different threads do not race.
+     */
+    static std::mutex mutex;
+
+    /**
+     * Global cache mapping canonical absolute paths to weak pointers.
+     *
+     * A non expired weak pointer means there is already a live SpiceKernel
+     * instance owning that kernel, so request can reuse it instead of
+     * calling furnsh_c again.
+     */
+    static std::unordered_map<std::string, std::weak_ptr<SpiceKernel>> cache;
+};
+
+
 /*! @brief spice interface class */
 class SpiceInterface: public SysModel {
 public:
@@ -50,7 +128,17 @@ class SpiceInterface: public SysModel {
     void computeGPSData();
     void pullSpiceData(std::vector<SpicePlanetStateMsgPayload> *spiceData);
     void writeOutputMessages(uint64_t CurrentClock);
-    void clearKeeper();                         //!< class method
+    
+    /** Resets all data loaded to SPICE.
+     * 
+     * Calls `kclear_c`, which resets all loaded kernels for all simulations
+     * in this process. Avoid using this, as it can affect other simulations
+     * running in parallel. Kernels loaded with `loadSpiceKernel` will be
+     * automatically cleared when all simulations that need it have closed.
+     * 
+     * Deprecated, pending removal 11/20/2026.
+     */
+    void clearKeeper();
     void addPlanetNames(std::vector<std::string> planetNames);
     void addSpacecraftNames(std::vector<std::string> spacecraftNames);
 
@@ -90,6 +178,15 @@ class SpiceInterface: public SysModel {
     std::vector<SpicePlanetStateMsgPayload> planetData;
     std::vector<SpicePlanetStateMsgPayload> scData;
 
+    /**
+     * Map of loaded kernel paths to their RAII handles.
+     *
+     * As long as an entry is present, the corresponding kernel remains
+     * furnished in SPICE. Removing an entry allows the SpiceKernel
+     * destructor to unload the kernel when all shared_ptr copies are
+     * gone.
+     */
+    std::unordered_map<std::string, std::shared_ptr<SpiceKernel>> loadedKernels;
 };