/*

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

 *

 * Copyright (c) 2020-2025 Andrey Semashev

 */

/*!

 * \file   atomic/detail/futex.hpp

 *

 * This header defines wrappers around futex syscall.

 *

 * http://man7.org/linux/man-pages/man2/futex.2.html

 * https://man.openbsd.org/futex

 */

#ifndef BOOST_ATOMIC_DETAIL_FUTEX_HPP_INCLUDED_

#define BOOST_ATOMIC_DETAIL_FUTEX_HPP_INCLUDED_

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

#ifdef BOOST_HAS_PRAGMA_ONCE

#pragma once

#endif

#if defined(__linux__)

#include <sys/syscall.h>

#if defined(SYS_futex)

#define BOOST_ATOMIC_DETAIL_SYS_FUTEX SYS_futex

#elif defined(SYS_futex_time64)

// On some 32-bit targets (e.g. riscv32) SYS_futex is not defined and instead SYS_futex_time64 is implemented,

// which is equivalent to SYS_futex but uses 64-bit time_t.

#define BOOST_ATOMIC_DETAIL_SYS_FUTEX SYS_futex_time64

#define BOOST_ATOMIC_DETAIL_FUTEX_TIME64

#elif defined(__NR_futex)

// Some Android NDKs (Google NDK and older Crystax.NET NDK versions) don't define SYS_futex.

#define BOOST_ATOMIC_DETAIL_SYS_FUTEX __NR_futex

#endif

#elif defined(__OpenBSD__)

// OpenBSD provides futex(2) function wrapper since OpenBSD 6.2 (https://man.openbsd.org/OpenBSD-6.2/futex.2).

// It has also removed syscall(2) interface:

// https://github.com/openbsd/src/commit/cafeb892b121ee89c39c2b940e8ccd6950f50009

#include <sys/param.h>

#include <cerrno>

#if OpenBSD >= 201711

#define BOOST_ATOMIC_DETAIL_OPENBSD_FUTEX

#endif // OpenBSD >= 201711

#elif defined(__NETBSD__) || defined(__NetBSD__)

#include <sys/syscall.h>

#if defined(SYS___futex)

// NetBSD defines SYS___futex, which has slightly different parameters. Basically, it has decoupled timeout and val2 parameters:

// int __futex(int *addr1, int op, int val1, const struct timespec *timeout, int *addr2, int val2, int val3);

// https://ftp.netbsd.org/pub/NetBSD/NetBSD-current/src/sys/sys/syscall.h

// http://bxr.su/NetBSD/sys/kern/sys_futex.c

#define BOOST_ATOMIC_DETAIL_SYS_FUTEX SYS___futex

#define BOOST_ATOMIC_DETAIL_NETBSD_FUTEX

#endif // defined(SYS___futex)

#endif

#if defined(BOOST_ATOMIC_DETAIL_SYS_FUTEX) || defined(BOOST_ATOMIC_DETAIL_OPENBSD_FUTEX)

#if defined(__linux__)

#include <linux/futex.h>

#else

#include <sys/futex.h>

#endif

#include <time.h> // timespec

#include <cstdint>

#include <boost/atomic/detail/intptr.hpp>

#include <boost/atomic/detail/header.hpp>

#define BOOST_ATOMIC_DETAIL_HAS_FUTEX

// Note: On Android, futex.h is lacking many definitions, but the actual Linux kernel supports the API in full.

#if defined(FUTEX_WAIT_BITSET)

#define BOOST_ATOMIC_DETAIL_FUTEX_WAIT_BITSET FUTEX_WAIT_BITSET

#elif defined(__ANDROID__)

#define BOOST_ATOMIC_DETAIL_FUTEX_WAIT_BITSET 9

#endif

#if defined(FUTEX_PRIVATE_FLAG)

#define BOOST_ATOMIC_DETAIL_FUTEX_PRIVATE_FLAG FUTEX_PRIVATE_FLAG

#elif defined(__ANDROID__)

#define BOOST_ATOMIC_DETAIL_FUTEX_PRIVATE_FLAG 128

#else

#define BOOST_ATOMIC_DETAIL_FUTEX_PRIVATE_FLAG 0

#endif

#if defined(FUTEX_CLOCK_REALTIME)

#define BOOST_ATOMIC_DETAIL_FUTEX_CLOCK_REALTIME FUTEX_CLOCK_REALTIME

#elif defined(__ANDROID__)

#define BOOST_ATOMIC_DETAIL_FUTEX_CLOCK_REALTIME 256

#endif

namespace boost {

namespace atomics {

namespace detail {

#if defined(BOOST_ATOMIC_DETAIL_FUTEX_TIME64)

//! An equivalent of `timespec` that uses 64-bit members when the userland `timespec` is 32-bit

struct futex_timespec

{

    std::int64_t tv_sec;

    std::int64_t tv_nsec;

    futex_timespec() = default;

    explicit futex_timespec(::timespec ts) noexcept :

        tv_sec(ts.tv_sec), tv_nsec(ts.tv_nsec)

