Diff coverage report for

//

//

// Copyright (c) 2025 Vinnie Falco (vinnie dot falco at gmail dot com)

// Copyright (c) 2025 Vinnie Falco (vinnie dot falco at gmail dot com)

//

//

// Distributed under the Boost Software License, Version 1.0. (See accompanying

// Distributed under the Boost Software License, Version 1.0. (See accompanying

// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

//

//

// Official repository: https://github.com/cppalliance/corosio

// Official repository: https://github.com/cppalliance/corosio

//

//

#ifndef BOOST_COROSIO_SIGNAL_SET_HPP

#ifndef BOOST_COROSIO_SIGNAL_SET_HPP

#define BOOST_COROSIO_SIGNAL_SET_HPP

#define BOOST_COROSIO_SIGNAL_SET_HPP

#include <boost/corosio/detail/config.hpp>

#include <boost/corosio/detail/config.hpp>

#include <boost/corosio/detail/except.hpp>

#include <boost/corosio/detail/except.hpp>

#include <boost/corosio/io_object.hpp>

#include <boost/corosio/io_object.hpp>

#include <boost/capy/io_result.hpp>

#include <boost/capy/io_result.hpp>

#include <boost/capy/error.hpp>

#include <boost/capy/error.hpp>

#include <boost/capy/ex/executor_ref.hpp>

#include <boost/capy/ex/executor_ref.hpp>

#include <boost/capy/ex/execution_context.hpp>

#include <boost/capy/ex/execution_context.hpp>

#include <boost/capy/concept/executor.hpp>

#include <boost/capy/concept/executor.hpp>

#include <system_error>

#include <system_error>

#include <concepts>

#include <concepts>

#include <coroutine>

#include <coroutine>

#include <stop_token>

#include <stop_token>

#include <system_error>

#include <system_error>

/*

/*

    Signal Set Public API

    Signal Set Public API

    =====================

    =====================

    This header provides the public interface for asynchronous signal handling.

    This header provides the public interface for asynchronous signal handling.

    The implementation is split across platform-specific files:

    The implementation is split across platform-specific files:

      - posix/signals.cpp: Uses sigaction() for robust signal handling

      - posix/signals.cpp: Uses sigaction() for robust signal handling

      - iocp/signals.cpp: Uses C runtime signal() (Windows lacks sigaction)

      - iocp/signals.cpp: Uses C runtime signal() (Windows lacks sigaction)

    Key design decisions:

    Key design decisions:

    1. Abstract flag values: The flags_t enum uses arbitrary bit positions

    1. Abstract flag values: The flags_t enum uses arbitrary bit positions

       (not SA_RESTART, etc.) to avoid including <signal.h> in public headers.

       (not SA_RESTART, etc.) to avoid including <signal.h> in public headers.

       The POSIX implementation maps these to actual SA_* constants internally.

       The POSIX implementation maps these to actual SA_* constants internally.

    2. Flag conflict detection: When multiple signal_sets register for the

    2. Flag conflict detection: When multiple signal_sets register for the

       same signal, they must use compatible flags. The first registration

       same signal, they must use compatible flags. The first registration

       establishes the flags; subsequent registrations must match or use

       establishes the flags; subsequent registrations must match or use

       dont_care.

       dont_care.

    3. Polymorphic implementation: signal_set_impl is an abstract base that

    3. Polymorphic implementation: signal_set_impl is an abstract base that

       platform-specific implementations (posix_signal_impl, win_signal_impl)

       platform-specific implementations (posix_signal_impl, win_signal_impl)

       derive from. This allows the public API to be platform-agnostic.

       derive from. This allows the public API to be platform-agnostic.

    4. The inline add(int) overload avoids a virtual call for the common case

    4. The inline add(int) overload avoids a virtual call for the common case

       of adding signals without flags (delegates to add(int, none)).

       of adding signals without flags (delegates to add(int, none)).

*/

*/

