You.i Engine
Public Member Functions | Static Public Member Functions | List of all members
yi::deprecated::CYIAtomic< YI_ATOMIC_TYPE > Class Template Reference
Threading

Detailed Description

template<typename YI_ATOMIC_TYPE>
class yi::deprecated::CYIAtomic< YI_ATOMIC_TYPE >

Class is a simple convenient wrapper around a volatile value and atomic instructions.

With CYIAtomic, you can replace this code:

class MyClass
{
private:
CYIMutex m_valueMutex;
int32_t m_nData;
public:
void AddValue(int32_t nData)
{
m_valueMutex.Lock();
m_nData += nData;
m_valueMutex.Unlock();
}
};

by this:

class MyClass
{
private:
CYIAtomic<int32_t> m_nData; // can also use YI_ATOMIC_INT32
public:
void AddValue(int32_t nData)
{
m_nData += nData;
}
};

Both ways are thread-safe, but the atomic way is 'lockless' and is guaranteed to never de-schedule an active thread like what would happen to a thread when it hits a locked CYIMutex. For this reason, CYIAtomic is significantly faster than using the CYIMutex to protect a member variable against multi-thread access.

The CYIAtomic class supports the following types only:

  • bool
  • uint8_t
  • uint16_t
  • uint32_t
  • uint64_t
  • int8_t
  • int16_t
  • int32_t
  • int64_t
  • Pointer types
Warning
CYIAtomic cannot and will not support float and double types.

#include <deprecated/YiAtomic.h>

Public Member Functions

 CYIAtomic (YI_ATOMIC_TYPE nValue=(YI_ATOMIC_TYPE) 0)
 
 CYIAtomic (const CYIAtomic< YI_ATOMIC_TYPE > &rOther)
 
bool operator== (YI_ATOMIC_TYPE nValue) const
 
bool operator!= (YI_ATOMIC_TYPE nValue) const
 
bool operator! () const
 
 operator YI_ATOMIC_TYPE () const
 
CYIAtomic< YI_ATOMIC_TYPE > & operator= (YI_ATOMIC_TYPE nValue)
 
YI_ATOMIC_TYPE operator+= (YI_ATOMIC_TYPE nValueToAdd)
 
YI_ATOMIC_TYPE operator-= (YI_ATOMIC_TYPE nValueToSub)
 
YI_ATOMIC_TYPE operator*= (YI_ATOMIC_TYPE nValueToMult)
 
YI_ATOMIC_TYPE operator/= (YI_ATOMIC_TYPE nValueToDiv)
 
YI_ATOMIC_TYPE operator&= (YI_ATOMIC_TYPE nValueToAnd)
 
YI_ATOMIC_TYPE operator|= (YI_ATOMIC_TYPE nValueToOr)
 
YI_ATOMIC_TYPE operator^= (YI_ATOMIC_TYPE nValueToXor)
 
YI_ATOMIC_TYPE operator++ ()
 
YI_ATOMIC_TYPE operator++ (int)
 
YI_ATOMIC_TYPE operator-- ()
 
YI_ATOMIC_TYPE operator-- (int)
 
YI_ATOMIC_TYPE FetchAndAdd (YI_ATOMIC_TYPE nValueToAdd)
 
YI_ATOMIC_TYPE FetchAndSub (YI_ATOMIC_TYPE nValue)
 
YI_ATOMIC_TYPE FetchAndAnd (YI_ATOMIC_TYPE nValue)
 
YI_ATOMIC_TYPE FetchAndOr (YI_ATOMIC_TYPE nValue)
 
YI_ATOMIC_TYPE FetchAndXor (YI_ATOMIC_TYPE nValue)
 
YI_ATOMIC_TYPE AddAndFetch (YI_ATOMIC_TYPE nValue)
 
YI_ATOMIC_TYPE SubAndFetch (YI_ATOMIC_TYPE nValue)
 
YI_ATOMIC_TYPE AndAndFetch (YI_ATOMIC_TYPE nValue)
 
YI_ATOMIC_TYPE OrAndFetch (YI_ATOMIC_TYPE nValue)
 
YI_ATOMIC_TYPE XorAndFetch (YI_ATOMIC_TYPE nValue)
 
YI_ATOMIC_TYPE CompareAndSwap (YI_ATOMIC_TYPE nCurrentValue, YI_ATOMIC_TYPE nNewValue)
 
YI_ATOMIC_TYPE Load () const
 
void Store (YI_ATOMIC_TYPE nNewValue)
 

Static Public Member Functions

