Document APIs

Author: Dmitry Malakhov

README.md

@@ -14,6 +14,10 @@ Returning to main loop is not possible if a signal was raised by your implementa
 
 And as any IO operation, this is faster and fancier when you do it asynchronously.
 
+## Accessing documentation
+
+This project uses doxygen for documenting it's APIs. You can read docs in source code or read an index generated by `xmake doxygen` command. There is no remote docs index currently
+
 ## Brief API overview
 
 Library is within it's very early stage of development and interfaces may change in future

devenv.nix

@@ -3,7 +3,7 @@
   packages = with pkgs; [
     llvmPackages_21.clang-tools
     llvmPackages_19.libstdcxxClang
-
+    doxygen
     xmake
     gdb
   ];

doxyfile

@@ -25,11 +25,17 @@ concept NotReactor = !std::same_as<Reactor, T>;
 
 template <typename T, typename E>
 struct CoroutinePromiseType : CoroListNode {
-
+  /// @brief Construct new coroutine promise bound to reactor
+  /// @note For more detailed explanation check
+  ///        https://en.cppreference.com/w/cpp/language/coroutines.html
   CoroutinePromiseType(Reactor &reactor, NotReactor auto const &...) noexcept
       : m_reactor{reactor} {
   }
 
+  /// @brief Construct new coroutine promise bound to reactor. This overload is used when some
+  ///         object's method is declared as coroutine
+  /// @note For more detailed explanation check
+  ///        https://en.cppreference.com/w/cpp/language/coroutines.html
   CoroutinePromiseType(NotReactor auto const &,
                        Reactor &reactor,
                        NotReactor auto const &...) noexcept
@@ -43,41 +49,63 @@ struct CoroutinePromiseType : CoroListNode {
 
   ~CoroutinePromiseType() override = default;
 
+  /// @brief Allocate new coroutine frame using allocator from reactor
+  /// @note C++20 coroutine's required method. For more detailed explanation check
+  ///        https://en.cppreference.com/w/cpp/language/coroutines.html
   static void *operator new(size_t n, Reactor &reactor, NotReactor auto const &...) noexcept {
     return reactor.allocator().allocate(n);
   }
 
+  /// @brief Allocate new coroutine frame using allocator from reactor. This overload is used when
+  ///         some object's method is declared as coroutine
+  /// @note C++20 coroutine's required method. For more detailed explanation check
+  ///        https://en.cppreference.com/w/cpp/language/coroutines.html
   static void *operator new(size_t n,
                             NotReactor auto const &,
                             Reactor &reactor,
                             NotReactor auto const &...) noexcept {
     return reactor.allocator().allocate(n);
   }
 
+  /// @brief Noop
+  /// @note C++20 coroutine's required method. For more detailed explanation check
+  ///        https://en.cppreference.com/w/cpp/language/coroutines.html
   static void operator delete(void *) noexcept {
     // nothing to do in here since reactor is not accessible. instead, a coro frame is released when
     // future is destroyed
   }
 
+  /// @brief Add this as a CoroListNode into reactor to be executed later
   void yield_to_reactor() noexcept {
-    m_reactor.yield(*this);
+    m_reactor.schedule(*this);
   }
 
+  /// @brief Add this PollListNode into reactor to be executed later, when event becomes awailable
   void poll_to_reactor(PollListNode &node) noexcept {
-    m_reactor.poll(node);
+    m_reactor.schedule_when_ready(node);
   }
 
+  /// @brief Call an abort. Corosig expects no exceptions to be thrown around since they are not
+  ///         safe to throw in sighandlers.
+  /// @note C++20 coroutine's required method. For more detailed explanation check
+  ///        https://en.cppreference.com/w/cpp/language/coroutines.html
   [[noreturn]] static void unhandled_exception() noexcept {
     std::abort();
   }
 
+  /// @note C++20 coroutine's required method. For more detailed explanation check
+  ///        https://en.cppreference.com/w/cpp/language/coroutines.html
   Fut<T, E> get_return_object() noexcept;
   static Fut<T, E> get_return_object_on_allocation_failure() noexcept;
 
+  /// @note C++20 coroutine's required method. For more detailed explanation check
+  ///        https://en.cppreference.com/w/cpp/language/coroutines.html
   auto initial_suspend() noexcept {
     return std::suspend_never{};
   }
 
+  /// @note C++20 coroutine's required method. For more detailed explanation check
+  ///        https://en.cppreference.com/w/cpp/language/coroutines.html
   auto final_suspend() noexcept {
     struct ReturnControlToCaller {
       static bool await_ready() noexcept {
@@ -96,6 +124,9 @@ struct CoroutinePromiseType : CoroListNode {
     return ReturnControlToCaller{};
   }
 
+  /// @brief Return a value form coroutine
+  /// @note C++20 coroutine's required method. For more detailed explanation check
+  ///        https://en.cppreference.com/w/cpp/language/coroutines.html
   template <std::convertible_to<Result<T, E>> U>
   void return_value(U &&value) noexcept {
     assert(m_value.is_nothing());
@@ -117,8 +148,11 @@ struct CoroutinePromiseType : CoroListNode {
 
 } // namespace detail
 
+/// @brief A result, which will become available in the future
 template <typename T = void, typename E = AllocationError>
 struct [[nodiscard("forgot to await?")]] Fut {
+  /// @note C++20 coroutine's required typedef. For more detailed explanation check
+  ///        https://en.cppreference.com/w/cpp/language/coroutines.html
   using promise_type = detail::CoroutinePromiseType<T, E>;
 
   Fut(const Fut &) = delete;
@@ -134,10 +168,13 @@ struct [[nodiscard("forgot to await?")]] Fut {
     }
   }
 
+  /// @brief Tell if future is already available. General-purpose code shall not use this method
+  ///         and just simply co_await a future
   [[nodiscard]] bool completed() const noexcept {
     return m_handle.value == nullptr || !promise().m_value.is_nothing();
   }
 
+  /// @brief Run reactor's event loop until this future is ready
   Result<T, extend_error<E, SyscallError>> block_on() && noexcept {
     while (!completed()) {
       COROSIG_TRYV(promise().m_reactor.do_event_loop_iteration());
@@ -148,39 +185,40 @@ struct [[nodiscard("forgot to await?")]] Fut {
     return std::move(promise().m_value);
   }
 
-  struct Awaiter {
-    Awaiter(const Awaiter &) = delete;
-    Awaiter(Awaiter &&) = delete;
-    Awaiter &operator=(const Awaiter &) = delete;
-    Awaiter &operator=(Awaiter &&) = delete;
-
-    [[nodiscard]] bool await_ready() const noexcept {
-      return m_future.completed();
-    }
+  /// @brief Await for result inside this future to become available
+  auto operator co_await() && noexcept {
+    struct Awaiter {
+      Awaiter(const Awaiter &) = delete;
+      Awaiter(Awaiter &&) = delete;
+      Awaiter &operator=(const Awaiter &) = delete;
+      Awaiter &operator=(Awaiter &&) = delete;
 
-    void await_suspend(std::coroutine_handle<> h) const noexcept {
-      m_future.promise().m_waiting_coro = h;
-    }
+      [[nodiscard]] bool await_ready() const noexcept {
+        return m_future.completed();
+      }
 
-    Result<T, E> await_resume() const noexcept {
-      if (m_future.m_handle.value == nullptr) {
-        return Failure{AllocationError{}};
+      void await_suspend(std::coroutine_handle<> h) const noexcept {
+        m_future.promise().m_waiting_coro = h;
       }
 
-      assert(!m_future.promise().m_value.is_nothing());
-      return std::move(m_future.promise().m_value);
-    }
+      Result<T, E> await_resume() const noexcept {
+        if (m_future.m_handle.value == nullptr) {
+          return Failure{AllocationError{}};
+        }
 
-  private:
-    friend Fut;
-    Awaiter(Fut &future) noexcept
-        : m_future{future} {
-    }
+        assert(!m_future.promise().m_value.is_nothing());
+        return std::move(m_future.promise().m_value);
+      }
 
-    Fut &m_future;
-  };
+    private:
+      friend Fut;
+      Awaiter(Fut &future) noexcept
+          : m_future{future} {
+      }
+
+      Fut &m_future;
+    };
 
-  Awaiter operator co_await() && noexcept {
     return Awaiter{*this};
   }
 

include/corosig/Coro.hpp

@@ -25,6 +25,7 @@ concept WithDescription = requires(E const &e) {
 
 } // namespace detail
 
+/// @brief An error which contains one of specified errors inside
 template <typename... TYPES>
 struct Error : std::variant<TYPES...> {
 private:
@@ -38,29 +39,36 @@ struct Error : std::variant<TYPES...> {
 public:
   using Base::Base;
 
+  /// @brief Return an error description. If an underlying error has method .description, it's
+  ///        result is returned. Otherwise, it's typename is returned
   [[nodiscard]] std::string_view description() const noexcept {
     return visit(Overloaded{
         [](detail::WithDescription auto const &e) { return e.description(); },
         [](auto const &e) { return std::string_view{typeid(std::decay_t<decltype(e)>).name()}; },
     });
   }
 
+  /// @brief Tell if an error holds a type T inside
   template <typename T>
   [[nodiscard]] bool holds() const noexcept {
     return std::holds_alternative<T>(*this);
   }
 
+  /// @brief Visit all possible errors inside using f as visitor
   template <typename F>
   [[nodiscard]] decltype(auto) visit(F &&f) noexcept {
     return std::visit(std::forward<F>(f), *this);
   }
 
+  /// @brief Visit all possible errors inside using f as visitor
   template <typename F>
   [[nodiscard]] decltype(auto) visit(F &&f) const noexcept {
     return std::visit(std::forward<F>(f), *this);
   }
 };
 
+/// @brief An error type that represents that there is no error. Used only for metaprogramming. Any
+///         usage in potentially evaluated context makes program ill-formed
 struct NoError;
 
 namespace detail {
@@ -94,25 +102,28 @@ using extend_error =
 
 } // namespace detail
 
+/// @brief Extend Error type with other options. If E is Error, it's underlying types are used for
+///         extension, otherwise E itself is used. Any duplicates in the list are automatically
+///         removed to form a list of unique options
 template <typename... E>
 using extend_error =
     boost::mp11::mp_fold<boost::mp11::mp_list<E...>, Error<>, detail::extend_error>;
 
-template <typename... E>
-using extend_error =
-    boost::mp11::mp_fold<boost::mp11::mp_list<E...>, Error<>, detail::extend_error>;
-
+/// @brief Get an error type which may be returned by functor CALLABLE when called with ARGS
 template <auto CALLABLE, typename... ARGS>
 using error_type = std::decay_t<
     decltype(std::declval<std::invoke_result_t<decltype(CALLABLE), ARGS...>>().error())>;
 
+/// @brief An allocation error. Does it really need a description?
 struct AllocationError {
   auto operator<=>(const AllocationError &) const noexcept = default;
 };
 
+/// @brief An error, propagated from a syscall
 struct SyscallError {
   auto operator<=>(const SyscallError &) const noexcept = default;
 
+  /// @brief Get current syscall error. In POSIX this function copies an errno into value
   static SyscallError current() noexcept;
 
   [[nodiscard]] std::string_view description() const noexcept;

include/corosig/ErrorTypes.hpp

@@ -15,6 +15,7 @@
 
 namespace corosig {
 
+/// @brief Wait when all futures are ready. Return all of their results
 template <typename... R, typename... E>
 Fut<std::tuple<Result<R, E>...>> when_all(Reactor &, Fut<R, E> &&...futs) noexcept {
   co_return std::tuple{co_await std::move(futs)...};
@@ -44,6 +45,8 @@ using WrapVoid = std::conditional_t<std::same_as<void, T>, std::monostate, T>;
 
 } // namespace detail
 
+/// @brief Wait when all futures are ready. Return all of values from their results or the first
+///         error that occurred among them
 template <typename... R, typename... E>
 Fut<std::tuple<detail::WrapVoid<R>...>, extend_error<E...>>
 when_all_succeed(Reactor &, Fut<R, E> &&...futs) noexcept {

include/corosig/Parallel.hpp

@@ -11,6 +11,8 @@
 
 namespace corosig {
 
+/// @brief Await for event to occur for handle
+/// @note Event is only actually polled when this struct is co_awaited
 struct PollEvent : PollListNode {
   PollEvent(os::Handle handle, poll_event_e event) {
     this->handle = handle;