include/SDL_atomic.h
changeset 3407 d3baf5ac4e37
parent 3261 72b542f34739
child 3697 f7b03b6838cb
     1.1 --- a/include/SDL_atomic.h	Sun Oct 18 23:21:15 2009 +0000
     1.2 +++ b/include/SDL_atomic.h	Mon Oct 19 13:31:58 2009 +0000
     1.3 @@ -23,9 +23,19 @@
     1.4   */
     1.5  
     1.6  /**
     1.7 - * \file SDL_atomic.h
     1.8 - *
     1.9 - * Atomic operations.
    1.10 + *  \file SDL_atomic.h
    1.11 + *  
    1.12 + *  Atomic operations.
    1.13 + *  
    1.14 + *  These operations may, or may not, actually be implemented using
    1.15 + *  processor specific atomic operations. When possible they are
    1.16 + *  implemented as true processor specific atomic operations. When that
    1.17 + *  is not possible the are implemented using locks that *do* use the
    1.18 + *  available atomic operations.
    1.19 + *  
    1.20 + *  At the very minimum spin locks must be implemented. Without spin
    1.21 + *  locks it is not possible (AFAICT) to emulate the rest of the atomic
    1.22 + *  operations.
    1.23   */
    1.24  
    1.25  #ifndef _SDL_atomic_h_
    1.26 @@ -43,176 +53,139 @@
    1.27  /* *INDENT-ON* */
    1.28  #endif
    1.29  
    1.30 -/**
    1.31 - * These operations may, or may not, actually be implemented using
    1.32 - * processor specific atomic operations. When possible they are
    1.33 - * implemented as true processor specific atomic operations. When that
    1.34 - * is not possible the are implemented using locks that *do* use the
    1.35 - * available atomic operations.
    1.36 - *
    1.37 - * At the very minimum spin locks must be implemented. Without spin
    1.38 - * locks it is not possible (AFAICT) to emulate the rest of the atomic
    1.39 - * operations.
    1.40 - */
    1.41 -
    1.42  /* Function prototypes */
    1.43  
    1.44  /**
    1.45 - * SDL AtomicLock.
    1.46 - * 
    1.47 - * The spin lock functions and type are required and can not be
    1.48 - * emulated because they are used in the emulation code.
    1.49 + *  \name SDL AtomicLock
    1.50 + *  
    1.51 + *  The spin lock functions and type are required and can not be
    1.52 + *  emulated because they are used in the emulation code.
    1.53   */
    1.54 +/*@{*/
    1.55  
    1.56  typedef volatile Uint32 SDL_SpinLock;
    1.57  
    1.58  /**
    1.59 - * \fn  void SDL_AtomicLock(SDL_SpinLock *lock);
    1.60 - *
    1.61 - * \brief Lock a spin lock by setting it to a none zero value.
    1.62 - *
    1.63 - * \param lock points to the lock.
    1.64 - *
    1.65 + *  \brief Lock a spin lock by setting it to a none zero value.
    1.66 + *  
    1.67 + *  \param lock Points to the lock.
    1.68   */
    1.69  extern DECLSPEC void SDLCALL SDL_AtomicLock(SDL_SpinLock *lock);
    1.70  
    1.71  /**
    1.72 - * \fn  void SDL_AtomicUnlock(SDL_SpinLock *lock);
    1.73 + *  \brief Unlock a spin lock by setting it to 0. Always returns immediately
    1.74   *
    1.75 - * \brief Unlock a spin lock by setting it to 0. Always returns immediately
    1.76 - *
    1.77 - * \param lock points to the lock.
    1.78 - *
    1.79 + *  \param lock Points to the lock.
    1.80   */
    1.81  extern DECLSPEC void SDLCALL SDL_AtomicUnlock(SDL_SpinLock *lock);
    1.82  
    1.83 -/* 32 bit atomic operations */
    1.84 +/*@}*//*SDL AtomicLock*/
    1.85  
    1.86  /**
    1.87 - * \fn  SDL_bool SDL_AtomicTestThenSet32(volatile Uint32 * ptr);
    1.88 - *
    1.89 - * \brief Check to see if *ptr == 0 and set it to 1.
    1.90 - *
    1.91 - * \return SDL_True if the value pointed to by ptr was zero and
    1.92 - * SDL_False if it was not zero
    1.93 - *
    1.94 - * \param ptr points to the value to be tested and set.
    1.95 - *
    1.96 + *  \name 32 bit atomic operations
    1.97 + */
    1.98 +/*@{*/
    1.99 +
   1.100 +/**
   1.101 + *  \brief Check to see if \c *ptr == 0 and set it to 1.
   1.102 + *  
   1.103 + *  \return SDL_True if the value pointed to by \c ptr was zero and
   1.104 + *          SDL_False if it was not zero
   1.105 + *  
   1.106 + *  \param ptr Points to the value to be tested and set.
   1.107   */
   1.108  extern DECLSPEC SDL_bool SDLCALL SDL_AtomicTestThenSet32(volatile Uint32 * ptr);
   1.109  
   1.110  /**
   1.111 - * \fn  void SDL_AtomicClear32(volatile Uint32 * ptr);
   1.112 - *
   1.113 - * \brief set the value pointed to by ptr to be zero.
   1.114 - *
   1.115 - * \param ptr address of the value to be set to zero
   1.116 - *
   1.117 + *  \brief Set the value pointed to by \c ptr to be zero.
   1.118 + *  
   1.119 + *  \param ptr Address of the value to be set to zero
   1.120   */
   1.121  extern DECLSPEC void SDLCALL SDL_AtomicClear32(volatile Uint32 * ptr);
   1.122  
   1.123  /**
   1.124 - * \fn  Uint32 SDL_AtomicFetchThenIncrement32(volatile Uint32 * ptr);
   1.125 - *
   1.126 - * \brief fetch the current value of *ptr and then increment that
   1.127 - * value in place.
   1.128 - *
   1.129 - * \return the value before it was incremented.
   1.130 - *
   1.131 - * \param ptr address of the value to fetch and increment
   1.132 - *
   1.133 + *  \brief Fetch the current value of \c *ptr and then increment that
   1.134 + *         value in place.
   1.135 + *  
   1.136 + *  \return The value before it was incremented.
   1.137 + *  
   1.138 + *  \param ptr Address of the value to fetch and increment
   1.139   */
   1.140  extern DECLSPEC Uint32 SDLCALL SDL_AtomicFetchThenIncrement32(volatile Uint32 * ptr);
   1.141  
   1.142  /**
   1.143 - * \fn  Uint32 SDL_AtomicFetchThenDecrement32(volatile Uint32 * ptr);
   1.144 - *
   1.145 - * \brief fetch *ptr and then decrement the value in place.
   1.146 - *
   1.147 - * \return the value before it was decremented.
   1.148 - *
   1.149 - * \param ptr address of the value to fetch and drement
   1.150 - *
   1.151 + *  \brief Fetch \c *ptr and then decrement the value in place.
   1.152 + *  
   1.153 + *  \return The value before it was decremented.
   1.154 + *  
   1.155 + *  \param ptr Address of the value to fetch and drement
   1.156   */
   1.157  extern DECLSPEC Uint32 SDLCALL SDL_AtomicFetchThenDecrement32(volatile Uint32 * ptr);
   1.158  
   1.159  /**
   1.160 - * \fn  Uint32 SDL_AtomicFetchThenAdd32(volatile Uint32 * ptr, Uint32 value);
   1.161 - *
   1.162 - * \brief fetch the current value at ptr and then add value to *ptr.
   1.163 - *
   1.164 - * \return *ptr before the addition took place.
   1.165 - *
   1.166 - * \param ptr the address of data we are changing.
   1.167 - * \param value the value to add to *ptr. 
   1.168 - *
   1.169 + *  \brief Fetch the current value at \c ptr and then add \c value to \c *ptr.
   1.170 + *  
   1.171 + *  \return \c *ptr before the addition took place.
   1.172 + *  
   1.173 + *  \param ptr The address of data we are changing.
   1.174 + *  \param value The value to add to \c *ptr. 
   1.175   */
   1.176  extern DECLSPEC Uint32 SDLCALL SDL_AtomicFetchThenAdd32(volatile Uint32 * ptr, Uint32 value);
   1.177  
   1.178  /**
   1.179 - * \fn  Uint32 SDL_AtomicFetchThenSubtract32(volatile Uint32 * ptr, Uint32 value);
   1.180 - *
   1.181 - * \brief Fetch *ptr and then subtract value from it.
   1.182 - *
   1.183 - * \return *ptr before the subtraction took place.
   1.184 - *
   1.185 - * \param ptr the address of the data being changed.
   1.186 - * \param value the value to subtract from *ptr.
   1.187 - *
   1.188 + *  \brief Fetch \c *ptr and then subtract \c value from it.
   1.189 + *  
   1.190 + *  \return \c *ptr before the subtraction took place.
   1.191 + *  
   1.192 + *  \param ptr The address of the data being changed.
   1.193 + *  \param value The value to subtract from \c *ptr.
   1.194   */
   1.195  extern DECLSPEC Uint32 SDLCALL SDL_AtomicFetchThenSubtract32(volatile Uint32 * ptr, Uint32 value);
   1.196  
   1.197  /**
   1.198 - * \fn  Uint32 SDL_AtomicIncrementThenFetch32(volatile Uint32 * ptr);
   1.199 - *
   1.200 - * \brief Add one to the data pointed to by ptr and return that value.
   1.201 - *
   1.202 - * \return the incremented value.
   1.203 - *
   1.204 - * \param ptr address of the data to increment.
   1.205 - *
   1.206 + *  \brief Add one to the data pointed to by \c ptr and return that value.
   1.207 + *  
   1.208 + *  \return The incremented value.
   1.209 + *  
   1.210 + *  \param ptr The address of the data to increment.
   1.211   */
   1.212  extern DECLSPEC Uint32 SDLCALL SDL_AtomicIncrementThenFetch32(volatile Uint32 * ptr);
   1.213  
   1.214  /**
   1.215 - * \fn  Uint32 SDL_AtomicDecrementThenFetch32(volatile Uint32 * ptr);
   1.216 - *
   1.217 - * \brief Subtract one from data pointed to by ptr and return the new value.
   1.218 - *
   1.219 - * \return The decremented value.
   1.220 - *
   1.221 - * \param ptr The address of the data to decrement.
   1.222 - *
   1.223 + *  \brief Subtract one from data pointed to by \c ptr and return the new value.
   1.224 + *  
   1.225 + *  \return The decremented value.
   1.226 + *  
   1.227 + *  \param ptr The address of the data to decrement.
   1.228   */
   1.229  extern DECLSPEC Uint32 SDLCALL SDL_AtomicDecrementThenFetch32(volatile Uint32 * ptr);
   1.230  
   1.231  /**
   1.232 - * \fn  Uint32 SDL_AtomicAddThenFetch32(volatile Uint32 * ptr, Uint32 value);
   1.233 - *
   1.234 - * \brief Add value to the data pointed to by ptr and return result.
   1.235 - *
   1.236 - * \return The sum of *ptr and value.
   1.237 - *
   1.238 - * \param ptr The address of the data to be modified.
   1.239 - * \param value The value to be added.
   1.240 - *
   1.241 + *  \brief Add \c value to the data pointed to by \c ptr and return result.
   1.242 + *  
   1.243 + *  \return The sum of \c *ptr and \c value.
   1.244 + *  
   1.245 + *  \param ptr The address of the data to be modified.
   1.246 + *  \param value The value to be added.
   1.247   */
   1.248  extern DECLSPEC Uint32 SDLCALL SDL_AtomicAddThenFetch32(volatile Uint32 * ptr, Uint32 value);
   1.249  
   1.250  /**
   1.251 - * \fn  Uint32 SDL_AtomicSubtractThenFetch32(volatile Uint32 * ptr, Uint32 value);
   1.252 - *
   1.253 - * \brief Subtract value from the data pointed to by ptr and return the result.
   1.254 - *
   1.255 - * \return the difference between *ptr and value.
   1.256 - *
   1.257 - * \param ptr The address of the data to be modified.
   1.258 - * \param value The value to be subtracted.
   1.259 - *
   1.260 + *  \brief Subtract \c value from the data pointed to by \c ptr and return the result.
   1.261 + *  
   1.262 + *  \return The difference between \c *ptr and \c value.
   1.263 + *  
   1.264 + *  \param ptr The address of the data to be modified.
   1.265 + *  \param value The value to be subtracted.
   1.266   */
   1.267  extern DECLSPEC Uint32 SDLCALL SDL_AtomicSubtractThenFetch32(volatile Uint32 * ptr, Uint32 value);
   1.268  
   1.269 -/* 64 bit atomic operations */
   1.270 +/*@}*//*32 bit atomic operations*/
   1.271 +
   1.272 +/**
   1.273 + *  \name 64 bit atomic operations
   1.274 + */
   1.275 +/*@{*/
   1.276  #ifdef SDL_HAS_64BIT_TYPE
   1.277  
   1.278  extern DECLSPEC SDL_bool SDLCALL SDL_AtomicTestThenSet64(volatile Uint64 * ptr);
   1.279 @@ -227,6 +200,8 @@
   1.280  extern DECLSPEC Uint64 SDLCALL SDL_AtomicSubtractThenFetch64(volatile Uint64 * ptr, Uint64 value);
   1.281  #endif /*  SDL_HAS_64BIT_TYPE */
   1.282  
   1.283 +/*@}*//*64 bit atomic operations*/
   1.284 +
   1.285  /* Ends C function definitions when using C++ */
   1.286  #ifdef __cplusplus
   1.287  /* *INDENT-OFF* */