Diff coverage report for

//

//

// Copyright (c) 2025 Vinnie Falco (vinnie.falco@gmail.com)

// Copyright (c) 2025 Vinnie Falco (vinnie.falco@gmail.com)

// Copyright (c) 2026 Steve Gerbino

// Copyright (c) 2026 Steve Gerbino

//

//

// 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/io/io_signal_set.hpp>

#include <boost/corosio/io/io_signal_set.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 <concepts>

#include <concepts>

#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: implementation is an abstract base that

    3. Polymorphic implementation: implementation is an abstract base that

       platform-specific implementations (posix_signal, win_signal)

       platform-specific implementations (posix_signal, win_signal)

       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_signal_set

class BOOST_COROSIO_DECL signal_set : public io_signal_set

{

{

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));

    }

    }

    /** Define backend hooks for signal set operations.

    /** Define backend hooks for signal set operations.

        Platform backends derive from this to provide signal

        Platform backends derive from this to provide signal

        registration via sigaction (POSIX) or the C runtime

        registration via sigaction (POSIX) or the C runtime

        signal() function (Windows).

        signal() function (Windows).

    */

    */

    struct implementation : io_signal_set::implementation

    struct implementation : io_signal_set::implementation

    {

    {

        /** Register a signal with the given flags.

        /** Register a signal with the given flags.

            @param signal_number The signal to register.

            @param signal_number The signal to register.

            @param flags Platform-specific signal handling flags.

            @param flags Platform-specific signal handling flags.

            @return Error code on failure, empty on success.

            @return Error code on failure, empty on success.

        */

        */

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

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

        /** Unregister a signal.

        /** Unregister a signal.

            @param signal_number The signal to remove.

            @param signal_number The signal to remove.

            @return Error code on failure, empty on success.

            @return Error code on failure, empty on success.

        */

        */

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

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

        /** Unregister all signals.

        /** Unregister all signals.

            @return Error code on failure, empty on success.

            @return Error code on failure, empty on success.

        */

        */

        virtual std::error_code clear() = 0;

        virtual std::error_code clear() = 0;

    };

    };

    /** Destructor.

    /** Destructor.

        Cancels any pending operations and releases signal resources.

        Cancels any pending operations and releases signal resources.

    */

    */

    ~signal_set() override;

    ~signal_set() override;

    /** 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>

    {

    {

        };

        };

    /** 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.

        @pre No awaitables returned by @p other's methods exist.

        @pre No awaitables returned by @p other's methods exist.

        @pre The execution context associated with @p other must

        @pre The execution context associated with @p other must

            outlive this signal set.

            outlive this signal set.

    */

    */

    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.

        @param other The signal set to move from.

        @param other The signal set to move from.

        @pre No awaitables returned by either `*this` or @p other's

        @pre No awaitables returned by either `*this` or @p other's

            methods exist.

            methods exist.

        @pre The execution context associated with @p other must

        @pre The execution context associated with @p other must

            outlive this signal set.

            outlive this signal set.

        @return Reference to this signal set.

        @return Reference to this signal set.

    */

    */

    signal_set& operator=(signal_set&& other) noexcept;

    signal_set& operator=(signal_set&& other) noexcept;

    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();

protected:

protected:

    explicit signal_set(handle h) noexcept : io_signal_set(std::move(h)) {}

    explicit signal_set(handle h) noexcept : io_signal_set(std::move(h)) {}

private:

private:

    void do_cancel() override;

    void do_cancel() override;

    {

    {

    }

    }

};

};

} // namespace boost::corosio

} // namespace boost::corosio

#endif

#endif