💥✨ libhal 3.0.0

Migrate from Boost.LEAF to C++ exceptions

Author: Khalil Estell

.github/workflows/3.0.0-alpha.1.yml

@@ -0,0 +1,12 @@
+name: 🚀 Deploy exceptions v1
+
+on:
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    uses: libhal/ci/.github/workflows/[email protected]
+    with:
+      version: exceptions
+      arch: "x86_64"
+    secrets: inherit

.github/workflows/ci.yml

@@ -3,10 +3,6 @@ name: ✅ CI
 on:
   workflow_dispatch:
   pull_request:
-  release:
-    types:
-      - published
-      - deleted
   push:
     branches:
       - main
@@ -15,5 +11,5 @@ on:
 
 jobs:
   ci:
-    uses: libhal/ci/.github/workflows/library.yml@4.x.y
+    uses: libhal/ci/.github/workflows/library_check.yml@5.x.y
     secrets: inherit

CMakeLists.txt

@@ -47,9 +47,7 @@ libhal_unit_test(SOURCES
   tests/main.test.cpp
 
   PACKAGES
-  boost-leaf
   tl-function-ref
 
   LINK_LIBRARIES
-  boost::leaf
   tl::function-ref)

conanfile.py

@@ -26,9 +26,8 @@
 
 class libhal_conan(ConanFile):
     name = "libhal"
-    version = "2.0.3"
     license = "Apache-2.0"
-    url = "https://github.com/conan-io/conan-center-index"
+    url = "https://github.com/libhal/libhal"
     homepage = "https://libhal.github.io/libhal"
     description = ("A collection of interfaces and abstractions for embedded "
                    "peripherals and devices using modern C++")
@@ -51,10 +50,6 @@ def _compilers_minimum_version(self):
             "apple-clang": "14.0.0"
         }
 
-    @property
-    def _bare_metal(self):
-        return self.settings.os == "baremetal"
-
     def validate(self):
         if self.settings.get_safe("compiler.cppstd"):
             check_min_cppstd(self, self._min_cppstd)
@@ -66,7 +61,6 @@ def build_requirements(self):
 
     def requirements(self):
         self.requires("tl-function-ref/1.0.0")
-        self.requires("boost-leaf/1.83.0")
 
     def layout(self):
         cmake_layout(self)
@@ -90,13 +84,5 @@ def package_info(self):
         self.cpp_info.libdirs = []
         self.cpp_info.resdirs = []
 
-        if self._bare_metal:
-            self.cpp_info.defines = [
-                "BOOST_LEAF_EMBEDDED",
-                # TODO(#694): Remove this or have it be configurable. Users
-                # should not be forced to operate without thread support
-                "BOOST_LEAF_NO_THREADS"
-            ]
-
     def package_id(self):
         self.info.clear()

include/libhal/accelerometer.hpp

@@ -14,7 +14,6 @@
 
 #pragma once
 
-#include "error.hpp"
 #include "units.hpp"
 
 namespace hal {
@@ -53,16 +52,16 @@ class accelerometer
   /**
    * @brief Read the latest acceleration sensed by the device
    *
-   * @return result<read_t> - acceleration data
+   * @return read_t - acceleration data
    */
-  [[nodiscard]] result<read_t> read()
+  [[nodiscard]] read_t read()
   {
     return driver_read();
   }
 
   virtual ~accelerometer() = default;
 
 private:
-  virtual result<read_t> driver_read() = 0;
+  virtual read_t driver_read() = 0;
 };
 }  // namespace hal

include/libhal/adc.hpp

@@ -14,8 +14,6 @@
 
 #pragma once
 
-#include "error.hpp"
-
 namespace hal {
 /**
  * @brief Analog to Digital Converter (ADC) hardware abstraction interface.
@@ -50,16 +48,16 @@ class adc
   /**
    * @brief Sample the analog to digital converter and return the result
    *
-   * @return result<read_t> - the sampled adc value
+   * @return read_t - the sampled adc value
    */
-  [[nodiscard]] result<read_t> read()
+  [[nodiscard]] read_t read()
   {
     return driver_read();
   }
 
   virtual ~adc() = default;
 
 private:
-  virtual result<read_t> driver_read() = 0;
+  virtual read_t driver_read() = 0;
 };
 }  // namespace hal

include/libhal/can.hpp

@@ -17,7 +17,6 @@
 #include <array>
 #include <cstdint>
 
-#include "error.hpp"
 #include "functional.hpp"
 #include "units.hpp"
 
@@ -149,10 +148,9 @@ class can
    * @brief Configure this can bus port to match the settings supplied
    *
    * @param p_settings - settings to apply to can driver
-   * @return status - success or failure
    * @throws std::errc::invalid_argument if the settings could not be achieved.
    */
-  [[nodiscard]] status configure(const settings& p_settings)
+  void configure(const settings& p_settings)
   {
     return driver_configure(p_settings);
   }
@@ -176,11 +174,9 @@ class can
    * If this occurs, this function must be called to re-enable bus
    * communication.
    *
-   * @return status - success or failure. In the case this function fails
-   * repeatedly, it is advised to simply not use the bus anymore as something is
-   * critical wrong and may not be recoverable.
+   * @return throw - TBD
    */
