include/SDL_atomic.h
author Bob Pendleton <bob@pendleton.com>
Tue, 11 Aug 2009 21:27:19 +0000
changeset 3237 916f396fe65d
parent 3216 48a80f2a7ff2
child 3261 72b542f34739
permissions -rw-r--r--
Start of redesign, getting rid of 8 and 16 bit operations in .h and test files.
     1 /*
     2     SDL - Simple DirectMedia Layer
     3     Copyright (C) 1997-2006 Sam Lantinga
     4 
     5     This library is free software; you can redistribute it and/or
     6     modify it under the terms of the GNU Lesser General Public
     7     License as published by the Free Software Foundation; either
     8     version 2.1 of the License, or (at your option) any later version.
     9 
    10     This library is distributed in the hope that it will be useful,
    11     but WITHOUT ANY WARRANTY; without even the implied warranty of
    12     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    13     Lesser General Public License for more details.
    14 
    15     You should have received a copy of the GNU Lesser General Public
    16     License along with this library; if not, write to the Free Software
    17     Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
    18 
    19     Sam Lantinga
    20     slouken@libsdl.org
    21  */
    22 
    23 /**
    24  * \file SDL_atomic.h
    25  *
    26  * Atomic operations.
    27  */
    28 
    29 #ifndef _SDL_atomic_h_
    30 #define _SDL_atomic_h_
    31 
    32 #include "SDL_stdinc.h"
    33 #include "SDL_platform.h"
    34 
    35 #include "begin_code.h"
    36 
    37 /* Set up for C function definitions, even when using C++ */
    38 #ifdef __cplusplus
    39 /* *INDENT-OFF* */
    40 extern "C" {
    41 /* *INDENT-ON* */
    42 #endif
    43 
    44 /**
    45  * These operations may, or may not, actually be implemented using
    46  * processor specific atomic operations. When possible they are
    47  * implemented as true processor specific atomic operations. When that
    48  * is not possible the are implemented using locks that *do* use the
    49  * available atomic operations. In rare cases they may be implemented
    50  * using SDL's mutex fuctions.
    51  */
    52 
    53 /* Function prototypes */
    54 
    55 /* 32 bit atomic operations */
    56 
    57 /**
    58  * \fn int SDL_AtomicExchange32(volatile Uint32 * ptr, Uint32 value)
    59  *
    60  * \brief Atomically exchange two 32 bit values.
    61  *
    62  * \return the value point to by ptr.
    63  *
    64  * \param ptr points to the value to be fetched from *ptr.  
    65  * \param value is value to be stored at *ptr.
    66  *
    67  * The current value stored at *ptr is returned and it is replaced
    68  * with value. This function can be used to implement SDL_TestThenSet.
    69  *
    70  */
    71 extern DECLSPEC Uint32 SDLCALL SDL_AtomicExchange32(volatile Uint32 * ptr, Uint32 value);
    72 
    73 /**
    74  * \fn int SDL_AtomicCompareThenSet32(volatile Uint32 * ptr, Uint32 oldvalue, Uint32 newvalue)
    75  *
    76  * \brief If *ptr == oldvalue then replace the contents of *ptr by new value. 
    77  *
    78  * \return true if the newvalue was stored.
    79  *
    80  * \param *ptr is the value to be compared and replaced.
    81  * \param oldvalue is value to be compared to *ptr.
    82  * \param newvalue is value to be stored at *ptr.
    83  *
    84  */
    85 extern DECLSPEC SDL_bool SDLCALL SDL_AtomicCompareThenSet32(volatile Uint32 * ptr,
    86                                                             Uint32 oldvalue, Uint32 newvalue);
    87 /**
    88  * \fn  SDL_bool SDL_AtomicTestThenSet32(volatile Uint32 * ptr);
    89  *
    90  * \brief Check to see if *ptr == 0 and set it to non-zero.
    91  *
    92  * \return SDL_True if the value pointed to by ptr was zero and
    93  * SDL_False if it was not zero
    94  *
    95  * \param ptr points to the value to be tested and set.
    96  *
    97  */
    98 extern DECLSPEC SDL_bool SDLCALL SDL_AtomicTestThenSet32(volatile Uint32 * ptr);
    99 
   100 /**
   101  * \fn  void SDL_AtomicClear32(volatile Uint32 * ptr);
   102  *
   103  * \brief set the value pointed to by ptr to be zero.
   104  *
   105  * \param ptr address of the value to be set to zero
   106  *
   107  */
   108 extern DECLSPEC void SDLCALL SDL_AtomicClear32(volatile Uint32 * ptr);
   109 
   110 /**
   111  * \fn  Uint32 SDL_AtomicFetchThenIncrement32(volatile Uint32 * ptr);
   112  *
   113  * \brief fetch the current value of *ptr and then increment that
   114  * value in place.
   115  *
   116  * \return the value before it was incremented.
   117  *
   118  * \param ptr address of the value to fetch and increment
   119  *
   120  */
   121 extern DECLSPEC Uint32 SDLCALL SDL_AtomicFetchThenIncrement32(volatile Uint32 * ptr);
   122 
   123 /**
   124  * \fn  Uint32 SDL_AtomicFetchThenDecrement32(volatile Uint32 * ptr);
   125  *
   126  * \brief fetch *ptr and then decrement the value in place.
   127  *
   128  * \return the value before it was decremented.
   129  *
   130  * \param ptr address of the value to fetch and drement
   131  *
   132  */
   133 extern DECLSPEC Uint32 SDLCALL SDL_AtomicFetchThenDecrement32(volatile Uint32 * ptr);
   134 
   135 /**
   136  * \fn  Uint32 SDL_AtomicFetchThenAdd32(volatile Uint32 * ptr, Uint32 value);
   137  *
   138  * \brief fetch the current value at ptr and then add value to *ptr.
   139  *
   140  * \return *ptr before the addition took place.
   141  *
   142  * \param ptr the address of data we are changing.
   143  * \param value the value to add to *ptr. 
   144  *
   145  */
   146 extern DECLSPEC Uint32 SDLCALL SDL_AtomicFetchThenAdd32(volatile Uint32 * ptr, Uint32 value);
   147 
   148 /**
   149  * \fn  Uint32 SDL_AtomicFetchThenSubtract32(volatile Uint32 * ptr, Uint32 value);
   150  *
   151  * \brief Fetch *ptr and then subtract value from it.
   152  *
   153  * \return *ptr before the subtraction took place.
   154  *
   155  * \param ptr the address of the data being changed.
   156  * \param value the value to subtract from *ptr.
   157  *
   158  */
   159 extern DECLSPEC Uint32 SDLCALL SDL_AtomicFetchThenSubtract32(volatile Uint32 * ptr, Uint32 value);
   160 
   161 /**
   162  * \fn  Uint32 SDL_AtomicIncrementThenFetch32(volatile Uint32 * ptr);
   163  *
   164  * \brief Add one to the data pointed to by ptr and return that value.
   165  *
   166  * \return the incremented value.
   167  *
   168  * \param ptr address of the data to increment.
   169  *
   170  */
   171 extern DECLSPEC Uint32 SDLCALL SDL_AtomicIncrementThenFetch32(volatile Uint32 * ptr);
   172 
   173 /**
   174  * \fn  Uint32 SDL_AtomicDecrementThenFetch32(volatile Uint32 * ptr);
   175  *
   176  * \brief Subtract one from data pointed to by ptr and return the new value.
   177  *
   178  * \return The decremented value.
   179  *
   180  * \param ptr The address of the data to decrement.
   181  *
   182  */
   183 extern DECLSPEC Uint32 SDLCALL SDL_AtomicDecrementThenFetch32(volatile Uint32 * ptr);
   184 
   185 /**
   186  * \fn  Uint32 SDL_AtomicAddThenFetch32(volatile Uint32 * ptr, Uint32 value);
   187  *
   188  * \brief Add value to the data pointed to by ptr and return result.
   189  *
   190  * \return The sum of *ptr and value.
   191  *
   192  * \param ptr The address of the data to be modified.
   193  * \param value The value to be added.
   194  *
   195  */
   196 extern DECLSPEC Uint32 SDLCALL SDL_AtomicAddThenFetch32(volatile Uint32 * ptr, Uint32 value);
   197 
   198 /**
   199  * \fn  Uint32 SDL_AtomicSubtractThenFetch32(volatile Uint32 * ptr, Uint32 value);
   200  *
   201  * \brief Subtract value from the data pointed to by ptr and return the result.
   202  *
   203  * \return the difference between *ptr and value.
   204  *
   205  * \param ptr The address of the data to be modified.
   206  * \param value The value to be subtracted.
   207  *
   208  */
   209 extern DECLSPEC Uint32 SDLCALL SDL_AtomicSubtractThenFetch32(volatile Uint32 * ptr, Uint32 value);
   210 
   211 /* 64 bit atomic operations */
   212 #ifdef SDL_HAS_64BIT_TYPE
   213 
   214 extern DECLSPEC Uint64 SDLCALL SDL_AtomicExchange64(volatile Uint64 * ptr, Uint64 value);
   215 extern DECLSPEC SDL_bool SDLCALL SDL_AtomicCompareThenSet64(volatile Uint64 * ptr,
   216                                                             Uint64 oldvalue, Uint64 newvalue);
   217 extern DECLSPEC SDL_bool SDLCALL SDL_AtomicTestThenSet64(volatile Uint64 * ptr);
   218 extern DECLSPEC void SDLCALL SDL_AtomicClear64(volatile Uint64 * ptr);
   219 extern DECLSPEC Uint64 SDLCALL SDL_AtomicFetchThenIncrement64(volatile Uint64 * ptr);
   220 extern DECLSPEC Uint64 SDLCALL SDL_AtomicFetchThenDecrement64(volatile Uint64 * ptr);
   221 extern DECLSPEC Uint64 SDLCALL SDL_AtomicFetchThenAdd64(volatile Uint64 * ptr, Uint64 value);
   222 extern DECLSPEC Uint64 SDLCALL SDL_AtomicFetchThenSubtract64(volatile Uint64 * ptr, Uint64 value);
   223 extern DECLSPEC Uint64 SDLCALL SDL_AtomicIncrementThenFetch64(volatile Uint64 * ptr);
   224 extern DECLSPEC Uint64 SDLCALL SDL_AtomicDecrementThenFetch64(volatile Uint64 * ptr);
   225 extern DECLSPEC Uint64 SDLCALL SDL_AtomicAddThenFetch64(volatile Uint64 * ptr, Uint64 value);
   226 extern DECLSPEC Uint64 SDLCALL SDL_AtomicSubtractThenFetch64(volatile Uint64 * ptr, Uint64 value);
   227 #endif /*  SDL_HAS_64BIT_TYPE */
   228 
   229 /* Ends C function definitions when using C++ */
   230 #ifdef __cplusplus
   231 /* *INDENT-OFF* */
   232 }
   233 /* *INDENT-ON* */
   234 #endif
   235 
   236 #include "close_code.h"
   237 
   238 #endif /* _SDL_atomic_h_ */
   239 
   240 /* vi: set ts=4 sw=4 expandtab: */