kAtomic.h

Go to the documentation of this file.

/** 
 * @file    kAtomic.h
 * @brief   Declares the kAtomic class. 
 *
 * @internal
 * Copyright (C) 2012-2014 by LMI Technologies Inc.
 * Licensed under the MIT License.
 * Redistributed files must retain the above copyright notice.
 */
#include <kApi/kApiDef.h>   //--inclusion order controlled by kApiDef

#ifndef K_API_ATOMIC_H
#define K_API_ATOMIC_H

kBeginHeader()

/**
 * @class   kAtomic
 * @ingroup kApi-Threads
 * @brief   Collection of functions for atomic variable operations.
 */

/** 
 * Increments an atomic variable. 
 * 
 * This method is thread-safe. Implements a full memory barrier. 
 *
 * @public              @memberof kAtomic
 * @param   atomic      Pointer to  atomic variable.
 * @return              New atomic value.
 */
kFx(k32s) kAtomic_Increment32s(volatile k32s* atomic); 

/** 
 * Decrements an atomic variable. 
 * 
 * This method is thread-safe. Implements a full memory barrier. 
 *
 * @public              @memberof kAtomic
 * @param   atomic      Pointer to atomic variable.
 * @return              New atomic value.
 */
kFx(k32s) kAtomic_Decrement32s(volatile k32s* atomic); 

/** 
 * Exchanges the value of an atomic variable.
 * 
 * This method is thread-safe. Implements a full memory barrier. 
 *
 * @public              @memberof kAtomic
 * @param   atomic      Pointer to atomic variable.
 * @param   value       New atomic value.
 * @return              Previous atomic value.
 */
kFx(k32s) kAtomic_Exchange32s(volatile k32s* atomic, k32s value); 

/** 
 * Conditionally exchanges the value of an atomic variable.
 * 
 * If the atomic value is equal to the oldValue argument, then it is replaced by the value argument. 
 *
 * This method is thread-safe. Implements a full memory barrier. 
 *
 * @public              @memberof kAtomic
 * @param   atomic      Pointer to atomic variable.
 * @param   oldValue    Previous atomic value.
 * @param   value       New atomic value.
 * @return              kTRUE if the exchange succeeded. 
 */
kFx(kBool) kAtomic_CompareExchange32s(volatile k32s* atomic, k32s oldValue, k32s value); 

/** 
 * Gets the current value of an atomic variable. 
 * 
 * This method is thread-safe. Implements a full memory barrier. 
 *
 * @public              @memberof kAtomic
 * @param   atomic      Pointer to atomic variable.
 * @return              Atomic value.
 */
kFx(k32s) kAtomic_Get32s(volatile k32s* atomic); 

/** 
 * Exchanges the value of an atomic variable.
 * 
 * This method is thread-safe. Implements a full memory barrier. 
 *
 * @public              @memberof kAtomic
 * @param   atomic      Pointer to atomic variable.
 * @param   value       New atomic value.
 * @return              Previous atomic value.
 */
kFx(kPointer) kAtomic_ExchangePointer(volatile kPointer* atomic, kPointer value); 

/** 
 * Conditionally exchanges the value of an atomic variable.
 * 
 * If the atomic value is equal to the oldValue argument, then it is replaced by the value argument. 
 *
 * This method is thread-safe. Implements a full memory barrier. 
 *
 * @public              @memberof kAtomic
 * @param   atomic      Pointer to atomic variable.
 * @param   oldValue    Previous atomic value.
 * @param   value       New atomic value.
 * @return              Previous atomic value.
 */
kFx(kBool) kAtomic_CompareExchangePointer(volatile kPointer* atomic, kPointer oldValue, kPointer value); 

#define kAtomic_Increment32s_(ATM)                          kxAtomic_Increment32s_(ATM)                         ///< Macro version of kAtomic_Increment32s. 
#define kAtomic_Decrement32s_(ATM)                          kxAtomic_Decrement32s_(ATM)                         ///< Macro version of kAtomic_Decrement32s.
#define kAtomic_Exchange32s_(ATM, VAL)                      kxAtomic_Exchange32s_(ATM, VAL)                     ///< Macro version of kAtomic_Exchange32s.
#define kAtomic_CompareExchange32s_(ATM, OLD, VAL)          kxAtomic_CompareExchange32s_(ATM, OLD, VAL)         ///< Macro version of kAtomic_CompareExchange32s.
#define kAtomic_Get32s_(ATM)                                kxAtomic_Get32s_(ATM)                               ///< Macro version of kAtomic_Get32s.
#define kAtomic_ExchangePointer_(ATM, VAL)                  kxAtomic_ExchangePointer_(ATM, VAL)                 ///< Macro version of kAtomic_ExchangePointer.
#define kAtomic_CompareExchangePointer_(ATM, OLD, VAL)      kxAtomic_CompareExchangePointer_(ATM, OLD, VAL)     ///< Macro version of kAtomic_CompareExchangePointer.

kEndHeader()

#include <kApi/Threads/kAtomic.x.h>

#endif