include/SDL_atomic.h
author Bob Pendleton <bob@pendleton.com>
Thu, 17 Sep 2009 20:35:12 +0000
changeset 3261 72b542f34739
parent 3237 916f396fe65d
child 3407 d3baf5ac4e37
permissions -rw-r--r--
The new, cleaner, version of the atomic operations. The dummy code is what you should start working with to port atomic ops.
The linux code appears to be complete and *should* be the base of all Unix and GCC based versions. The macosx and win32 versions
are currently just copies of the dummy code. I will begin working on the windows version as soon as this check in is done. I
need someone to work on the Mac OS X version.

I'm afraid that this check in will break QNX (Sorry!)
     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     Contributed by Bob Pendleton, bob@pendleton.com
    23  */
    24 
    25 /**
    26  * \file SDL_atomic.h
    27  *
    28  * Atomic operations.
    29  */
    30 
    31 #ifndef _SDL_atomic_h_
    32 #define _SDL_atomic_h_
    33 
    34 #include "SDL_stdinc.h"
    35 #include "SDL_platform.h"
    36 
    37 #include "begin_code.h"
    38 
    39 /* Set up for C function definitions, even when using C++ */
    40 #ifdef __cplusplus
    41 /* *INDENT-OFF* */
    42 extern "C" {
    43 /* *INDENT-ON* */
    44 #endif
    45 
    46 /**
    47  * These operations may, or may not, actually be implemented using
    48  * processor specific atomic operations. When possible they are
    49  * implemented as true processor specific atomic operations. When that
    50  * is not possible the are implemented using locks that *do* use the
    51  * available atomic operations.
    52  *
    53  * At the very minimum spin locks must be implemented. Without spin
    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  */
    87 extern DECLSPEC void SDLCALL SDL_AtomicUnlock(SDL_SpinLock *lock);
    88 
    89 /* 32 bit atomic operations */
    90 
    91 /**
    92  * \fn  SDL_bool SDL_AtomicTestThenSet32(volatile Uint32 * ptr);
    93  *
    94  * \brief Check to see if *ptr == 0 and set it to 1.
    95  *
    96  * \return SDL_True if the value pointed to by ptr was zero and
    97  * SDL_False if it was not zero
    98  *
    99  * \param ptr points to the value to be tested and set.
   100  *
   101  */
   102 extern DECLSPEC SDL_bool SDLCALL SDL_AtomicTestThenSet32(volatile Uint32 * ptr);
   103 
   104 /**
   105  * \fn  void SDL_AtomicClear32(volatile Uint32 * ptr);
   106  *
   107  * \brief set the value pointed to by ptr to be zero.
   108  *
   109  * \param ptr address of the value to be set to zero
   110  *
   111  */
   112 extern DECLSPEC void SDLCALL SDL_AtomicClear32(volatile Uint32 * ptr);
   113 
   114 /**
   115  * \fn  Uint32 SDL_AtomicFetchThenIncrement32(volatile Uint32 * ptr);
   116  *
   117  * \brief fetch the current value of *ptr and then increment that
   118  * value in place.
   119  *
   120  * \return the value before it was incremented.
   121  *
   122  * \param ptr address of the value to fetch and increment
   123  *
   124  */
   125 extern DECLSPEC Uint32 SDLCALL SDL_AtomicFetchThenIncrement32(volatile Uint32 * ptr);
   126 
   127 /**
   128  * \fn  Uint32 SDL_AtomicFetchThenDecrement32(volatile Uint32 * ptr);
   129  *
   130  * \brief fetch *ptr and then decrement the value in place.
   131  *
   132  * \return the value before it was decremented.
   133  *
   134  * \param ptr address of the value to fetch and drement
   135  *
   136  */
   137 extern DECLSPEC Uint32 SDLCALL SDL_AtomicFetchThenDecrement32(volatile Uint32 * ptr);
   138 
   139 /**
   140  * \fn  Uint32 SDL_AtomicFetchThenAdd32(volatile Uint32 * ptr, Uint32 value);
   141  *
   142  * \brief fetch the current value at ptr and then add value to *ptr.
   143  *
   144  * \return *ptr before the addition took place.
   145  *
   146  * \param ptr the address of data we are changing.
   147  * \param value the value to add to *ptr. 
   148  *
   149  */
   150 extern DECLSPEC Uint32 SDLCALL SDL_AtomicFetchThenAdd32(volatile Uint32 * ptr, Uint32 value);
   151 
   152 /**
   153  * \fn  Uint32 SDL_AtomicFetchThenSubtract32(volatile Uint32 * ptr, Uint32 value);
   154  *
   155  * \brief Fetch *ptr and then subtract value from it.
   156  *
   157  * \return *ptr before the subtraction took place.
   158  *
   159  * \param ptr the address of the data being changed.
   160  * \param value the value to subtract from *ptr.
   161  *
   162  */
   163 extern DECLSPEC Uint32 SDLCALL SDL_AtomicFetchThenSubtract32(volatile Uint32 * ptr, Uint32 value);
   164 
   165 /**
   166  * \fn  Uint32 SDL_AtomicIncrementThenFetch32(volatile Uint32 * ptr);
   167  *
   168  * \brief Add one to the data pointed to by ptr and return that value.
   169  *
   170  * \return the incremented value.
   171  *
   172  * \param ptr address of the data to increment.
   173  *
   174  */
   175 extern DECLSPEC Uint32 SDLCALL SDL_AtomicIncrementThenFetch32(volatile Uint32 * ptr);
   176 
   177 /**
   178  * \fn  Uint32 SDL_AtomicDecrementThenFetch32(volatile Uint32 * ptr);
   179  *
   180  * \brief Subtract one from data pointed to by ptr and return the new value.
   181  *
   182  * \return The decremented value.
   183  *
   184  * \param ptr The address of the data to decrement.
   185  *
   186  */
   187 extern DECLSPEC Uint32 SDLCALL SDL_AtomicDecrementThenFetch32(volatile Uint32 * ptr);
   188 
   189 /**
   190  * \fn  Uint32 SDL_AtomicAddThenFetch32(volatile Uint32 * ptr, Uint32 value);
   191  *
   192  * \brief Add value to the data pointed to by ptr and return result.
   193  *
   194  * \return The sum of *ptr and value.
   195  *
   196  * \param ptr The address of the data to be modified.
   197  * \param value The value to be added.
   198  *
   199  */
   200 extern DECLSPEC Uint32 SDLCALL SDL_AtomicAddThenFetch32(volatile Uint32 * ptr, Uint32 value);
   201 
   202 /**
   203  * \fn  Uint32 SDL_AtomicSubtractThenFetch32(volatile Uint32 * ptr, Uint32 value);
   204  *
   205  * \brief Subtract value from the data pointed to by ptr and return the result.
   206  *
   207  * \return the difference between *ptr and value.
   208  *
   209  * \param ptr The address of the data to be modified.
   210  * \param value The value to be subtracted.
   211  *
   212  */
   213 extern DECLSPEC Uint32 SDLCALL SDL_AtomicSubtractThenFetch32(volatile Uint32 * ptr, Uint32 value);
   214 
   215 /* 64 bit atomic operations */
   216 #ifdef SDL_HAS_64BIT_TYPE
   217 
   218 extern DECLSPEC SDL_bool SDLCALL SDL_AtomicTestThenSet64(volatile Uint64 * ptr);
   219 extern DECLSPEC void SDLCALL SDL_AtomicClear64(volatile Uint64 * ptr);
   220 extern DECLSPEC Uint64 SDLCALL SDL_AtomicFetchThenIncrement64(volatile Uint64 * ptr);
   221 extern DECLSPEC Uint64 SDLCALL SDL_AtomicFetchThenDecrement64(volatile Uint64 * ptr);
   222 extern DECLSPEC Uint64 SDLCALL SDL_AtomicFetchThenAdd64(volatile Uint64 * ptr, Uint64 value);
   223 extern DECLSPEC Uint64 SDLCALL SDL_AtomicFetchThenSubtract64(volatile Uint64 * ptr, Uint64 value);
   224 extern DECLSPEC Uint64 SDLCALL SDL_AtomicIncrementThenFetch64(volatile Uint64 * ptr);
   225 extern DECLSPEC Uint64 SDLCALL SDL_AtomicDecrementThenFetch64(volatile Uint64 * ptr);
   226 extern DECLSPEC Uint64 SDLCALL SDL_AtomicAddThenFetch64(volatile Uint64 * ptr, Uint64 value);
   227 extern DECLSPEC Uint64 SDLCALL SDL_AtomicSubtractThenFetch64(volatile Uint64 * ptr, Uint64 value);
   228 #endif /*  SDL_HAS_64BIT_TYPE */
   229 
   230 /* Ends C function definitions when using C++ */
   231 #ifdef __cplusplus
   232 /* *INDENT-OFF* */
   233 }
   234 /* *INDENT-ON* */
   235 #endif
   236 
   237 #include "close_code.h"
   238 
   239 #endif /* _SDL_atomic_h_ */
   240 
   241 /* vi: set ts=4 sw=4 expandtab: */