static bool IsLockFree () const
 

Constructor & Destructor Documentation

template<typename YI_ATOMIC_TYPE>
yi::deprecated::CYIAtomic< YI_ATOMIC_TYPE >::CYIAtomic ( YI_ATOMIC_TYPE  nValue = (YI_ATOMIC_TYPE) 0)
template<typename YI_ATOMIC_TYPE>
yi::deprecated::CYIAtomic< YI_ATOMIC_TYPE >::CYIAtomic ( const CYIAtomic< YI_ATOMIC_TYPE > &  rOther)

Member Function Documentation

template<typename YI_ATOMIC_TYPE>
YI_ATOMIC_TYPE yi::deprecated::CYIAtomic< YI_ATOMIC_TYPE >::AddAndFetch ( YI_ATOMIC_TYPE  nValue)

Helper function that is a low-level abstraction of the add-and-fetch atomic instruction. The implementation is compiler-specific. If the compiler is not supported, a generic implementation will be provided using regular mutex with no performance benefits.

Example:

class MyCounter
{
public:
int32_t operator++();
private:
volatile YI_ATOMIC_INT32 m_nCounter;
};
// ++instance
inline int32_t MyCounter::operator++()
{
return m_nCounter.AddAndFetch(1);
}

For more information about atomic instructions, please visit to the following web sites:

http://en.wikipedia.org/wiki/Atomic_(computer_science)

Note
This function is thread-safe.
template<typename YI_ATOMIC_TYPE>
YI_ATOMIC_TYPE yi::deprecated::CYIAtomic< YI_ATOMIC_TYPE >::AndAndFetch ( YI_ATOMIC_TYPE  nValue)

Helper function that is a low-level abstraction of the and-and-fetch atomic instruction. The implementation is compiler-specific. If the compiler is not supported, a generic implementation will be provided using regular mutex with no performance benefits.

For more information about atomic instructions, please visit to the following web sites:

http://en.wikipedia.org/wiki/Atomic_(computer_science)

Note
This function is thread-safe.
template<typename YI_ATOMIC_TYPE>
YI_ATOMIC_TYPE yi::deprecated::CYIAtomic< YI_ATOMIC_TYPE >::CompareAndSwap ( YI_ATOMIC_TYPE  nCurrentValue,
YI_ATOMIC_TYPE  nNewValue 
)

Helper function that is a low-level abstraction of the compare-and-swap atomic instruction, also known as 'compare-and-exchange'. The implementation is compiler-specific. If the compiler is not supported, a generic implementation will be provided using regular mutex with no performance benefits.

To use this function, you must provide both the current value and the new value. The assignment will be performed only if the value contained in the atomic variable is equal to nCurrentValue. The function always returns the value from prior to attempting an assignment. If the returned value does not match nCurrentValue, it means that another thread changed the value while we were performing the call. If that is the case, you can chose to either abort or retry.

Example:

class MyClass
{
public:
int32_t MyClass::operator*=(int32_t nValue);
private:
volatile YI_ATOMIC_INT32 m_nValue;
};
inline int32_t MyClass::operator*=(int32_t nValue)
{
int32_t nCurrentValue;
int32_t nNewValue;
do
{
nCurrentValue = m_nValue;
nNewValue = nCurrentValue * nValue;
} while(m_nValue.CompareAndSwap(nCurrentValue, nNewValue) != nCurrentValue);
return (nNewValue);
}

For more information about the compare-and-swap operation, please go to the following web sites:

http://en.wikipedia.org/wiki/Atomic_(computer_science)
http://en.wikipedia.org/wiki/Compare-and-swap

Note
This function is thread-safe.
template<typename YI_ATOMIC_TYPE>
YI_ATOMIC_TYPE yi::deprecated::CYIAtomic< YI_ATOMIC_TYPE >::FetchAndAdd ( YI_ATOMIC_TYPE  nValueToAdd)

Helper function that is a low-level abstraction of the fetch-and-add atomic instruction. The implementation is compiler-specific. If the compiler is not supported, a generic implementation will be provided using regular mutex with no performance benefits.

Example:

class MyCounter
{
public:
int32_t operator++(int);
private:
volatile YI_ATOMIC_INT32 m_nCounter;
};
// ++instance
inline int32_t MyCounter::operator++(int)
{
return m_nCounter.FetchAndAdd(1);
}

For more information about atomic instructions and the fetch-and-add instruction, please visit to the following web sites:

http://en.wikipedia.org/wiki/Atomic_(computer_science)
http://en.wikipedia.org/wiki/Fetch-and-add

