Add sequential execution support for serial interface functions

- Introduced a new dispatch mechanism for executing serial interface functions sequentially across threads, ensuring that calls are processed in the order they are made.
- Added corresponding sequential variants for multiple serial functions, including `serialAbortRead`, `serialRead`, `serialWrite`, and others, to enhance thread safety and execution consistency.
- Updated the `serial.h` header to include the new sequential interface headers.

This update improves the robustness of the serial API by providing a clear and reliable way to handle function calls in a sequential manner.

Author: Katze719

include/cpp_core/detail/sequential_dispatch.h

@@ -0,0 +1,115 @@
+#pragma once
+
+#include <condition_variable>
+#include <functional>
+#include <future>
+#include <memory>
+#include <mutex>
+#include <queue>
+#include <thread>
+#include <type_traits>
+
+namespace cpp_core::detail::seq
+{
+
+struct DispatchState
+{
+    std::mutex                        mtx;
+    std::condition_variable           cv;
+    std::queue<std::function<void()>> queue;
+    std::once_flag                    worker_started;
+};
+
+/**
+ * @brief Access the global dispatcher state (singleton).
+ *
+ * Implements the C++11 *Meyers-Singleton* idiom: the static local variable is
+ * initialised on first use in a thread-safe manner and subsequently reused.
+ * This ensures exactly one queue / mutex / condition_variable exists per
+ * process while avoiding the static-initialisation-order problem.
+ *
+ * @return Reference to the sole ::DispatchState instance.
+ */
+inline auto state() -> DispatchState &
+{
+    static DispatchState instance;
+    return instance;
+}
+
+/**
+ * @brief Worker thread main loop.
+ *
+ * Waits for new jobs in `state().queue` and executes them sequentially.
+ * The loop never terminates, the thread lives for the entire lifetime of
+ * the process.
+ */
+inline void worker()
+{
+    for (;;)
+    {
+        std::function<void()> job;
+        {
+            std::unique_lock<std::mutex> lock(state().mtx);
+            state().cv.wait(lock, [] { return !state().queue.empty(); });
+            job = std::move(state().queue.front());
+            state().queue.pop();
+        }
+        job();
+    }
+}
+
+/**
+ * @brief Starts the background worker thread (called once).
+ *
+ * Invoked internally by ::call via `std::call_once`. On the first invocation a
+ * detached thread is spawned; subsequent calls are no-ops.
+ */
+inline void startWorker()
+{
+    std::thread(worker).detach();
+}
+
+/**
+ * @brief Execute a callable sequentially on the background thread.
+ *
+ * The function/lambda is enqueued in FIFO order. The calling thread then
+ * blocks until completion and returns the result (or propagates an exception).
+ *
+ * Steps:
+ * 1. Wrap the callable in `std::packaged_task` to obtain an associated
+ *    `std::future`.
+ * 2. Ensure the worker thread is running (`std::call_once`).
+ * 3. Push a copyable thunk into the queue and wake the worker via
+ *    `notify_one()`.
+ * 4. Wait on `future.get()` for completion and forward the return value.
+ *
+ * @tparam FunctionT Callable type with no parameters.
+ * @param  function  Function object to be executed sequentially.
+ * @return           The callable's return value (or `void`).
+ */
+template <typename FunctionT> auto call(FunctionT &&function) -> decltype(function())
+{
+    using FunctionReturnT = decltype(function());
+
+    auto task_ptr = std::make_shared<std::packaged_task<FunctionReturnT()>>(std::forward<FunctionT>(function));
+    auto future   = task_ptr->get_future();
+
+    std::call_once(state().worker_started, startWorker);
+
+    {
+        std::lock_guard<std::mutex> lock(state().mtx);
+        state().queue.emplace([task_ptr]() { (*task_ptr)(); });
+    }
+    state().cv.notify_one();
+
+    if constexpr (std::is_void_v<FunctionReturnT>)
+    {
+        future.get();
+    }
+    else
+    {
+        return future.get();
+    }
+}
+
+} // namespace cpp_core::detail::seq

include/cpp_core/interface/sequential/all.h

@@ -0,0 +1,24 @@
+#pragma once
+
+// Aggregates all *Sequential headers
+#include "get_version_sequential.h"
+#include "serial_abort_read_sequential.h"
+#include "serial_abort_write_sequential.h"
+#include "serial_clear_buffer_in_sequential.h"
+#include "serial_clear_buffer_out_sequential.h"
+#include "serial_close_sequential.h"
+#include "serial_drain_sequential.h"
+#include "serial_get_ports_info_sequential.h"
+#include "serial_in_bytes_total_sequential.h"
+#include "serial_in_bytes_waiting_sequential.h"
+#include "serial_open_sequential.h"
+#include "serial_out_bytes_total_sequential.h"
+#include "serial_out_bytes_waiting_sequential.h"
+#include "serial_read_line_sequential.h"
+#include "serial_read_sequential.h"
+#include "serial_read_until_sequence_sequential.h"
+#include "serial_read_until_sequential.h"
+#include "serial_set_error_callback_sequential.h"
+#include "serial_set_read_callback_sequential.h"
+#include "serial_set_write_callback_sequential.h"
+#include "serial_write_sequential.h"

include/cpp_core/interface/sequential/get_version_sequential.h

@@ -0,0 +1,23 @@
+#pragma once
+
+#include "../../detail/sequential_dispatch.h"
+#include "../../version.h"
+#include "../get_version.h"
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif
+
+    /**
+     * @copydoc getVersion
+     * @note Sequential variant: call executes strictly in the order it was enqueued across threads.
+     */
+    inline MODULE_API void getVersionSequential(cpp_core::Version *out)
+    {
+        cpp_core::detail::seq::call([=] { getVersion(out); });
+    }
+
+#ifdef __cplusplus
+}
+#endif