-  [[nodiscard]] status bus_on()
+  void bus_on()
   {
     return driver_bus_on();
   }
@@ -189,13 +185,13 @@ class can
    * @brief Send a can message
    *
    * @param p_message - the message to be sent
-   * @return result<send_t> - success or failure
+   * @return send_t - Nothing currently
    * @throws std::errc::network_down - if the can device is in the "bus-off"
    * state. This can happen if a critical fault in the bus has occurred. A call
    * to `bus_on()` will need to be issued to attempt to talk on the bus again.
    * See `bus_on()` for more details.
    */
-  [[nodiscard]] result<send_t> send(const message_t& p_message)
+  send_t send(const message_t& p_message)
   {
     return driver_send(p_message);
   }
@@ -216,9 +212,9 @@ class can
   virtual ~can() = default;
 
 private:
-  virtual status driver_configure(const settings& p_settings) = 0;
-  virtual status driver_bus_on() = 0;
-  virtual result<send_t> driver_send(const message_t& p_message) = 0;
+  virtual void driver_configure(const settings& p_settings) = 0;
+  virtual void driver_bus_on() = 0;
+  virtual send_t driver_send(const message_t& p_message) = 0;
   virtual void driver_on_receive(hal::callback<handler> p_handler) = 0;
 };
 }  // namespace hal

include/libhal/dac.hpp

@@ -14,10 +14,9 @@
 
 #pragma once
 
+#include <algorithm>
 #include <cstdint>
 
-#include "error.hpp"
-
 namespace hal {
 /**
  * @brief Digital to Analog Converter (DAC) hardware abstraction interface.
@@ -58,9 +57,9 @@ class dac
    *
    * @param p_percentage - value from 0.0f to +1.0f representing the proportion
    * of the output voltage from the Vss to Vcc.
-   * @return result<write_t> - success or failure
+   * @return write_t - success or failure
    */
-  [[nodiscard]] result<write_t> write(float p_percentage)
+  write_t write(float p_percentage)
   {
     auto clamped_percentage = std::clamp(p_percentage, 0.0f, 1.0f);
     return driver_write(clamped_percentage);
@@ -69,6 +68,6 @@ class dac
   virtual ~dac() = default;
 
 private:
-  virtual result<write_t> driver_write(float p_percentage) = 0;
+  virtual write_t driver_write(float p_percentage) = 0;
 };
 }  // namespace hal

include/libhal/distance_sensor.hpp

@@ -14,7 +14,6 @@
 
 #pragma once
 
-#include "error.hpp"
 #include "units.hpp"
 
 namespace hal {
@@ -96,16 +95,16 @@ class distance_sensor
   /**
    * @brief Read the current distance measured by the device
    *
-   * @return result<read_t> - distance data
+   * @return read_t - distance data
    */
-  [[nodiscard]] result<read_t> read()
+  [[nodiscard]] read_t read()
   {
     return driver_read();
   }
 
   virtual ~distance_sensor() = default;
 
 private:
-  virtual result<read_t> driver_read() = 0;
+  virtual read_t driver_read() = 0;
 };
 }  // namespace hal

include/libhal/error.hpp

@@ -15,66 +15,26 @@
 #pragma once
 
 #include <system_error>
-
-#include <boost/leaf/detail/all.hpp>
-
-#define HAL_CHECK BOOST_LEAF_CHECK
+#include <type_traits>
 
 namespace hal {
 
-template<typename T, T... value>
-using match = boost::leaf::match<T, value...>;
-template<class T>
-using result = boost::leaf::result<T>;
-using status = result<void>;
 using error_handler = void(void);
 
 inline error_handler* on_error_callback = nullptr;
 
-/**
- * @brief a readability function for returning successful results;
- *
- * For functions that return `status`, rather than returning `{}` to default
- * initialize the status object as "success", use this function to make it more
- * clear to the reader.
- *
- * EXAMPLE:
- *
- *     hal::status some_function() {
- *        return hal::success();
- *     }
- *
- * @return status - that is always successful
- */
-inline status success()
-{
-  // Default initialize the status object using the brace initialization, which
-  // will set the status to the default "success" state.
-  status successful_status{};
-  return successful_status;
-}
-
-template<class TryBlock, class... H>
-[[nodiscard]] constexpr auto attempt(TryBlock&& p_try_block, H&&... p_handlers)
-{
-  return boost::leaf::try_handle_some(p_try_block, p_handlers...);
-}
-
-template<class TryBlock, class... H>
-[[nodiscard]] constexpr auto attempt_all(TryBlock&& p_try_block,
-                                         H&&... p_handlers)
+template<class thrown_t>
+void safe_throw(thrown_t&& p_thrown_object)
 {
-  return boost::leaf::try_handle_all(p_try_block, p_handlers...);
-}
+  static_assert(
+    std::is_trivially_destructible_v<thrown_t>,
+    "safe_throw() only works with trivially destructible thrown types");
 
-template<class... Item>
-[[nodiscard]] inline auto new_error(Item&&... p_item)
-{
   if (on_error_callback) {
     on_error_callback();
   }
 
-  return boost::leaf::new_error(std::forward<Item>(p_item)...);
+  throw p_thrown_object;
 }
 
 [[noreturn]] inline void halt()