Note
This function is thread-safe.
template<typename YI_ATOMIC_TYPE>
YI_ATOMIC_TYPE yi::deprecated::CYIAtomic< YI_ATOMIC_TYPE >::FetchAndAnd ( YI_ATOMIC_TYPE  nValue)

Helper function that is a low-level abstraction of the fetch-and-and atomic instruction. The implementation is compiler-specific. If the compiler is not supported, a generic implementation will be provided using regular mutex with no performance benefits.

For more information about atomic instructions, please visit to the following web sites:

http://en.wikipedia.org/wiki/Atomic_(computer_science)

Note
This function is thread-safe.
template<typename YI_ATOMIC_TYPE>
YI_ATOMIC_TYPE yi::deprecated::CYIAtomic< YI_ATOMIC_TYPE >::FetchAndOr ( YI_ATOMIC_TYPE  nValue)

Helper function that is a low-level abstraction of the fetch-and-or atomic instruction. The implementation is compiler-specific. If the compiler is not supported, a generic implementation will be provided using regular mutex with no performance benefits.

For more information about atomic instructions, please visit to the following web sites:

http://en.wikipedia.org/wiki/Atomic_(computer_science)

Note
This function is thread-safe.
template<typename YI_ATOMIC_TYPE>
YI_ATOMIC_TYPE yi::deprecated::CYIAtomic< YI_ATOMIC_TYPE >::FetchAndSub ( YI_ATOMIC_TYPE  nValue)

Helper function that is a low-level abstraction of the fetch-and-sub atomic instruction. The implementation is compiler-specific. If the compiler is not supported, a generic implementation will be provided using regular mutex with no performance benefits.

Example:

class MyCounter
{
public:
int32_t operator--(int);
private:
volatile YI_ATOMIC_INT32 m_nCounter;
};
// ++instance
inline int32_t MyCounter::operator--(int)
{
return m_nCounter.FetchAndSub(1);
}

For more information about atomic instructions, please visit to the following web site:

http://en.wikipedia.org/wiki/Atomic_(computer_science)

Note
This function is thread-safe.
template<typename YI_ATOMIC_TYPE>
YI_ATOMIC_TYPE yi::deprecated::CYIAtomic< YI_ATOMIC_TYPE >::FetchAndXor ( YI_ATOMIC_TYPE  nValue)

Helper function that is a low-level abstraction of the fetch-and-xor atomic instruction. The implementation is compiler-specific. If the compiler is not supported, a generic implementation will be provided using regular mutex with no performance benefits.

For more information about atomic instructions, please visit to the following web sites:

http://en.wikipedia.org/wiki/Atomic_(computer_science)

Note
This function is thread-safe.
template<typename YI_ATOMIC_TYPE>
static bool yi::deprecated::CYIAtomic< YI_ATOMIC_TYPE >::IsLockFree ( ) const
static

Helper function to determine if we support atomic instructions with your compiler. Returns true if it is supported, false otherwise.

template<typename YI_ATOMIC_TYPE>
YI_ATOMIC_TYPE yi::deprecated::CYIAtomic< YI_ATOMIC_TYPE >::Load ( ) const

Fetches and returns the value contained in this atomic variable.