include/cpp_core/interface/sequential/serial_abort_read_sequential.h

@@ -0,0 +1,26 @@
+#pragma once
+
+#include "../../detail/sequential_dispatch.h"
+#include "../../error_callback.h"
+#include "../serial_abort_read.h"
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif
+
+    /**
+     * @copydoc serialAbortRead
+     * @note Sequential variant: guarantees execution in the exact order the calls were made across threads.
+     */
+    inline MODULE_API auto serialAbortReadSequential(
+        int64_t        handle,
+        ErrorCallbackT error_callback = nullptr
+    ) -> int
+    {
+        return cpp_core::detail::seq::call([=] { return serialAbortRead(handle, error_callback); });
+    }
+
+#ifdef __cplusplus
+}
+#endif

include/cpp_core/interface/sequential/serial_abort_write_sequential.h

@@ -0,0 +1,26 @@
+#pragma once
+
+#include "../../detail/sequential_dispatch.h"
+#include "../../error_callback.h"
+#include "../serial_abort_write.h"
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif
+
+    /**
+     * @copydoc serialAbortWrite
+     * @note Sequential variant: guarantees execution in the exact order the calls were made across threads.
+     */
+    inline MODULE_API auto serialAbortWriteSequential(
+        int64_t        handle,
+        ErrorCallbackT error_callback = nullptr
+    ) -> int
+    {
+        return cpp_core::detail::seq::call([=] { return serialAbortWrite(handle, error_callback); });
+    }
+
+#ifdef __cplusplus
+}
+#endif

include/cpp_core/interface/sequential/serial_clear_buffer_in_sequential.h

@@ -0,0 +1,26 @@
+#pragma once
+
+#include "../../detail/sequential_dispatch.h"
+#include "../../error_callback.h"
+#include "../serial_clear_buffer_in.h"
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif
+
+    /**
+     * @copydoc serialClearBufferIn
+     * @note Sequential variant: guarantees execution in the exact order the calls were made across threads.
+     */
+    inline MODULE_API auto serialClearBufferInSequential(
+        int64_t        handle,
+        ErrorCallbackT error_callback = nullptr
+    ) -> int
+    {
+        return cpp_core::detail::seq::call([=] { return serialClearBufferIn(handle, error_callback); });
+    }
+
+#ifdef __cplusplus
+}
+#endif

include/cpp_core/interface/sequential/serial_clear_buffer_out_sequential.h

@@ -0,0 +1,26 @@
+#pragma once
+
+#include "../../detail/sequential_dispatch.h"
+#include "../../error_callback.h"
+#include "../serial_clear_buffer_out.h"
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif
+
+    /**
+     * @copydoc serialClearBufferOut
+     * @note Sequential variant: guarantees execution in the exact order the calls were made across threads.
+     */
+    inline MODULE_API auto serialClearBufferOutSequential(
+        int64_t        handle,
+        ErrorCallbackT error_callback = nullptr
+    ) -> int
+    {
+        return cpp_core::detail::seq::call([=] { return serialClearBufferOut(handle, error_callback); });
+    }
+
+#ifdef __cplusplus
+}
+#endif

include/cpp_core/interface/sequential/serial_close_sequential.h

@@ -0,0 +1,26 @@
+#pragma once
+
+#include "../../detail/sequential_dispatch.h"
+#include "../../error_callback.h"
+#include "../serial_close.h"
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif
+
+    /**
+     * @copydoc serialClose
+     * @note Sequential variant: guarantees execution in the exact order the calls were made across threads.
+     */
+    inline MODULE_API auto serialCloseSequential(
+        int64_t        handle,
+        ErrorCallbackT error_callback = nullptr
+    ) -> int
+    {
+        return cpp_core::detail::seq::call([=] { return serialClose(handle, error_callback); });
+    }
+
+#ifdef __cplusplus
+}
+#endif

include/cpp_core/interface/sequential/serial_drain_sequential.h

@@ -0,0 +1,26 @@
+#pragma once
+
+#include "../../detail/sequential_dispatch.h"
+#include "../../error_callback.h"
+#include "../serial_drain.h"
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif
+
+    /**
+     * @copydoc serialDrain
+     * @note Sequential variant: guarantees execution in the exact order the calls were made across threads.
+     */
+    inline MODULE_API auto serialDrainSequential(
+        int64_t        handle,
+        ErrorCallbackT error_callback = nullptr
+    ) -> int
+    {
+        return cpp_core::detail::seq::call([=] { return serialDrain(handle, error_callback); });
+    }
+
+#ifdef __cplusplus
+}
+#endif

include/cpp_core/interface/sequential/serial_get_ports_info_sequential.h

@@ -0,0 +1,35 @@
+#pragma once
+
+#include "../../detail/sequential_dispatch.h"
+#include "../../error_callback.h"
+#include "../serial_get_ports_info.h"
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif
+
+    /**
+     * @copydoc serialGetPortsInfo
+     * @note Sequential variant: guarantees execution in the exact order the calls were made across threads.
+     */
+    inline MODULE_API auto serialGetPortsInfoSequential(
+        void (*callback_fn)(
+            const char *port,
+            const char *path,
+            const char *manufacturer,
+            const char *serial_number,
+            const char *pnp_id,
+            const char *location_id,
+            const char *product_id,
+            const char *vendor_id
+        ),
+        ErrorCallbackT error_callback = nullptr
+    ) -> int
+    {
+        return cpp_core::detail::seq::call([=] { return serialGetPortsInfo(callback_fn, error_callback); });
+    }
+
+#ifdef __cplusplus
+}
+#endif