    {}

};

#else // defined(BOOST_ATOMIC_DETAIL_FUTEX_TIME64)

using futex_timespec = ::timespec;

#endif // defined(BOOST_ATOMIC_DETAIL_FUTEX_TIME64)

//! Invokes an operation on the futex

BOOST_FORCEINLINE int futex_invoke(void* addr1, int op, unsigned int val1, const futex_timespec* timeout = nullptr, void* addr2 = nullptr, unsigned int val3 = 0u) noexcept

{

#if defined(BOOST_ATOMIC_DETAIL_OPENBSD_FUTEX)

    return ::futex

    (

        static_cast< volatile std::uint32_t* >(addr1),

        op,

        static_cast< int >(val1),

        timeout,

        static_cast< volatile std::uint32_t* >(addr2)

    );

#elif defined(BOOST_ATOMIC_DETAIL_NETBSD_FUTEX)

    // Pass 0 in val2.

    return ::syscall(BOOST_ATOMIC_DETAIL_SYS_FUTEX, addr1, op, val1, timeout, addr2, 0u, val3);

#else

    return ::syscall(BOOST_ATOMIC_DETAIL_SYS_FUTEX, addr1, op, val1, timeout, addr2, val3);

#endif

}

//! Invokes an operation on the futex

BOOST_FORCEINLINE int futex_invoke(void* addr1, int op, unsigned int val1, unsigned int val2, void* addr2 = nullptr, unsigned int val3 = 0u) noexcept

{

#if defined(BOOST_ATOMIC_DETAIL_OPENBSD_FUTEX)

    return ::futex

    (

        static_cast< volatile std::uint32_t* >(addr1),

        op,

        static_cast< int >(val1),

        reinterpret_cast< const futex_timespec* >(static_cast< atomics::detail::uintptr_t >(val2)),

        static_cast< volatile std::uint32_t* >(addr2)

    );

#elif defined(BOOST_ATOMIC_DETAIL_NETBSD_FUTEX)

    // Pass nullptr in timeout.

    return ::syscall(BOOST_ATOMIC_DETAIL_SYS_FUTEX, addr1, op, val1, static_cast< void* >(nullptr), addr2, val2, val3);

#else

    return ::syscall(BOOST_ATOMIC_DETAIL_SYS_FUTEX, addr1, op, val1, static_cast< atomics::detail::uintptr_t >(val2), addr2, val3);

#endif

}

//! Checks that the value \c pval is \c expected and blocks

BOOST_FORCEINLINE int futex_wait(void* pval, unsigned int expected, int flags) noexcept

{

    int res = futex_invoke(pval, FUTEX_WAIT | flags, expected);

#if defined(OpenBSD) && (OpenBSD < 202111)

    // In older OpenBSD versions, futex(2) returned error code directly instead of setting errno and returning -1.

    // This was fixed in OpenBSD 7.0 (https://github.com/openbsd/src/commit/3288ea8fbfe504db25b57dd18b664a1aa377e4bf).

    // This primarily affects FUTEX_WAIT. For FUTEX_WAKE and FUTEX_REQUEUE the returned value may be positive

    // on successful completion of the call and there seem to be no errors that can be returned. Other functions

    // are not supported on OpenBSD 7.0 and older.

    if (res > 0)

    {

        errno = res;

        res = -1;

    }

#endif // defined(OpenBSD) && (OpenBSD < 202111)

    return res;

}

//! Checks that the value \c pval is \c expected and blocks until timeout

BOOST_FORCEINLINE int futex_wait_for(void* pval, unsigned int expected, futex_timespec const& timeout, int flags) noexcept

{

    int res = futex_invoke(pval, FUTEX_WAIT | flags, expected, &timeout);

#if defined(OpenBSD) && (OpenBSD < 202111)

    // See the comment in futex_wait

    if (res > 0)

    {

        errno = res;

        res = -1;

    }

#endif // defined(OpenBSD) && (OpenBSD < 202111)

    return res;

}

#if defined(BOOST_ATOMIC_DETAIL_FUTEX_WAIT_BITSET)

//! Checks that the value \c pval is \c expected and blocks until timeout

BOOST_FORCEINLINE int futex_wait_until(void* pval, unsigned int expected, futex_timespec const& timeout, int flags) noexcept

{

    return futex_invoke(pval, BOOST_ATOMIC_DETAIL_FUTEX_WAIT_BITSET | flags, expected, &timeout, nullptr, ~static_cast< unsigned int >(0u));

}

#endif // defined(BOOST_ATOMIC_DETAIL_FUTEX_WAIT_BITSET)

//! Wakes the specified number of threads waiting on the futex

BOOST_FORCEINLINE int futex_signal(void* pval, int flags, unsigned int count = 1u) noexcept

{

    return futex_invoke(pval, FUTEX_WAKE | flags, count);

}

//! Wakes all threads waiting on the futex

BOOST_FORCEINLINE int futex_broadcast(void* pval, int flags) noexcept

{

    return futex_signal(pval, flags, (~static_cast< unsigned int >(0u)) >> 1u);

}

//! Wakes the wake_count threads waiting on the futex pval1 and requeues up to requeue_count of the blocked threads onto another futex pval2

BOOST_FORCEINLINE int futex_requeue

(

    void* pval1,

    void* pval2,

    int flags,

    unsigned int wake_count = 1u,

    unsigned int requeue_count = (~static_cast< unsigned int >(0u)) >> 1u

) noexcept

{

    return futex_invoke(pval1, FUTEX_REQUEUE | flags, wake_count, requeue_count, pval2);

}

} // namespace detail

} // namespace atomics

} // namespace boost

#include <boost/atomic/detail/footer.hpp>

#endif // defined(BOOST_ATOMIC_DETAIL_SYS_FUTEX) || defined(BOOST_ATOMIC_DETAIL_OPENBSD_FUTEX)

#endif // BOOST_ATOMIC_DETAIL_FUTEX_HPP_INCLUDED_