Note
This function is thread-safe.
template<typename YI_ATOMIC_TYPE>
yi::deprecated::CYIAtomic< YI_ATOMIC_TYPE >::operator YI_ATOMIC_TYPE ( ) const
template<typename YI_ATOMIC_TYPE>
bool yi::deprecated::CYIAtomic< YI_ATOMIC_TYPE >::operator! ( ) const
template<typename YI_ATOMIC_TYPE>
bool yi::deprecated::CYIAtomic< YI_ATOMIC_TYPE >::operator!= ( YI_ATOMIC_TYPE  nValue) const
template<typename YI_ATOMIC_TYPE>
YI_ATOMIC_TYPE yi::deprecated::CYIAtomic< YI_ATOMIC_TYPE >::operator&= ( YI_ATOMIC_TYPE  nValueToAnd)
template<typename YI_ATOMIC_TYPE>
YI_ATOMIC_TYPE yi::deprecated::CYIAtomic< YI_ATOMIC_TYPE >::operator*= ( YI_ATOMIC_TYPE  nValueToMult)
template<typename YI_ATOMIC_TYPE>
YI_ATOMIC_TYPE yi::deprecated::CYIAtomic< YI_ATOMIC_TYPE >::operator++ ( )
template<typename YI_ATOMIC_TYPE>
YI_ATOMIC_TYPE yi::deprecated::CYIAtomic< YI_ATOMIC_TYPE >::operator++ ( int  )
template<typename YI_ATOMIC_TYPE>
YI_ATOMIC_TYPE yi::deprecated::CYIAtomic< YI_ATOMIC_TYPE >::operator+= ( YI_ATOMIC_TYPE  nValueToAdd)
template<typename YI_ATOMIC_TYPE>
YI_ATOMIC_TYPE yi::deprecated::CYIAtomic< YI_ATOMIC_TYPE >::operator-- ( )
template<typename YI_ATOMIC_TYPE>
YI_ATOMIC_TYPE yi::deprecated::CYIAtomic< YI_ATOMIC_TYPE >::operator-- ( int  )
template<typename YI_ATOMIC_TYPE>
YI_ATOMIC_TYPE yi::deprecated::CYIAtomic< YI_ATOMIC_TYPE >::operator-= ( YI_ATOMIC_TYPE  nValueToSub)
template<typename YI_ATOMIC_TYPE>
YI_ATOMIC_TYPE yi::deprecated::CYIAtomic< YI_ATOMIC_TYPE >::operator/= ( YI_ATOMIC_TYPE  nValueToDiv)
template<typename YI_ATOMIC_TYPE>
CYIAtomic<YI_ATOMIC_TYPE>& yi::deprecated::CYIAtomic< YI_ATOMIC_TYPE >::operator= ( YI_ATOMIC_TYPE  nValue)
template<typename YI_ATOMIC_TYPE>
bool yi::deprecated::CYIAtomic< YI_ATOMIC_TYPE >::operator== ( YI_ATOMIC_TYPE  nValue) const
template<typename YI_ATOMIC_TYPE>
YI_ATOMIC_TYPE yi::deprecated::CYIAtomic< YI_ATOMIC_TYPE >::operator^= ( YI_ATOMIC_TYPE  nValueToXor)
template<typename YI_ATOMIC_TYPE>
YI_ATOMIC_TYPE yi::deprecated::CYIAtomic< YI_ATOMIC_TYPE >::operator|= ( YI_ATOMIC_TYPE  nValueToOr)
template<typename YI_ATOMIC_TYPE>
YI_ATOMIC_TYPE yi::deprecated::CYIAtomic< YI_ATOMIC_TYPE >::OrAndFetch ( YI_ATOMIC_TYPE  nValue)

Helper function that is a low-level abstraction of the or-and-fetch atomic instruction. The implementation is compiler-specific. If the compiler is not supported, a generic implementation will be provided using regular mutex with no performance benefits.

For more information about atomic instructions, please visit to the following web sites:

http://en.wikipedia.org/wiki/Atomic_(computer_science)

Note
This function is thread-safe.
template<typename YI_ATOMIC_TYPE>
void yi::deprecated::CYIAtomic< YI_ATOMIC_TYPE >::Store ( YI_ATOMIC_TYPE  nNewValue)

Stores the provided value in this atomic variable.

Note
This function is thread-safe.
template<typename YI_ATOMIC_TYPE>
YI_ATOMIC_TYPE yi::deprecated::CYIAtomic< YI_ATOMIC_TYPE >::SubAndFetch ( YI_ATOMIC_TYPE  nValue)

Helper function that is a low-level abstraction of the sub-and-fetch atomic instruction. The implementation is compiler-specific. If the compiler is not supported, a generic implementation will be provided using regular mutex with no performance benefits.

Example:

class MyCounter
{
public:
int32_t operator--();
private:
volatile YI_ATOMIC_INT32 m_nCounter;
};
// ++instance
inline int32_t MyCounter::operator--()
{
return m_nCounter.SubAndFetch(1);
}

For more information about atomic instructions, please visit to the following web sites:

http://en.wikipedia.org/wiki/Atomic_(computer_science)

Note
This function is thread-safe.
template<typename YI_ATOMIC_TYPE>
YI_ATOMIC_TYPE yi::deprecated::CYIAtomic< YI_ATOMIC_TYPE >::XorAndFetch ( YI_ATOMIC_TYPE  nValue)

Helper function that is a low-level abstraction of the xor-and-fetch atomic instruction. The implementation is compiler-specific. If the compiler is not supported, a generic implementation will be provided using regular mutex with no performance benefits.

For more information about atomic instructions, please visit to the following web sites:

http://en.wikipedia.org/wiki/Atomic_(computer_science)

Note
This function is thread-safe.
The documentation for this class was generated from the following file: