include/SDL_mutex.h
author Sam Lantinga <slouken@libsdl.org>
Wed, 01 Feb 2006 06:32:25 +0000
changeset 1312 c9b51268668f
parent 1263 3bdcef7e1c90
child 1356 67114343400d
permissions -rw-r--r--
Updated copyright information and removed rcs id lines (problematic in branch merges)
I batch edited these files, so please let me know if I've accidentally removed anybody's
credit here.
     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 #ifndef _SDL_mutex_h
    24 #define _SDL_mutex_h
    25 
    26 /* Functions to provide thread synchronization primitives
    27 
    28 	These are independent of the other SDL routines.
    29 */
    30 
    31 #include "SDL_main.h"
    32 #include "SDL_types.h"
    33 
    34 #include "begin_code.h"
    35 /* Set up for C function definitions, even when using C++ */
    36 #ifdef __cplusplus
    37 extern "C" {
    38 #endif
    39 
    40 /* Synchronization functions which can time out return this value
    41    if they time out.
    42 */
    43 #define SDL_MUTEX_TIMEDOUT	1
    44 
    45 /* This is the timeout value which corresponds to never time out */
    46 #define SDL_MUTEX_MAXWAIT	(~(Uint32)0)
    47 
    48 
    49 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
    50 /* Mutex functions                                               */
    51 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
    52 
    53 /* The SDL mutex structure, defined in SDL_mutex.c */
    54 struct SDL_mutex;
    55 typedef struct SDL_mutex SDL_mutex;
    56 
    57 /* Create a mutex, initialized unlocked */
    58 extern DECLSPEC SDL_mutex * SDLCALL SDL_CreateMutex(void);
    59 
    60 /* Lock the mutex  (Returns 0, or -1 on error) */
    61 #define SDL_LockMutex(m)	SDL_mutexP(m)
    62 extern DECLSPEC int SDLCALL SDL_mutexP(SDL_mutex *mutex);
    63 
    64 /* Unlock the mutex  (Returns 0, or -1 on error)
    65    It is an error to unlock a mutex that has not been locked by
    66    the current thread, and doing so results in undefined behavior.
    67  */
    68 #define SDL_UnlockMutex(m)	SDL_mutexV(m)
    69 extern DECLSPEC int SDLCALL SDL_mutexV(SDL_mutex *mutex);
    70 
    71 /* Destroy a mutex */
    72 extern DECLSPEC void SDLCALL SDL_DestroyMutex(SDL_mutex *mutex);
    73 
    74 
    75 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
    76 /* Semaphore functions                                           */
    77 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
    78 
    79 /* The SDL semaphore structure, defined in SDL_sem.c */
    80 struct SDL_semaphore;
    81 typedef struct SDL_semaphore SDL_sem;
    82 
    83 /* Create a semaphore, initialized with value, returns NULL on failure. */
    84 extern DECLSPEC SDL_sem * SDLCALL SDL_CreateSemaphore(Uint32 initial_value);
    85 
    86 /* Destroy a semaphore */
    87 extern DECLSPEC void SDLCALL SDL_DestroySemaphore(SDL_sem *sem);
    88 
    89 /* This function suspends the calling thread until the semaphore pointed 
    90  * to by sem has a positive count. It then atomically decreases the semaphore
    91  * count.
    92  */
    93 extern DECLSPEC int SDLCALL SDL_SemWait(SDL_sem *sem);
    94 
    95 /* Non-blocking variant of SDL_SemWait(), returns 0 if the wait succeeds,
    96    SDL_MUTEX_TIMEDOUT if the wait would block, and -1 on error.
    97 */
    98 extern DECLSPEC int SDLCALL SDL_SemTryWait(SDL_sem *sem);
    99 
   100 /* Variant of SDL_SemWait() with a timeout in milliseconds, returns 0 if
   101    the wait succeeds, SDL_MUTEX_TIMEDOUT if the wait does not succeed in
   102    the allotted time, and -1 on error.
   103    On some platforms this function is implemented by looping with a delay
   104    of 1 ms, and so should be avoided if possible.
   105 */
   106 extern DECLSPEC int SDLCALL SDL_SemWaitTimeout(SDL_sem *sem, Uint32 ms);
   107 
   108 /* Atomically increases the semaphore's count (not blocking), returns 0,
   109    or -1 on error.
   110  */
   111 extern DECLSPEC int SDLCALL SDL_SemPost(SDL_sem *sem);
   112 
   113 /* Returns the current count of the semaphore */
   114 extern DECLSPEC Uint32 SDLCALL SDL_SemValue(SDL_sem *sem);
   115 
   116 
   117 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
   118 /* Condition variable functions                                  */
   119 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
   120 
   121 /* The SDL condition variable structure, defined in SDL_cond.c */
   122 struct SDL_cond;
   123 typedef struct SDL_cond SDL_cond;
   124 
   125 /* Create a condition variable */
   126 extern DECLSPEC SDL_cond * SDLCALL SDL_CreateCond(void);
   127 
   128 /* Destroy a condition variable */
   129 extern DECLSPEC void SDLCALL SDL_DestroyCond(SDL_cond *cond);
   130 
   131 /* Restart one of the threads that are waiting on the condition variable,
   132    returns 0 or -1 on error.
   133  */
   134 extern DECLSPEC int SDLCALL SDL_CondSignal(SDL_cond *cond);
   135 
   136 /* Restart all threads that are waiting on the condition variable,
   137    returns 0 or -1 on error.
   138  */
   139 extern DECLSPEC int SDLCALL SDL_CondBroadcast(SDL_cond *cond);
   140 
   141 /* Wait on the condition variable, unlocking the provided mutex.
   142    The mutex must be locked before entering this function!
   143    The mutex is re-locked once the condition variable is signaled.
   144    Returns 0 when it is signaled, or -1 on error.
   145  */
   146 extern DECLSPEC int SDLCALL SDL_CondWait(SDL_cond *cond, SDL_mutex *mut);
   147 
   148 /* Waits for at most 'ms' milliseconds, and returns 0 if the condition
   149    variable is signaled, SDL_MUTEX_TIMEDOUT if the condition is not
   150    signaled in the allotted time, and -1 on error.
   151    On some platforms this function is implemented by looping with a delay
   152    of 1 ms, and so should be avoided if possible.
   153 */
   154 extern DECLSPEC int SDLCALL SDL_CondWaitTimeout(SDL_cond *cond, SDL_mutex *mutex, Uint32 ms);
   155 
   156 /* Ends C function definitions when using C++ */
   157 #ifdef __cplusplus
   158 }
   159 #endif
   160 #include "close_code.h"
   161 
   162 #endif /* _SDL_mutex_h */