namespace boost::corosio {

namespace boost::corosio {

/** An asynchronous signal set for coroutine I/O.

/** An asynchronous signal set for coroutine I/O.

    This class provides the ability to perform an asynchronous wait

    This class provides the ability to perform an asynchronous wait

    for one or more signals to occur. The signal set registers for

    for one or more signals to occur. The signal set registers for

    signals using sigaction() on POSIX systems or the C runtime

    signals using sigaction() on POSIX systems or the C runtime

    signal() function on Windows.

    signal() function on Windows.

    @par Thread Safety

    @par Thread Safety

    Distinct objects: Safe.@n

    Distinct objects: Safe.@n

    Shared objects: Unsafe. A signal_set must not have concurrent

    Shared objects: Unsafe. A signal_set must not have concurrent

    wait operations.

    wait operations.

    @par Semantics

    @par Semantics

    Wraps platform signal handling (sigaction on POSIX, C runtime

    Wraps platform signal handling (sigaction on POSIX, C runtime

    signal() on Windows). Operations dispatch to OS signal APIs

    signal() on Windows). Operations dispatch to OS signal APIs

    via the io_context reactor.

    via the io_context reactor.

    @par Supported Signals

    @par Supported Signals

    On Windows, the following signals are supported:

    On Windows, the following signals are supported:

    SIGINT, SIGTERM, SIGABRT, SIGFPE, SIGILL, SIGSEGV.

    SIGINT, SIGTERM, SIGABRT, SIGFPE, SIGILL, SIGSEGV.

    @par Example

    @par Example

    @code

    @code

    signal_set signals(ctx, SIGINT, SIGTERM);

    signal_set signals(ctx, SIGINT, SIGTERM);

    auto [ec, signum] = co_await signals.wait();

    auto [ec, signum] = co_await signals.wait();

    if (ec == capy::cond::canceled)

    if (ec == capy::cond::canceled)

    {

    {

        // Operation was cancelled via stop_token or cancel()

        // Operation was cancelled via stop_token or cancel()

    }

    }

    else if (!ec)

    else if (!ec)

    {

    {

        std::cout << "Received signal " << signum << std::endl;

        std::cout << "Received signal " << signum << std::endl;

    }

    }

    @endcode

    @endcode

*/

*/

class BOOST_COROSIO_DECL signal_set : public io_object

class BOOST_COROSIO_DECL signal_set : public io_object

{

{

public:

public:

    /** Flags for signal registration.

    /** Flags for signal registration.

        These flags control the behavior of signal handling. Multiple

        These flags control the behavior of signal handling. Multiple

        flags can be combined using the bitwise OR operator.

        flags can be combined using the bitwise OR operator.

        @note Flags only have effect on POSIX systems. On Windows,

        @note Flags only have effect on POSIX systems. On Windows,

        only `none` and `dont_care` are supported; other flags return

        only `none` and `dont_care` are supported; other flags return

        `operation_not_supported`.

        `operation_not_supported`.

    */

    */

    enum flags_t : unsigned

    enum flags_t : unsigned

    {

    {

        /// Use existing flags if signal is already registered.

        /// Use existing flags if signal is already registered.

        /// When adding a signal that's already registered by another

        /// When adding a signal that's already registered by another

        /// signal_set, this flag indicates acceptance of whatever

        /// signal_set, this flag indicates acceptance of whatever

        /// flags were used for the existing registration.

        /// flags were used for the existing registration.

        dont_care = 1u << 16,

        dont_care = 1u << 16,

        /// No special flags.

        /// No special flags.

        none = 0,

        none = 0,

        /// Restart interrupted system calls.

        /// Restart interrupted system calls.

        /// Equivalent to SA_RESTART on POSIX systems.

        /// Equivalent to SA_RESTART on POSIX systems.

        restart = 1u << 0,

        restart = 1u << 0,

        /// Don't generate SIGCHLD when children stop.

        /// Don't generate SIGCHLD when children stop.

        /// Equivalent to SA_NOCLDSTOP on POSIX systems.

        /// Equivalent to SA_NOCLDSTOP on POSIX systems.

        no_child_stop = 1u << 1,

        no_child_stop = 1u << 1,

        /// Don't create zombie processes on child termination.

        /// Don't create zombie processes on child termination.

        /// Equivalent to SA_NOCLDWAIT on POSIX systems.

        /// Equivalent to SA_NOCLDWAIT on POSIX systems.

        no_child_wait = 1u << 2,

        no_child_wait = 1u << 2,

        /// Don't block the signal while its handler runs.

        /// Don't block the signal while its handler runs.

        /// Equivalent to SA_NODEFER on POSIX systems.

        /// Equivalent to SA_NODEFER on POSIX systems.

        no_defer = 1u << 3,

        no_defer = 1u << 3,

        /// Reset handler to SIG_DFL after one invocation.

        /// Reset handler to SIG_DFL after one invocation.

        /// Equivalent to SA_RESETHAND on POSIX systems.

        /// Equivalent to SA_RESETHAND on POSIX systems.

        reset_handler = 1u << 4

        reset_handler = 1u << 4

    };

    };

    /// Combine two flag values.

    /// Combine two flag values.

    {

    {

        return static_cast<flags_t>(

        return static_cast<flags_t>(

    }

    }

    /// Mask two flag values.

    /// Mask two flag values.

    {

    {

        return static_cast<flags_t>(

        return static_cast<flags_t>(

    }

    }

    /// Compound assignment OR.

    /// Compound assignment OR.

    {

    {

    }

    }

    /// Compound assignment AND.

    /// Compound assignment AND.

    friend constexpr flags_t& operator&=(flags_t& a, flags_t b) noexcept

    friend constexpr flags_t& operator&=(flags_t& a, flags_t b) noexcept

    {

    {

        return a = a & b;

        return a = a & b;

    }

    }

    /// Bitwise NOT (complement).

    /// Bitwise NOT (complement).

    friend constexpr flags_t operator~(flags_t a) noexcept

    friend constexpr flags_t operator~(flags_t a) noexcept

    {

    {

        return static_cast<flags_t>(~static_cast<unsigned>(a));

        return static_cast<flags_t>(~static_cast<unsigned>(a));

    }

    }

private:

private:

    struct wait_awaitable

    struct wait_awaitable

    {

    {

        signal_set& s_;

        signal_set& s_;

        std::stop_token token_;

        std::stop_token token_;

        mutable std::error_code ec_;

        mutable std::error_code ec_;

        mutable int signal_number_ = 0;

        mutable int signal_number_ = 0;

        {

        {

        }

        }

        {

        {

        }

        }

        template<typename Ex>

        template<typename Ex>

            std::coroutine_handle<> h,

            std::coroutine_handle<> h,

            Ex const& ex,

            Ex const& ex,

            std::stop_token token) -> std::coroutine_handle<>

            std::stop_token token) -> std::coroutine_handle<>

        {

        {

        }

        }

    };

    };

public:

public:

    struct signal_set_impl : io_object_impl

    struct signal_set_impl : io_object_impl

    {

    {

        virtual void wait(

        virtual void wait(

            std::coroutine_handle<>,

            std::coroutine_handle<>,

            capy::executor_ref,

            capy::executor_ref,

            std::stop_token,

            std::stop_token,

            std::error_code*,

            std::error_code*,

            int*) = 0;

            int*) = 0;

        virtual std::error_code add(int signal_number, flags_t flags) = 0;

        virtual std::error_code add(int signal_number, flags_t flags) = 0;

        virtual std::error_code remove(int signal_number) = 0;

        virtual std::error_code remove(int signal_number) = 0;

        virtual std::error_code clear() = 0;

        virtual std::error_code clear() = 0;

        virtual void cancel() = 0;

        virtual void cancel() = 0;

    };

    };

    /** Destructor.

    /** Destructor.

        Cancels any pending operations and releases signal resources.

        Cancels any pending operations and releases signal resources.

    */

    */

    ~signal_set();

    ~signal_set();

    /** Construct an empty signal set.

    /** Construct an empty signal set.

        @param ctx The execution context that will own this signal set.

        @param ctx The execution context that will own this signal set.

    */

    */

    explicit signal_set(capy::execution_context& ctx);

    explicit signal_set(capy::execution_context& ctx);

    /** Construct a signal set with initial signals.

    /** Construct a signal set with initial signals.

        @param ctx The execution context that will own this signal set.

        @param ctx The execution context that will own this signal set.

        @param signal First signal number to add.

        @param signal First signal number to add.

        @param signals Additional signal numbers to add.

        @param signals Additional signal numbers to add.

        @throws std::system_error Thrown on failure.

        @throws std::system_error Thrown on failure.

    */

    */

    template<std::convertible_to<int>... Signals>

    template<std::convertible_to<int>... Signals>

        capy::execution_context& ctx,

        capy::execution_context& ctx,

        int signal,

        int signal,

        Signals... signals)

        Signals... signals)

    {

    {

        };

        };

    /** Move constructor.

    /** Move constructor.

        Transfers ownership of the signal set resources.

        Transfers ownership of the signal set resources.

        @param other The signal set to move from.

        @param other The signal set to move from.

    */

    */

    signal_set(signal_set&& other) noexcept;

    signal_set(signal_set&& other) noexcept;

    /** Move assignment operator.

    /** Move assignment operator.

        Closes any existing signal set and transfers ownership.

        Closes any existing signal set and transfers ownership.

        The source and destination must share the same execution context.

        The source and destination must share the same execution context.

        @param other The signal set to move from.

        @param other The signal set to move from.

        @return Reference to this signal set.

        @return Reference to this signal set.

        @throws std::logic_error if the signal sets have different

        @throws std::logic_error if the signal sets have different

            execution contexts.

            execution contexts.

    */

    */

    signal_set& operator=(signal_set&& other);

    signal_set& operator=(signal_set&& other);

    signal_set(signal_set const&) = delete;

    signal_set(signal_set const&) = delete;

    signal_set& operator=(signal_set const&) = delete;

    signal_set& operator=(signal_set const&) = delete;

    /** Add a signal to the signal set.

    /** Add a signal to the signal set.

        This function adds the specified signal to the set with the

        This function adds the specified signal to the set with the

        specified flags. It has no effect if the signal is already

        specified flags. It has no effect if the signal is already

        in the set with the same flags.

        in the set with the same flags.

        If the signal is already registered globally (by another

        If the signal is already registered globally (by another

        signal_set) and the flags differ, an error is returned

        signal_set) and the flags differ, an error is returned

        unless one of them has the `dont_care` flag.

        unless one of them has the `dont_care` flag.

        @param signal_number The signal to be added to the set.

        @param signal_number The signal to be added to the set.

        @param flags The flags to apply when registering the signal.

        @param flags The flags to apply when registering the signal.

            On POSIX systems, these map to sigaction() flags.

            On POSIX systems, these map to sigaction() flags.

            On Windows, flags are accepted but ignored.

            On Windows, flags are accepted but ignored.

        @return Success, or an error if the signal could not be added.

        @return Success, or an error if the signal could not be added.

            Returns `errc::invalid_argument` if the signal is already

            Returns `errc::invalid_argument` if the signal is already

            registered with different flags.

            registered with different flags.

    */

    */

    std::error_code add(int signal_number, flags_t flags);

    std::error_code add(int signal_number, flags_t flags);

    /** Add a signal to the signal set with default flags.

    /** Add a signal to the signal set with default flags.

        This is equivalent to calling `add(signal_number, none)`.

        This is equivalent to calling `add(signal_number, none)`.

        @param signal_number The signal to be added to the set.

        @param signal_number The signal to be added to the set.

        @return Success, or an error if the signal could not be added.

        @return Success, or an error if the signal could not be added.

    */

    */

    {

    {

    }

    }

    /** Remove a signal from the signal set.

    /** Remove a signal from the signal set.

        This function removes the specified signal from the set. It has

        This function removes the specified signal from the set. It has

        no effect if the signal is not in the set.

        no effect if the signal is not in the set.

        @param signal_number The signal to be removed from the set.

        @param signal_number The signal to be removed from the set.

        @return Success, or an error if the signal could not be removed.

        @return Success, or an error if the signal could not be removed.

    */

    */

    std::error_code remove(int signal_number);

    std::error_code remove(int signal_number);

    /** Remove all signals from the signal set.

    /** Remove all signals from the signal set.

        This function removes all signals from the set. It has no effect

        This function removes all signals from the set. It has no effect

        if the set is already empty.

        if the set is already empty.

        @return Success, or an error if resetting any signal handler fails.

        @return Success, or an error if resetting any signal handler fails.

    */

    */

    std::error_code clear();

    std::error_code clear();

    /** Cancel all operations associated with the signal set.

    /** Cancel all operations associated with the signal set.

        This function forces the completion of any pending asynchronous

        This function forces the completion of any pending asynchronous

        wait operations against the signal set. The handler for each

        wait operations against the signal set. The handler for each

        cancelled operation will be invoked with an error code that

        cancelled operation will be invoked with an error code that

        compares equal to `capy::cond::canceled`.

        compares equal to `capy::cond::canceled`.

        Cancellation does not alter the set of registered signals.

        Cancellation does not alter the set of registered signals.

    */

    */

    void cancel();

    void cancel();

    /** Wait for a signal to be delivered.

    /** Wait for a signal to be delivered.

        The operation supports cancellation via `std::stop_token` through

        The operation supports cancellation via `std::stop_token` through

        the affine awaitable protocol. If the associated stop token is

        the affine awaitable protocol. If the associated stop token is

        triggered, the operation completes immediately with an error

        triggered, the operation completes immediately with an error

        that compares equal to `capy::cond::canceled`.

        that compares equal to `capy::cond::canceled`.

        @par Example

        @par Example

        @code

        @code

        signal_set signals(ctx, SIGINT);

        signal_set signals(ctx, SIGINT);

        auto [ec, signum] = co_await signals.wait();

        auto [ec, signum] = co_await signals.wait();

        if (ec == capy::cond::canceled)

        if (ec == capy::cond::canceled)

        {

        {

            // Cancelled via stop_token or cancel()

            // Cancelled via stop_token or cancel()

            co_return;

            co_return;

        }

        }

        if (ec)

        if (ec)

        {

        {

            // Handle other errors

            // Handle other errors

            co_return;

            co_return;

        }

        }

        // Process signal

        // Process signal

        std::cout << "Received signal " << signum << std::endl;

        std::cout << "Received signal " << signum << std::endl;

        @endcode

        @endcode

        @return An awaitable that completes with `io_result<int>`.

        @return An awaitable that completes with `io_result<int>`.

            Returns the signal number when a signal is delivered,

            Returns the signal number when a signal is delivered,

            or an error code on failure. Compare against error conditions

            or an error code on failure. Compare against error conditions

            (e.g., `ec == capy::cond::canceled`) rather than error codes.

            (e.g., `ec == capy::cond::canceled`) rather than error codes.

    */

    */

    {

    {

    }

    }

private:

private:

    {

    {

    }

    }

};

};

} // namespace boost::corosio

} // namespace boost::corosio

#endif

#endif