include/SDL_atomic.h
changeset 3407 d3baf5ac4e37
parent 3261 72b542f34739
child 3697 f7b03b6838cb
equal deleted inserted replaced
3406:8ae607392409 3407:d3baf5ac4e37
    21 
    21 
    22     Contributed by Bob Pendleton, bob@pendleton.com
    22     Contributed by Bob Pendleton, bob@pendleton.com
    23  */
    23  */
    24 
    24 
    25 /**
    25 /**
    26  * \file SDL_atomic.h
    26  *  \file SDL_atomic.h
    27  *
    27  *  
    28  * Atomic operations.
    28  *  Atomic operations.
       
    29  *  
       
    30  *  These operations may, or may not, actually be implemented using
       
    31  *  processor specific atomic operations. When possible they are
       
    32  *  implemented as true processor specific atomic operations. When that
       
    33  *  is not possible the are implemented using locks that *do* use the
       
    34  *  available atomic operations.
       
    35  *  
       
    36  *  At the very minimum spin locks must be implemented. Without spin
       
    37  *  locks it is not possible (AFAICT) to emulate the rest of the atomic
       
    38  *  operations.
    29  */
    39  */
    30 
    40 
    31 #ifndef _SDL_atomic_h_
    41 #ifndef _SDL_atomic_h_
    32 #define _SDL_atomic_h_
    42 #define _SDL_atomic_h_
    33 
    43 
    41 /* *INDENT-OFF* */
    51 /* *INDENT-OFF* */
    42 extern "C" {
    52 extern "C" {
    43 /* *INDENT-ON* */
    53 /* *INDENT-ON* */
    44 #endif
    54 #endif
    45 
    55 
    46 /**
    56 /* Function prototypes */
    47  * These operations may, or may not, actually be implemented using
    57 
    48  * processor specific atomic operations. When possible they are
    58 /**
    49  * implemented as true processor specific atomic operations. When that
    59  *  \name SDL AtomicLock
    50  * is not possible the are implemented using locks that *do* use the
    60  *  
    51  * available atomic operations.
    61  *  The spin lock functions and type are required and can not be
       
    62  *  emulated because they are used in the emulation code.
       
    63  */
       
    64 /*@{*/
       
    65 
       
    66 typedef volatile Uint32 SDL_SpinLock;
       
    67 
       
    68 /**
       
    69  *  \brief Lock a spin lock by setting it to a none zero value.
       
    70  *  
       
    71  *  \param lock Points to the lock.
       
    72  */
       
    73 extern DECLSPEC void SDLCALL SDL_AtomicLock(SDL_SpinLock *lock);
       
    74 
       
    75 /**
       
    76  *  \brief Unlock a spin lock by setting it to 0. Always returns immediately
    52  *
    77  *
    53  * At the very minimum spin locks must be implemented. Without spin
    78  *  \param lock Points to the lock.
    54  * locks it is not possible (AFAICT) to emulate the rest of the atomic
       
    55  * operations.
       
    56  */
       
    57 
       
    58 /* Function prototypes */
       
    59 
       
    60 /**
       
    61  * SDL AtomicLock.
       
    62  * 
       
    63  * The spin lock functions and type are required and can not be
       
    64  * emulated because they are used in the emulation code.
       
    65  */
       
    66 
       
    67 typedef volatile Uint32 SDL_SpinLock;
       
    68 
       
    69 /**
       
    70  * \fn  void SDL_AtomicLock(SDL_SpinLock *lock);
       
    71  *
       
    72  * \brief Lock a spin lock by setting it to a none zero value.
       
    73  *
       
    74  * \param lock points to the lock.
       
    75  *
       
    76  */
       
    77 extern DECLSPEC void SDLCALL SDL_AtomicLock(SDL_SpinLock *lock);
       
    78 
       
    79 /**
       
    80  * \fn  void SDL_AtomicUnlock(SDL_SpinLock *lock);
       
    81  *
       
    82  * \brief Unlock a spin lock by setting it to 0. Always returns immediately
       
    83  *
       
    84  * \param lock points to the lock.
       
    85  *
       
    86  */
    79  */
    87 extern DECLSPEC void SDLCALL SDL_AtomicUnlock(SDL_SpinLock *lock);
    80 extern DECLSPEC void SDLCALL SDL_AtomicUnlock(SDL_SpinLock *lock);
    88 
    81 
    89 /* 32 bit atomic operations */
    82 /*@}*//*SDL AtomicLock*/
    90 
    83 
    91 /**
    84 /**
    92  * \fn  SDL_bool SDL_AtomicTestThenSet32(volatile Uint32 * ptr);
    85  *  \name 32 bit atomic operations
    93  *
    86  */
    94  * \brief Check to see if *ptr == 0 and set it to 1.
    87 /*@{*/
    95  *
    88 
    96  * \return SDL_True if the value pointed to by ptr was zero and
    89 /**
    97  * SDL_False if it was not zero
    90  *  \brief Check to see if \c *ptr == 0 and set it to 1.
    98  *
    91  *  
    99  * \param ptr points to the value to be tested and set.
    92  *  \return SDL_True if the value pointed to by \c ptr was zero and
   100  *
    93  *          SDL_False if it was not zero
       
    94  *  
       
    95  *  \param ptr Points to the value to be tested and set.
   101  */
    96  */
   102 extern DECLSPEC SDL_bool SDLCALL SDL_AtomicTestThenSet32(volatile Uint32 * ptr);
    97 extern DECLSPEC SDL_bool SDLCALL SDL_AtomicTestThenSet32(volatile Uint32 * ptr);
   103 
    98 
   104 /**
    99 /**
   105  * \fn  void SDL_AtomicClear32(volatile Uint32 * ptr);
   100  *  \brief Set the value pointed to by \c ptr to be zero.
   106  *
   101  *  
   107  * \brief set the value pointed to by ptr to be zero.
   102  *  \param ptr Address of the value to be set to zero
   108  *
       
   109  * \param ptr address of the value to be set to zero
       
   110  *
       
   111  */
   103  */
   112 extern DECLSPEC void SDLCALL SDL_AtomicClear32(volatile Uint32 * ptr);
   104 extern DECLSPEC void SDLCALL SDL_AtomicClear32(volatile Uint32 * ptr);
   113 
   105 
   114 /**
   106 /**
   115  * \fn  Uint32 SDL_AtomicFetchThenIncrement32(volatile Uint32 * ptr);
   107  *  \brief Fetch the current value of \c *ptr and then increment that
   116  *
   108  *         value in place.
   117  * \brief fetch the current value of *ptr and then increment that
   109  *  
   118  * value in place.
   110  *  \return The value before it was incremented.
   119  *
   111  *  
   120  * \return the value before it was incremented.
   112  *  \param ptr Address of the value to fetch and increment
   121  *
       
   122  * \param ptr address of the value to fetch and increment
       
   123  *
       
   124  */
   113  */
   125 extern DECLSPEC Uint32 SDLCALL SDL_AtomicFetchThenIncrement32(volatile Uint32 * ptr);
   114 extern DECLSPEC Uint32 SDLCALL SDL_AtomicFetchThenIncrement32(volatile Uint32 * ptr);
   126 
   115 
   127 /**
   116 /**
   128  * \fn  Uint32 SDL_AtomicFetchThenDecrement32(volatile Uint32 * ptr);
   117  *  \brief Fetch \c *ptr and then decrement the value in place.
   129  *
   118  *  
   130  * \brief fetch *ptr and then decrement the value in place.
   119  *  \return The value before it was decremented.
   131  *
   120  *  
   132  * \return the value before it was decremented.
   121  *  \param ptr Address of the value to fetch and drement
   133  *
       
   134  * \param ptr address of the value to fetch and drement
       
   135  *
       
   136  */
   122  */
   137 extern DECLSPEC Uint32 SDLCALL SDL_AtomicFetchThenDecrement32(volatile Uint32 * ptr);
   123 extern DECLSPEC Uint32 SDLCALL SDL_AtomicFetchThenDecrement32(volatile Uint32 * ptr);
   138 
   124 
   139 /**
   125 /**
   140  * \fn  Uint32 SDL_AtomicFetchThenAdd32(volatile Uint32 * ptr, Uint32 value);
   126  *  \brief Fetch the current value at \c ptr and then add \c value to \c *ptr.
   141  *
   127  *  
   142  * \brief fetch the current value at ptr and then add value to *ptr.
   128  *  \return \c *ptr before the addition took place.
   143  *
   129  *  
   144  * \return *ptr before the addition took place.
   130  *  \param ptr The address of data we are changing.
   145  *
   131  *  \param value The value to add to \c *ptr. 
   146  * \param ptr the address of data we are changing.
       
   147  * \param value the value to add to *ptr. 
       
   148  *
       
   149  */
   132  */
   150 extern DECLSPEC Uint32 SDLCALL SDL_AtomicFetchThenAdd32(volatile Uint32 * ptr, Uint32 value);
   133 extern DECLSPEC Uint32 SDLCALL SDL_AtomicFetchThenAdd32(volatile Uint32 * ptr, Uint32 value);
   151 
   134 
   152 /**
   135 /**
   153  * \fn  Uint32 SDL_AtomicFetchThenSubtract32(volatile Uint32 * ptr, Uint32 value);
   136  *  \brief Fetch \c *ptr and then subtract \c value from it.
   154  *
   137  *  
   155  * \brief Fetch *ptr and then subtract value from it.
   138  *  \return \c *ptr before the subtraction took place.
   156  *
   139  *  
   157  * \return *ptr before the subtraction took place.
   140  *  \param ptr The address of the data being changed.
   158  *
   141  *  \param value The value to subtract from \c *ptr.
   159  * \param ptr the address of the data being changed.
       
   160  * \param value the value to subtract from *ptr.
       
   161  *
       
   162  */
   142  */
   163 extern DECLSPEC Uint32 SDLCALL SDL_AtomicFetchThenSubtract32(volatile Uint32 * ptr, Uint32 value);
   143 extern DECLSPEC Uint32 SDLCALL SDL_AtomicFetchThenSubtract32(volatile Uint32 * ptr, Uint32 value);
   164 
   144 
   165 /**
   145 /**
   166  * \fn  Uint32 SDL_AtomicIncrementThenFetch32(volatile Uint32 * ptr);
   146  *  \brief Add one to the data pointed to by \c ptr and return that value.
   167  *
   147  *  
   168  * \brief Add one to the data pointed to by ptr and return that value.
   148  *  \return The incremented value.
   169  *
   149  *  
   170  * \return the incremented value.
   150  *  \param ptr The address of the data to increment.
   171  *
       
   172  * \param ptr address of the data to increment.
       
   173  *
       
   174  */
   151  */
   175 extern DECLSPEC Uint32 SDLCALL SDL_AtomicIncrementThenFetch32(volatile Uint32 * ptr);
   152 extern DECLSPEC Uint32 SDLCALL SDL_AtomicIncrementThenFetch32(volatile Uint32 * ptr);
   176 
   153 
   177 /**
   154 /**
   178  * \fn  Uint32 SDL_AtomicDecrementThenFetch32(volatile Uint32 * ptr);
   155  *  \brief Subtract one from data pointed to by \c ptr and return the new value.
   179  *
   156  *  
   180  * \brief Subtract one from data pointed to by ptr and return the new value.
   157  *  \return The decremented value.
   181  *
   158  *  
   182  * \return The decremented value.
   159  *  \param ptr The address of the data to decrement.
   183  *
       
   184  * \param ptr The address of the data to decrement.
       
   185  *
       
   186  */
   160  */
   187 extern DECLSPEC Uint32 SDLCALL SDL_AtomicDecrementThenFetch32(volatile Uint32 * ptr);
   161 extern DECLSPEC Uint32 SDLCALL SDL_AtomicDecrementThenFetch32(volatile Uint32 * ptr);
   188 
   162 
   189 /**
   163 /**
   190  * \fn  Uint32 SDL_AtomicAddThenFetch32(volatile Uint32 * ptr, Uint32 value);
   164  *  \brief Add \c value to the data pointed to by \c ptr and return result.
   191  *
   165  *  
   192  * \brief Add value to the data pointed to by ptr and return result.
   166  *  \return The sum of \c *ptr and \c value.
   193  *
   167  *  
   194  * \return The sum of *ptr and value.
   168  *  \param ptr The address of the data to be modified.
   195  *
   169  *  \param value The value to be added.
   196  * \param ptr The address of the data to be modified.
       
   197  * \param value The value to be added.
       
   198  *
       
   199  */
   170  */
   200 extern DECLSPEC Uint32 SDLCALL SDL_AtomicAddThenFetch32(volatile Uint32 * ptr, Uint32 value);
   171 extern DECLSPEC Uint32 SDLCALL SDL_AtomicAddThenFetch32(volatile Uint32 * ptr, Uint32 value);
   201 
   172 
   202 /**
   173 /**
   203  * \fn  Uint32 SDL_AtomicSubtractThenFetch32(volatile Uint32 * ptr, Uint32 value);
   174  *  \brief Subtract \c value from the data pointed to by \c ptr and return the result.
   204  *
   175  *  
   205  * \brief Subtract value from the data pointed to by ptr and return the result.
   176  *  \return The difference between \c *ptr and \c value.
   206  *
   177  *  
   207  * \return the difference between *ptr and value.
   178  *  \param ptr The address of the data to be modified.
   208  *
   179  *  \param value The value to be subtracted.
   209  * \param ptr The address of the data to be modified.
       
   210  * \param value The value to be subtracted.
       
   211  *
       
   212  */
   180  */
   213 extern DECLSPEC Uint32 SDLCALL SDL_AtomicSubtractThenFetch32(volatile Uint32 * ptr, Uint32 value);
   181 extern DECLSPEC Uint32 SDLCALL SDL_AtomicSubtractThenFetch32(volatile Uint32 * ptr, Uint32 value);
   214 
   182 
   215 /* 64 bit atomic operations */
   183 /*@}*//*32 bit atomic operations*/
       
   184 
       
   185 /**
       
   186  *  \name 64 bit atomic operations
       
   187  */
       
   188 /*@{*/
   216 #ifdef SDL_HAS_64BIT_TYPE
   189 #ifdef SDL_HAS_64BIT_TYPE
   217 
   190 
   218 extern DECLSPEC SDL_bool SDLCALL SDL_AtomicTestThenSet64(volatile Uint64 * ptr);
   191 extern DECLSPEC SDL_bool SDLCALL SDL_AtomicTestThenSet64(volatile Uint64 * ptr);
   219 extern DECLSPEC void SDLCALL SDL_AtomicClear64(volatile Uint64 * ptr);
   192 extern DECLSPEC void SDLCALL SDL_AtomicClear64(volatile Uint64 * ptr);
   220 extern DECLSPEC Uint64 SDLCALL SDL_AtomicFetchThenIncrement64(volatile Uint64 * ptr);
   193 extern DECLSPEC Uint64 SDLCALL SDL_AtomicFetchThenIncrement64(volatile Uint64 * ptr);
   225 extern DECLSPEC Uint64 SDLCALL SDL_AtomicDecrementThenFetch64(volatile Uint64 * ptr);
   198 extern DECLSPEC Uint64 SDLCALL SDL_AtomicDecrementThenFetch64(volatile Uint64 * ptr);
   226 extern DECLSPEC Uint64 SDLCALL SDL_AtomicAddThenFetch64(volatile Uint64 * ptr, Uint64 value);
   199 extern DECLSPEC Uint64 SDLCALL SDL_AtomicAddThenFetch64(volatile Uint64 * ptr, Uint64 value);
   227 extern DECLSPEC Uint64 SDLCALL SDL_AtomicSubtractThenFetch64(volatile Uint64 * ptr, Uint64 value);
   200 extern DECLSPEC Uint64 SDLCALL SDL_AtomicSubtractThenFetch64(volatile Uint64 * ptr, Uint64 value);
   228 #endif /*  SDL_HAS_64BIT_TYPE */
   201 #endif /*  SDL_HAS_64BIT_TYPE */
   229 
   202 
       
   203 /*@}*//*64 bit atomic operations*/
       
   204 
   230 /* Ends C function definitions when using C++ */
   205 /* Ends C function definitions when using C++ */
   231 #ifdef __cplusplus
   206 #ifdef __cplusplus
   232 /* *INDENT-OFF* */
   207 /* *INDENT-OFF* */
   233 }
   208 }
   234 /* *INDENT-ON* */
   209 /* *INDENT-ON* */