SYS_AtomicInt.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * NAME:        SYS_AtomicInt.h (SYS Library, C++)
 *
 * COMMENTS:    Thread-safe operations on integers
 */

#ifndef __SYS_AtomicInt__
#define __SYS_AtomicInt__

#include "SYS_Types.h"
#include "SYS_MemoryOrder.h"
#include "SYS_AtomicImpl.h"
#include <SYS/SYS_TypeDecorate.h>

#include <atomic>

template <typename T>
class SYS_AtomicInt
{
public:
    explicit SYS_AtomicInt(T value = 0) : myValue(value) {}

    /// An empty constructor. This will initialize the value with garbage,
    /// unless used as a static object (in which case it will be guaranteed
    /// by the C++ standard to be initialized to zero). Only use if required
    /// to be set prior to other, dependent statically initialized objects.
    SYS_AtomicInt(SYS_EmptyConstructor) {}

    /// Atomically assigns val to myValue, returning the prior value of
    /// myValue.
    inline T    exchange(T val);

    /// Atomically adds val to myValue, returning the prior value of
    /// myValue.
    inline T    exchangeAdd(T val);

    /// Atomically adds val to myValue, returning the new value of myValue.
    inline T    add(T val);

    /// Atomically set myValue to the maximum of val and myValue. Returns the
    /// last known maximal value.
    inline T    maximum(T val);

    /// Atomically set myValue to the minimum of val and myValue. Returns the
    /// last known minimal value.
    inline T    minimum(T val);

    /// Atomically compares (myValue == expected), and if true, replaces
    /// myValue with desired. Returns the prior value.
    inline T    compare_swap(T expected, T desired);

    inline bool compareExchangeStrong(
            T &expected,
            T desired,
            SYS_MemoryOrder success = SYS_MEMORY_ORDER_SEQ_CST,
            SYS_MemoryOrder failure = SYS_MEMORY_ORDER_SEQ_CST);

    inline bool compareExchangeWeak(
            T &expected,
            T desired,
            SYS_MemoryOrder success = SYS_MEMORY_ORDER_SEQ_CST,
            SYS_MemoryOrder failure = SYS_MEMORY_ORDER_SEQ_CST);

    /// @pre The supplied order must be one of [RELAXED, STORE, SEQ_CST].
    inline void store(T val, SYS_MemoryOrder order=SYS_MEMORY_ORDER_SEQ_CST);

    /// @pre The supplied order must be one of [RELAXED, LOAD, SEQ_CST].
    inline T    load(SYS_MemoryOrder order=SYS_MEMORY_ORDER_SEQ_CST) const;

    /// Forced RELAXED memory load
    /// GCC has trouble inlining so we pull the definition up here.
    SYS_FORCE_INLINE T          relaxedLoad() const;

    SYS_FORCE_INLINE void       relaxedStore(T val);

private:
    std::atomic<T>      myValue;

private:
    // Prohibited operators
    SYS_AtomicInt(const SYS_AtomicInt &) = default;
    SYS_AtomicInt       &operator=(const SYS_AtomicInt &) = default;
    /// WARNING: DO NOT ADD THIS BACK!  It was atomic, and nobody expected that,
    ///          so it ended up slowing down many things, including every
    ///          string attribute read.
    explicit operator T() const;

    static constexpr std::memory_order sysToStdMemoryOrder(SYS_MemoryOrder order);
};

typedef SYS_AtomicInt<int32> SYS_AtomicInt32;
typedef SYS_AtomicInt<int64> SYS_AtomicInt64;

#if defined(AMD64) || defined(ARM64)
typedef SYS_AtomicInt<int64> SYS_AtomicCounter;
#else
typedef SYS_AtomicInt<int32> SYS_AtomicCounter;
#endif

template <typename T>
SYS_DECLARE_LEGACY_TR_TEMPLATE(SYS_AtomicInt<T>)

template <typename T>
SYS_ATOMIC_INLINE T
SYS_AtomicInt<T>::exchange(T val)
{
    return myValue.exchange(val);
}

template <typename T>
SYS_ATOMIC_INLINE T
SYS_AtomicInt<T>::exchangeAdd(T val)
{
    return myValue.fetch_add(val);
}

template <typename T>
SYS_ATOMIC_INLINE T
SYS_AtomicInt<T>::add(T val)
{
    return (myValue += val);
}

template <typename T>
SYS_ATOMIC_INLINE T
SYS_AtomicInt<T>::maximum(T val)
{
    T me = relaxedLoad();

    do
    {
        if (me > val)
            break;
    }
    while (!compareExchangeWeak(me, val));

    return me;
}

template <typename T>
SYS_ATOMIC_INLINE T
SYS_AtomicInt<T>::minimum(T val)
{
    T me = relaxedLoad();

    do
    {
        if (me < val)
            break;
    }
    while (!compareExchangeWeak(me, val));

    return me;
}

template <typename T>
SYS_ATOMIC_INLINE T
SYS_AtomicInt<T>::compare_swap(T expected, T desired)
{
    compareExchangeStrong(expected, desired);
    return expected;
}

template <typename T>
SYS_ATOMIC_INLINE bool
SYS_AtomicInt<T>::compareExchangeStrong(
        T &expected,
        T desired,
        SYS_MemoryOrder success,
        SYS_MemoryOrder failure)
{
    return myValue.compare_exchange_strong(
            expected, desired, sysToStdMemoryOrder(success),
            sysToStdMemoryOrder(failure));
}

template <typename T>
SYS_ATOMIC_INLINE bool
SYS_AtomicInt<T>::compareExchangeWeak(
        T &expected,
        T desired,
        SYS_MemoryOrder success,
        SYS_MemoryOrder failure)
{
    return myValue.compare_exchange_weak(
            expected, desired, sysToStdMemoryOrder(success),
            sysToStdMemoryOrder(failure));
}

/// Next two methods intentionally not marked as volatile as this would cause 
/// &myValue to evaluate to a pointer to a volatile myValue and that has 
/// implications on MSVC2005+ beyond the C++ spec.
///
/// This shouldn't be a problem unless somebody needs a volatile instance of
/// SYS_AtomicInt<T>.
template <typename T>
SYS_ATOMIC_INLINE void
SYS_AtomicInt<T>::store(T val, SYS_MemoryOrder order)
{
    myValue.store(val, sysToStdMemoryOrder(order));
}

template <typename T>
SYS_ATOMIC_INLINE T
SYS_AtomicInt<T>::load(SYS_MemoryOrder order) const
{
    return myValue.load(sysToStdMemoryOrder(order));
}

template <typename T>
SYS_ATOMIC_INLINE T
SYS_AtomicInt<T>::relaxedLoad() const
{
    return myValue.load(std::memory_order_relaxed);
}

template <typename T>
SYS_ATOMIC_INLINE void
SYS_AtomicInt<T>::relaxedStore(T val)
{
    myValue.store(val, std::memory_order_relaxed);
};

template <typename T>
SYS_ATOMIC_INLINE constexpr std::memory_order
SYS_AtomicInt<T>::sysToStdMemoryOrder(SYS_MemoryOrder order)
{
    std::memory_order std_order = std::memory_order_seq_cst;

    switch (order)
    {
        case SYS_MEMORY_ORDER_RELAXED: std_order = std::memory_order_relaxed; break;
        case SYS_MEMORY_ORDER_LOAD:    std_order = std::memory_order_acquire; break;
        case SYS_MEMORY_ORDER_STORE:   std_order = std::memory_order_release; break;
        case SYS_MEMORY_ORDER_SEQ_CST: std_order = std::memory_order_seq_cst; break;
    }

    return std_order;
}

#endif