Enhance error handling and refactor C API for improved robustness

- Added new error handling functions and updated existing ones to use error codes instead of exceptions, enhancing the stability of the C API.
- Refactored memory allocation in `dup_cstr` and other functions to handle out-of-memory scenarios gracefully.
- Introduced `clear_error` and improved error reporting mechanisms across various functions to ensure consistent error management.
- Updated function signatures to return status or optional types, improving clarity and usability.
- Enhanced the `from_experiment` and `load` functions to provide better error feedback and prevent crashes due to invalid inputs.

Author: MacroModel

include/phy_engine/phy_lab_wrapper/auto_layout/auto_layout.h

@@ -3,6 +3,7 @@
 #include "physicslab.h"
 
 #include <cstring>
+#include <new>
 #include <string>
 
 // Minimal C API for embedding / wasm bindings.
@@ -13,10 +14,12 @@ namespace phy_engine::phy_lab_wrapper::c_api::detail
 inline thread_local std::string last_error;
 
 inline void set_error(std::string msg) { last_error = std::move(msg); }
+inline void clear_error() noexcept { last_error.clear(); }
 
 inline char* dup_cstr(std::string const& s)
 {
-    auto* out = new char[s.size() + 1];
+    auto* out = new (std::nothrow) char[s.size() + 1];
+    if(out == nullptr) { return nullptr; }
     std::memcpy(out, s.data(), s.size());
     out[s.size()] = '\0';
     return out;
@@ -37,44 +40,39 @@ inline void plw_string_free(char* s) { delete[] s; }
 inline plw_experiment_t plw_experiment_create(int type_value)
 {
     using namespace phy_engine::phy_lab_wrapper;
-    try
+    c_api::detail::clear_error();
+    auto type = static_cast<experiment_type>(type_value);
+    auto* ex = new (std::nothrow) experiment(experiment::create(type));
+    if(ex == nullptr)
     {
-        auto type = static_cast<experiment_type>(type_value);
-        return new experiment(experiment::create(type));
-    }
-    catch (std::exception const& e)
-    {
-        c_api::detail::set_error(e.what());
-        return nullptr;
-    }
-    catch (...)
-    {
-        c_api::detail::set_error("unknown error");
+        c_api::detail::set_error("out of memory");
         return nullptr;
     }
+    return ex;
 }
 
 inline plw_experiment_t plw_experiment_load_from_string(char const* sav_json)
 {
     using namespace phy_engine::phy_lab_wrapper;
-    try
+    c_api::detail::clear_error();
+    if(sav_json == nullptr)
     {
-        if (sav_json == nullptr)
-        {
-            throw std::invalid_argument("sav_json is null");
-        }
-        return new experiment(experiment::load_from_string(sav_json));
+        c_api::detail::set_error("sav_json is null");
+        return nullptr;
     }
-    catch (std::exception const& e)
+    auto r = experiment::load_from_string_ec(sav_json);
+    if(!r)
     {
-        c_api::detail::set_error(e.what());
+        c_api::detail::set_error(r.st.message);
         return nullptr;
     }
-    catch (...)
+    auto* ex = new (std::nothrow) experiment(std::move(*r.value));
+    if(ex == nullptr)
     {
-        c_api::detail::set_error("unknown error");
+        c_api::detail::set_error("out of memory");
         return nullptr;
     }
+    return ex;
 }
 
 inline void plw_experiment_destroy(plw_experiment_t handle)
@@ -86,25 +84,26 @@ inline void plw_experiment_destroy(plw_experiment_t handle)
 inline char* plw_experiment_dump(plw_experiment_t handle, int indent)
 {
     using namespace phy_engine::phy_lab_wrapper;
-    try
+    c_api::detail::clear_error();
+    auto* ex = static_cast<experiment*>(handle);
+    if(ex == nullptr)
     {
-        auto* ex = static_cast<experiment*>(handle);
-        if (ex == nullptr)
-        {
-            throw std::invalid_argument("experiment handle is null");
-        }
-        return c_api::detail::dup_cstr(ex->dump(indent));
+        c_api::detail::set_error("experiment handle is null");
+        return nullptr;
     }
-    catch (std::exception const& e)
+    auto r = ex->dump_ec(indent);
+    if(!r)
     {
-        c_api::detail::set_error(e.what());
+        c_api::detail::set_error(r.st.message);
         return nullptr;
     }
-    catch (...)
+    auto* out = c_api::detail::dup_cstr(*r.value);
+    if(out == nullptr)
     {
-        c_api::detail::set_error("unknown error");
+        c_api::detail::set_error("out of memory");
         return nullptr;
     }
+    return out;
 }
 
 inline char* plw_experiment_add_circuit_element(plw_experiment_t handle,
@@ -115,30 +114,31 @@ inline char* plw_experiment_add_circuit_element(plw_experiment_t handle,
                                                 int element_xyz_coords)
 {
     using namespace phy_engine::phy_lab_wrapper;
-    try
+    c_api::detail::clear_error();
+    auto* ex = static_cast<experiment*>(handle);
+    if(ex == nullptr)
     {
-        auto* ex = static_cast<experiment*>(handle);
-        if (ex == nullptr)
-        {
-            throw std::invalid_argument("experiment handle is null");
-        }
-        if (model_id == nullptr)
-        {
-            throw std::invalid_argument("model_id is null");
-        }
-        auto id = ex->add_circuit_element(model_id, position{x, y, z}, element_xyz_coords != 0);
-        return c_api::detail::dup_cstr(id);
+        c_api::detail::set_error("experiment handle is null");
+        return nullptr;
+    }
+    if(model_id == nullptr)
+    {
+        c_api::detail::set_error("model_id is null");
+        return nullptr;
     }
-    catch (std::exception const& e)
+    auto id_r = ex->add_circuit_element_ec(model_id, position{x, y, z}, element_xyz_coords != 0);
+    if(!id_r)
     {
-        c_api::detail::set_error(e.what());
+        c_api::detail::set_error(id_r.st.message);
         return nullptr;
     }
-    catch (...)
+    auto* out = c_api::detail::dup_cstr(*id_r.value);
+    if(out == nullptr)
     {
-        c_api::detail::set_error("unknown error");
+        c_api::detail::set_error("out of memory");
         return nullptr;
     }
+    return out;
 }
 
 inline int plw_experiment_connect(plw_experiment_t handle,
@@ -149,31 +149,25 @@ inline int plw_experiment_connect(plw_experiment_t handle,
                                  int color_value)
 {
     using namespace phy_engine::phy_lab_wrapper;
-    try
+    c_api::detail::clear_error();
+    auto* ex = static_cast<experiment*>(handle);
+    if(ex == nullptr)
     {
-        auto* ex = static_cast<experiment*>(handle);
-        if (ex == nullptr)
-        {
-            throw std::invalid_argument("experiment handle is null");
-        }
-        if (src_id == nullptr || dst_id == nullptr)
-        {
-            throw std::invalid_argument("src_id/dst_id is null");
-        }
-        ex->connect(src_id, src_pin, dst_id, dst_pin, static_cast<wire_color>(color_value));
-        return 0;
+        c_api::detail::set_error("experiment handle is null");
+        return 1;
     }
-    catch (std::exception const& e)
+    if(src_id == nullptr || dst_id == nullptr)
     {
-        c_api::detail::set_error(e.what());
+        c_api::detail::set_error("src_id/dst_id is null");
         return 1;
     }
-    catch (...)
+    auto st = ex->connect_ec(src_id, src_pin, dst_id, dst_pin, static_cast<wire_color>(color_value));
+    if(!st)
     {
-        c_api::detail::set_error("unknown error");
+        c_api::detail::set_error(st.message);
         return 1;
     }
+    return 0;
 }
 
 }  // extern "C"
-

include/phy_engine/phy_lab_wrapper/c_api.h

@@ -0,0 +1,15 @@
+#pragma once
+
+#include <string>
+#include <utility>
+
+namespace phy_engine::phy_lab_wrapper::detail
+{
+    inline thread_local std::string last_error{};
+
+    inline void set_last_error(std::string msg) { last_error = std::move(msg); }
+    inline void clear_last_error() noexcept { last_error.clear(); }
+
+    [[nodiscard]] inline char const* last_error_c_str() noexcept { return last_error.c_str(); }
+}  // namespace phy_engine::phy_lab_wrapper::detail
+

include/phy_engine/phy_lab_wrapper/error.h

@@ -30,7 +30,7 @@ struct corner_locator
     position x_axis{};  // left->right direction (u axis)
     position y_axis{};  // bottom->top direction (v axis)
 
-    [[nodiscard]] static corner_locator from_experiment(experiment const& ex, corner_markers markers)
+    [[nodiscard]] static status_or<corner_locator> from_experiment_ec(experiment const& ex, corner_markers markers) noexcept
     {
         auto find_first_by_model_id = [&](std::string_view model_id) -> std::optional<position> {
             for(auto const& e : ex.elements())
@@ -53,10 +53,12 @@ struct corner_locator
             auto missing = [&](std::optional<position> const& p, std::string_view name, std::string_view mid) -> std::string {
                 return p ? std::string{} : (std::string(name) + " (" + std::string(mid) + ") ");
             };
-            throw std::runtime_error("corner_locator: missing marker(s): " + missing(lt, "left_top", markers.left_top_model_id) +
-                                     missing(lb, "left_bottom", markers.left_bottom_model_id) +
-                                     missing(rt, "right_top", markers.right_top_model_id) +
-                                     missing(rb, "right_bottom", markers.right_bottom_model_id));
+            auto msg = "corner_locator: missing marker(s): " + missing(lt, "left_top", markers.left_top_model_id) +
+                       missing(lb, "left_bottom", markers.left_bottom_model_id) +
+                       missing(rt, "right_top", markers.right_top_model_id) +
+                       missing(rb, "right_bottom", markers.right_bottom_model_id);
+            ::phy_engine::phy_lab_wrapper::detail::set_last_error(msg);
+            return status{std::errc::invalid_argument, std::move(msg)};
         }
 
         corner_locator out{};
@@ -81,11 +83,28 @@ struct corner_locator
         return out;
     }
 
+    [[nodiscard]] static status_or<corner_locator> from_sav_ec(std::filesystem::path const& sav_path, corner_markers markers) noexcept
+    {
+        auto ex_r = experiment::load_ec(sav_path);
+        if(!ex_r) { return ex_r.st; }
+        return from_experiment_ec(*ex_r.value, markers);
+    }
+
+#if PHY_ENGINE_ENABLE_EXCEPTIONS
+    [[nodiscard]] static corner_locator from_experiment(experiment const& ex, corner_markers markers)
+    {
+        auto r = from_experiment_ec(ex, markers);
+        if(!r) { throw std::runtime_error(r.st.message); }
+        return std::move(*r.value);
+    }
+
     [[nodiscard]] static corner_locator from_sav(std::filesystem::path const& sav_path, corner_markers markers)
     {
-        auto ex = experiment::load(sav_path);
-        return from_experiment(ex, markers);
+        auto r = from_sav_ec(sav_path, markers);
+        if(!r) { throw std::runtime_error(r.st.message); }
+        return std::move(*r.value);
     }
+#endif
 
     // Map a point in the unit square (u,v in [0,1]) into native coordinates.
     // u: left->right, v: bottom->top.