feat: initial draft of lifecycle events API for plugins (#15293)

# Description

This PR introduces lifecycle events to the plugin API. 
For all plugin capabilities, you can define a `on_lifecycle_event`
function in the plugin that takes in a event enum and a small payload
for some generic information on the lifecycle event.
The idea is to keep the payload generic and small, and if you want to
get more information, you should invoke other more targeted APIs to get
more information.
For example, lets say you are keeping track of the the `ObjectAdded*`
event hook for model transformation, addition or deletion. The payload
would tell you the name of the model, and you should use a targeted API
such as `orca.host.plater().model()` to get more information on the
model. This is the overall design principle of the API.

Currently the lifecycle events are the following:
```cpp
    enum class LifecycleEvent {
        // Project (3mf)
        NewProject,
        ProjectOpened,
        ProjectBeforeSave,
        ProjectAfterSave,
        ProjectClosed,
        ProjectDirtyChanged,

        // Slicing pipeline
        SliceStarted,
        SliceGeometryFinished,
        GCodeExportStarted,
        GCodeExportFinished,
        SlicingJobComplete,

        // Plate/model editing
        ObjectAdded,
        ObjectDeleted,
        ObjectTransformed,
        ObjectChanged,
        ObjectRenamed,
        PlateCreated,
        PlateDeleted,
        PlateSelected,
        PlateRenamed,

        // Preset
        PresetSelected,
        PresetSaved,

        // Printer/device
        PrintStateChanged,
        DeviceOnlineChanged,
        DeviceDiscovered,
        DeviceSelected,
        DeviceConnected,
        DeviceDisconnected,
        UploadStarted,
        UploadFinished,

        // Print/send jobs
        PrintJobStarted,
        PrintJobFinished,
        SendJobStarted,
        SendJobFinished,
    };
```

This is an initial draft and lifecycle events can be included later on.

[orca_telegram_notifier_plugin_any.py](https://github.com/user-attachments/files/31220973/orca_telegram_notifier_plugin_any.py)

If you're familiar with telegram bots, after you install the telegram
bot, in the config of this plugin, you can enter the Bot ID and the Chat
ID with said bot.

# Screenshots/Recordings/Graphs

<!--
> Please attach relevant screenshots to showcase the UI changes.
> Please attach images that can help explain the changes.
-->

## Tests

<!--
> Please describe the tests that you have conducted to verify the
changes made in this PR.
-->

For this plugin, I am testing it with a telegram bot that sends me a
message on lifecycle event.


<!--
> A guide for users on how to download the artifacts from this PR.
-->

[How to Download Pull Requests Artifacts for
Testing](https://www.orcaslicer.com/wiki/how_to_download_pr_artifacts)

src/libslic3r/GCode.cpp

@@ -8,6 +8,7 @@
 #include "I18N.hpp"
 #include "GCode.hpp"
 #include "Exception.hpp"
+#include "LifecycleEvents.hpp"
 #include "ExtrusionEntity.hpp"
 #include "EdgeGrid.hpp"
 #include "Geometry/ConvexHull.hpp"
@@ -2476,6 +2477,15 @@ void GCode::do_export(Print* print, const char* path, GCodeProcessorResult* resu
     m_writer.set_is_bbl_machine(print->is_BBL_printer());
     print->set_started(psGCodeExport);
 
+    {
+        LifecycleEventContext ctx;
+        ctx.name = std::to_string(print->model().id().id);
+        ctx.code = LifecycleEvtCode::Ok;
+        ctx.msg  = path;
+        ctx.cancellation_check = [print]() { return print->canceled(); };
+        fire_lifecycle_event(LifecycleEvent::GCodeExportStarted, ctx);
+    }
+
     // check if any custom gcode contains keywords used by the gcode processor to
     // produce time estimation and gcode toolpaths
     std::vector<std::pair<std::string, std::string>> validation_res = DoExport::validate_custom_gcode(*print);
@@ -2511,12 +2521,23 @@ void GCode::do_export(Print* print, const char* path, GCodeProcessorResult* resu
     m_processor.set_print(print);
     GCodeOutputStream file(boost::nowide::fopen(path_tmp.c_str(), "wb"), m_processor);
     if (! file.is_open()) {
-        BOOST_LOG_TRIVIAL(error) << std::string("G-code export to ") + path + " failed.\nCannot open the file for writing.\n" << std::endl;
+        std::string err_msg = std::string("G-code export to ") + path + " failed.\nCannot open the file for writing.\n";
+        BOOST_LOG_TRIVIAL(error) << err_msg << std::endl;
         if (!fs::exists(folder)) {
             //fs::create_directory(folder);
-            BOOST_LOG_TRIVIAL(error) << "the parent path " + folder.string() +" is not there!!!" << std::endl;
+            std::string add_err_msg = "the parent path " + folder.string() +" is not there!!!";
+            BOOST_LOG_TRIVIAL(error) << add_err_msg << std::endl;
+            err_msg += add_err_msg;
         }
-        throw Slic3r::RuntimeError(std::string("G-code export to ") + path + " failed.\nCannot open the file for writing.\n");
+        {
+            LifecycleEventContext ctx;
+            ctx.name = std::to_string(print->model().id().id);
+            ctx.code = LifecycleEvtCode::Error;
+            ctx.msg  = std::string(path) + "\n" + err_msg;
+            ctx.cancellation_check = [print]() { return print->canceled(); };
+            fire_lifecycle_event(LifecycleEvent::GCodeExportFinished, ctx);
+        }
+        throw Slic3r::RuntimeError(err_msg);
     }
 
     try {
@@ -2527,11 +2548,19 @@ void GCode::do_export(Print* print, const char* path, GCodeProcessorResult* resu
             boost::nowide::remove(path_tmp.c_str());
             throw Slic3r::RuntimeError(std::string("G-code export to ") + path + " failed\nIs the disk full?\n");
         }
-    } catch (std::exception & /* ex */) {
+    } catch (std::exception &ex) {
         // Rethrow on any exception. std::runtime_exception and CanceledException are expected to be thrown.
         // Close and remove the file.
         file.close();
         boost::nowide::remove(path_tmp.c_str());
+        {
+            LifecycleEventContext ctx;
+            ctx.name = std::to_string(print->model().id().id);
+            ctx.code = LifecycleEvtCode::Error;
+            ctx.msg  = std::string(path) + "\n" + ex.what();
+            ctx.cancellation_check = [print]() { return print->canceled(); };
+            fire_lifecycle_event(LifecycleEvent::GCodeExportFinished, ctx);
+        }
         throw;
     }
     file.close();
@@ -2637,6 +2666,14 @@ void GCode::do_export(Print* print, const char* path, GCodeProcessorResult* resu
 
     std::error_code ret = rename_file(path_tmp, path);
     if (ret) {
+        {
+            LifecycleEventContext ctx;
+            ctx.name = std::to_string(print->model().id().id);
+            ctx.code = LifecycleEvtCode::Error;
+            ctx.msg  = std::string(path) + "\nFailed to rename the output G-code file: " + ret.message();
+            ctx.cancellation_check = [print]() { return print->canceled(); };
+            fire_lifecycle_event(LifecycleEvent::GCodeExportFinished, ctx);
+        }
         throw Slic3r::RuntimeError(
             std::string("Failed to rename the output G-code file from ") + path_tmp + " to " + path + '\n' + "error code " + ret.message() + '\n' +
             "Is " + path_tmp + " locked?" + '\n');
@@ -2647,7 +2684,16 @@ void GCode::do_export(Print* print, const char* path, GCodeProcessorResult* resu
 
     BOOST_LOG_TRIVIAL(info) << "Exporting G-code finished" << log_memory_info();
     print->set_done(psGCodeExport);
-    
+
+    {
+        LifecycleEventContext ctx;
+        ctx.name = std::to_string(print->model().id().id);
+        ctx.code = LifecycleEvtCode::Ok;
+        ctx.msg  = path;
+        ctx.cancellation_check = [print]() { return print->canceled(); };
+        fire_lifecycle_event(LifecycleEvent::GCodeExportFinished, ctx);
+    }
+
     // Orca: label_object_enabled reflects whether objects are labeled in the g-code (EXCLUDE_OBJECT /
     // M486), which is driven by exclude_object for every printer
     if(result != nullptr)

src/libslic3r/LifecycleEvents.hpp

@@ -0,0 +1,249 @@
+#pragma once
+
+// LifecycleEvents.hpp
+// --------------------
+// Application lifecycle events (project, slicing, plate editing, preset, printer connection, and
+// job activity) that other subsystems -- chiefly the plugin layer above libslic3r -- may want to
+// observe. Lives in libslic3r rather than the plugin layer because some events fire from inside
+// the slicing engine itself; see fire_lifecycle_event() below.
+
+#include <functional>
+#include <condition_variable>
+#include <cstddef>
+#include <mutex>
+#include <string>
+#include <utility>
+
+namespace Slic3r
+{
+    enum class LifecycleEvent {
+        // Project (3mf)
+        NewProject,
+        ProjectOpened,
+        ProjectBeforeSave,
+        ProjectAfterSave,
+        ProjectClosed,
+        ProjectDirtyChanged,
+
+        // Slicing pipeline
+        SliceStarted,
+        SliceGeometryFinished,
+        GCodeExportStarted,
+        GCodeExportFinished,
+        SlicingJobComplete,
+
+        // Plate/model editing
+        ObjectAdded,
+        ObjectDeleted,
+        ObjectTransformed,
+        ObjectChanged,
+        ObjectRenamed,
+        PlateCreated,
+        PlateDeleted,
+        PlateSelected,
+        PlateRenamed,
+
+        // Preset
+        PresetSelected,
+        PresetSaved,
+
+        // Printer/device
+        PrintStateChanged,
+        DeviceOnline,
+        DeviceOffline,
+        DeviceDiscovered,
+        DeviceSelected,
+        UploadStarted,
+        UploadFinished,
+
+        // Print/send jobs
+        PrintJobStarted,
+        PrintJobFinished,
+        SendJobStarted,
+        SendJobFinished,
+    };
+
+    // Scoped so callers must qualify (LifecycleEvtCode::Error, not ERROR) -- ERROR/OK collide with
+    // Windows macros (wingdi.h) as unqualified names.
+    enum class LifecycleEvtCode { Ok, Error, Warn };
+
+    struct LifecycleEventContext
+    {
+        // The primary subject identifier for the event. This is event-specific (for example, a
+        // project/output path, preset name, device id, or object name), must not contain status or
+        // prose, and may be empty when the event has no single subject.
+        std::string name;
+
+        // Outcome of the operation represented by the event. For state-change and start events,
+        // Ok means that the event occurred; it does not imply that a future operation succeeded.
+        LifecycleEvtCode code = LifecycleEvtCode::Ok;
+
+        // Optional human-readable detail or diagnostic text. It is not a stable parsing contract;
+        // machine-readable data should be represented by a dedicated field or event instead.
+        std::string msg;
+
+        // Stable subject/object identifier, when the source model provides one.
+        std::string id;
+
+        // Previous value for rename and other before/after events.
+        std::string previous_name;
+
+        // Device identifier for printer and job events.
+        std::string device_id;
+
+        // Job identifier when the originating queue/task provides one.
+        std::string job_id;
+
+        // Source subsystem or operation detail, suitable for filtering but not guaranteed to be
+        // exhaustive across versions.
+        std::string source;
+
+        // Plate, object, or volume index when the source uses an index rather than a stable id.
+        int index = -1;
+
+        // Aggregate project dirty state for ProjectDirtyChanged.
+        bool dirty = false;
+
+        // Optional host-side cancellation probe. Background slicing and G-code export events set
+        // this to the originating Print's cancellation state so dispatch can stop before calling
+        // the next capability. It is intentionally not exposed through the Python payload API.
+        std::function<bool()> cancellation_check;
+    };
+
+    inline std::string lifecycle_event_to_string(LifecycleEvent event)
+    {
+        switch (event) {
+        case LifecycleEvent::NewProject: return "NewProject";
+        case LifecycleEvent::ProjectOpened: return "ProjectOpened";
+        case LifecycleEvent::ProjectBeforeSave: return "ProjectBeforeSave";
+        case LifecycleEvent::ProjectAfterSave: return "ProjectAfterSave";
+        case LifecycleEvent::ProjectClosed: return "ProjectClosed";
+        case LifecycleEvent::ProjectDirtyChanged: return "ProjectDirtyChanged";
+
+        case LifecycleEvent::SliceStarted: return "SliceStarted";
+        case LifecycleEvent::SliceGeometryFinished: return "SliceGeometryFinished";
+        case LifecycleEvent::GCodeExportStarted: return "GCodeExportStarted";
+        case LifecycleEvent::GCodeExportFinished: return "GCodeExportFinished";
+        case LifecycleEvent::SlicingJobComplete: return "SlicingJobComplete";
+
+        case LifecycleEvent::ObjectAdded: return "ObjectAdded";
+        case LifecycleEvent::ObjectDeleted: return "ObjectDeleted";
+        case LifecycleEvent::ObjectTransformed: return "ObjectTransformed";
+        case LifecycleEvent::ObjectChanged: return "ObjectChanged";
+        case LifecycleEvent::ObjectRenamed: return "ObjectRenamed";
+        case LifecycleEvent::PlateCreated: return "PlateCreated";
+        case LifecycleEvent::PlateDeleted: return "PlateDeleted";
+        case LifecycleEvent::PlateSelected: return "PlateSelected";
+        case LifecycleEvent::PlateRenamed: return "PlateRenamed";
+
+        case LifecycleEvent::PresetSelected: return "PresetSelected";
+        case LifecycleEvent::PresetSaved: return "PresetSaved";
+        case LifecycleEvent::PrintStateChanged: return "PrintStateChanged";
+
+        case LifecycleEvent::DeviceOnline: return "DeviceOnline";
+        case LifecycleEvent::DeviceOffline: return "DeviceOffline";
+        case LifecycleEvent::DeviceDiscovered: return "DeviceDiscovered";
+        case LifecycleEvent::DeviceSelected: return "DeviceSelected";
+
+        case LifecycleEvent::UploadStarted: return "UploadStarted";
+        case LifecycleEvent::UploadFinished: return "UploadFinished";
+        case LifecycleEvent::PrintJobStarted: return "PrintJobStarted";
+        case LifecycleEvent::PrintJobFinished: return "PrintJobFinished";
+        case LifecycleEvent::SendJobStarted: return "SendJobStarted";
+        case LifecycleEvent::SendJobFinished: return "SendJobFinished";
+        default: return "Unknown";
+        }
+    }
+
+    inline std::string lifecycle_evt_code_to_string(LifecycleEvtCode code)
+    {
+        switch (code) {
+        case LifecycleEvtCode::Ok: return "Ok";
+        case LifecycleEvtCode::Error: return "Error";
+        case LifecycleEvtCode::Warn: return "Warn";
+        default: return "Unknown";
+        }
+    }
+
+    // Global cross-layer seam (mirrors ConfigBase::set_resolve_capability_fn): any libslic3r code can
+    // fire a lifecycle event without depending on the plugin layer above it, which installs the
+    // dispatcher here at startup. Not tied to Print/GCode specifically, since nothing here should
+    // require callers to hold a Print& just to report an event.
+    using LifecycleHookFn = std::function<void(LifecycleEvent, const LifecycleEventContext&)>;
+
+    namespace detail {
+
+    struct LifecycleHookState
+    {
+        std::mutex              mutex;
+        std::condition_variable cv;
+        LifecycleHookFn         fn;
+        std::size_t             active_dispatches = 0;
+        bool                    accepting        = false;
+    };
+
+    inline LifecycleHookState& lifecycle_hook_state()
+    {
+        static LifecycleHookState state;
+        return state;
+    }
+
+    class LifecycleDispatchGuard
+    {
+    public:
+        explicit LifecycleDispatchGuard(LifecycleHookState& state) : m_state(state) {}
+
+        ~LifecycleDispatchGuard()
+        {
+            std::lock_guard<std::mutex> lock(m_state.mutex);
+            --m_state.active_dispatches;
+            if (m_state.active_dispatches == 0)
+                m_state.cv.notify_all();
+        }
+
+        LifecycleDispatchGuard(const LifecycleDispatchGuard&)            = delete;
+        LifecycleDispatchGuard& operator=(const LifecycleDispatchGuard&) = delete;
+
+    private:
+        LifecycleHookState& m_state;
+    };
+
+    } // namespace detail
+
+    // Installing a hook starts accepting dispatches. Passing an empty function stops accepting
+    // new dispatches, detaches the hook, and waits for callbacks already in progress to finish.
+    // This is used during plugin shutdown so plugin code cannot be unloaded while a lifecycle
+    // callback is still executing. The empty-function path must not be called from inside the
+    // lifecycle callback itself.
+    inline void set_lifecycle_hook_fn(LifecycleHookFn fn)
+    {
+        detail::LifecycleHookState& state = detail::lifecycle_hook_state();
+        if (fn) {
+            std::lock_guard<std::mutex> lock(state.mutex);
+            state.fn        = std::move(fn);
+            state.accepting = true;
+            return;
+        }
+
+        std::unique_lock<std::mutex> lock(state.mutex);
+        state.accepting = false;
+        state.fn        = nullptr;
+        state.cv.wait(lock, [&state] { return state.active_dispatches == 0; });
+    }
+
+    inline void fire_lifecycle_event(LifecycleEvent event, const LifecycleEventContext& ctx)
+    {
+        detail::LifecycleHookState& state = detail::lifecycle_hook_state();
+        LifecycleHookFn             fn;
+        {
+            std::lock_guard<std::mutex> lock(state.mutex);
+            if (!state.accepting || !state.fn)
+                return;
+            fn = state.fn;
+            ++state.active_dispatches;
+        }
+
+        detail::LifecycleDispatchGuard guard(state);
+        fn(event, ctx);
+    }
+}

src/libslic3r/Preset.cpp

@@ -47,6 +47,7 @@
 #include <boost/log/trivial.hpp>
 
 #include "libslic3r.h"
+#include "LifecycleEvents.hpp"
 #include "Utils.hpp"
 #include "Time.hpp"
 #include "PlaceholderParser.hpp"
@@ -2972,6 +2973,7 @@ void PresetCollection::save_current_preset(const std::string &new_name, bool det
     // 1) Find the preset with a new_name or create a new one,
     // initialize it with the edited config.
     auto it = this->find_preset_internal(new_name);
+    const bool preset_existed = (it != m_presets.end() && it->name == new_name);
     if (it != m_presets.end() && it->name == new_name) {
         // Preset with the same name found.
         Preset &preset = *it;
@@ -3079,6 +3081,14 @@ void PresetCollection::save_current_preset(const std::string &new_name, bool det
         this->get_selected_preset().save(&(parent_preset->config));
     else
         this->get_selected_preset().save(nullptr);
+
+    {
+        LifecycleEventContext ctx;
+        ctx.name  = new_name;
+        ctx.msg = preset_existed ? "overwrite" : "new";
+        ctx.code = LifecycleEvtCode::Ok;
+        fire_lifecycle_event(LifecycleEvent::PresetSaved, ctx);
+    }
 }
 
 // A detached standalone preset for the Full Publish receiver: create a user preset holding

src/libslic3r/Print.cpp

@@ -14,6 +14,7 @@
 #include "Flow.hpp"
 #include "Geometry/ConvexHull.hpp"
 #include "I18N.hpp"
+#include "LifecycleEvents.hpp"
 #include "ShortestPath.hpp"
 #include "Thread.hpp"
 #include "Time.hpp"
@@ -2694,6 +2695,14 @@ void Print::process(long long *time_cost_with_cache, bool use_cache)
     if (m_objects.empty())
         return;
 
+    {
+        LifecycleEventContext ctx;
+        ctx.name = std::to_string(m_model.id().id);
+        ctx.code = LifecycleEvtCode::Ok;
+        ctx.cancellation_check = [this]() { return canceled(); };
+        fire_lifecycle_event(LifecycleEvent::SliceStarted, ctx);
+    }
+
     for (PrintObject *obj : m_objects)
         obj->clear_shared_object();
 
@@ -3312,6 +3321,14 @@ void Print::process(long long *time_cost_with_cache, bool use_cache)
     }
 
     BOOST_LOG_TRIVIAL(info) << "Slicing process finished." << log_memory_info();
+
+    {
+        LifecycleEventContext ctx;
+        ctx.name = std::to_string(m_model.id().id);
+        ctx.code = LifecycleEvtCode::Ok;
+        ctx.cancellation_check = [this]() { return canceled(); };
+        fire_lifecycle_event(LifecycleEvent::SliceGeometryFinished, ctx);
+    }
 }
 
 // G-code export process, running at a background thread.
@@ -4911,6 +4928,15 @@ void Print::set_gcode_file_invalidated()
 //BBS: add gcode file preload logic
 void Print::export_gcode_from_previous_file(const std::string& file, GCodeProcessorResult* result, ThumbnailsGeneratorCallback thumbnail_cb)
 {
+    {
+        LifecycleEventContext ctx;
+        ctx.name = std::to_string(m_model.id().id);
+        ctx.code = LifecycleEvtCode::Ok;
+        ctx.msg  = file;
+        ctx.cancellation_check = [this]() { return canceled(); };
+        fire_lifecycle_event(LifecycleEvent::GCodeExportStarted, ctx);
+    }
+
     try {
         GCodeProcessor processor;
         GCodeProcessor::s_IsBBLPrinter = is_BBL_printer();
@@ -4930,13 +4956,30 @@ void Print::export_gcode_from_previous_file(const std::string& file, GCodeProces
         *result = std::move(processor.extract_result());
         result->filament_change_sequence = filament_seq_loaded;
         result->nozzle_change_sequence   = nozzle_seq_loaded;
-    } catch (std::exception & /* ex */) {
+    } catch (std::exception &ex) {
         BOOST_LOG_TRIVIAL(error) << __FUNCTION__ <<  boost::format(": found errors when process gcode file %1%") %file.c_str();
+        {
+            LifecycleEventContext ctx;
+            ctx.name = std::to_string(m_model.id().id);
+            ctx.code = LifecycleEvtCode::Error;
+            ctx.msg  = file + "\n" + ex.what();
+            ctx.cancellation_check = [this]() { return canceled(); };
+            fire_lifecycle_event(LifecycleEvent::GCodeExportFinished, ctx);
+        }
         throw Slic3r::RuntimeError(
             std::string("Failed to process the G-code file ") + file + " from previous 3mf\n");
     }
 
     BOOST_LOG_TRIVIAL(info) << __FUNCTION__ <<  boost::format(":  process the G-code file %1% successfully")%file.c_str();
+
+    {
+        LifecycleEventContext ctx;
+        ctx.name = std::to_string(m_model.id().id);
+        ctx.code = LifecycleEvtCode::Ok;
+        ctx.msg  = file;
+        ctx.cancellation_check = [this]() { return canceled(); };
+        fire_lifecycle_event(LifecycleEvent::GCodeExportFinished, ctx);
+    }
 }
 
 std::tuple<float, float> Print::object_skirt_offset(double margin_height) const