include/SDL_thread.h
author Sam Lantinga <slouken@libsdl.org>
Fri, 25 Mar 2011 12:44:06 -0700
changeset 5509 5b1b4d820d10
parent 5506 82a09d5d0f07
child 5535 96594ac5fd1a
permissions -rw-r--r--
The API sets the priority for the current thread, not an arbitrary thread.

Implemented thread priority as the 'nice' value on Linux. High priority threads require root permissions (you shouldn't give your game root permissions though!)
slouken@0
     1
/*
slouken@0
     2
    SDL - Simple DirectMedia Layer
slouken@5262
     3
    Copyright (C) 1997-2011 Sam Lantinga
slouken@0
     4
slouken@0
     5
    This library is free software; you can redistribute it and/or
slouken@1312
     6
    modify it under the terms of the GNU Lesser General Public
slouken@0
     7
    License as published by the Free Software Foundation; either
slouken@1312
     8
    version 2.1 of the License, or (at your option) any later version.
slouken@0
     9
slouken@0
    10
    This library is distributed in the hope that it will be useful,
slouken@0
    11
    but WITHOUT ANY WARRANTY; without even the implied warranty of
slouken@0
    12
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
slouken@1312
    13
    Lesser General Public License for more details.
slouken@0
    14
slouken@1312
    15
    You should have received a copy of the GNU Lesser General Public
slouken@1312
    16
    License along with this library; if not, write to the Free Software
slouken@1312
    17
    Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
slouken@0
    18
slouken@0
    19
    Sam Lantinga
slouken@251
    20
    slouken@libsdl.org
slouken@0
    21
*/
slouken@0
    22
slouken@0
    23
#ifndef _SDL_thread_h
slouken@0
    24
#define _SDL_thread_h
slouken@0
    25
slouken@1895
    26
/**
slouken@3407
    27
 *  \file SDL_thread.h
slouken@3407
    28
 *  
slouken@3407
    29
 *  Header for the SDL thread management routines.
slouken@1895
    30
 */
slouken@0
    31
slouken@1356
    32
#include "SDL_stdinc.h"
slouken@1358
    33
#include "SDL_error.h"
slouken@0
    34
slouken@0
    35
/* Thread synchronization primitives */
slouken@0
    36
#include "SDL_mutex.h"
slouken@0
    37
slouken@0
    38
#include "begin_code.h"
slouken@0
    39
/* Set up for C function definitions, even when using C++ */
slouken@0
    40
#ifdef __cplusplus
slouken@1895
    41
/* *INDENT-OFF* */
slouken@0
    42
extern "C" {
slouken@1895
    43
/* *INDENT-ON* */
slouken@0
    44
#endif
slouken@0
    45
slouken@0
    46
/* The SDL thread structure, defined in SDL_thread.c */
slouken@0
    47
struct SDL_Thread;
slouken@0
    48
typedef struct SDL_Thread SDL_Thread;
slouken@0
    49
slouken@3578
    50
/* The SDL thread ID */
slouken@3578
    51
typedef unsigned long SDL_threadID;
slouken@3578
    52
slouken@5506
    53
/* The SDL thread priority
slouken@5506
    54
 *
slouken@5506
    55
 * Note: On many systems you require special privileges to set high priority.
slouken@5506
    56
 */
slouken@5506
    57
typedef enum {
slouken@5506
    58
    SDL_THREAD_PRIORITY_LOW,
slouken@5506
    59
    SDL_THREAD_PRIORITY_NORMAL,
slouken@5506
    60
    SDL_THREAD_PRIORITY_HIGH
slouken@5506
    61
} SDL_ThreadPriority;
slouken@5506
    62
slouken@4866
    63
/* The function passed to SDL_CreateThread()
slouken@4866
    64
   It is passed a void* user context parameter and returns an int.
slouken@4866
    65
 */
slouken@4866
    66
typedef int (SDLCALL * SDL_ThreadFunction) (void *data);
slouken@4866
    67
slouken@5086
    68
#if defined(__WIN32__) && !defined(HAVE_LIBC)
slouken@3407
    69
/**
slouken@3407
    70
 *  \file SDL_thread.h
slouken@3407
    71
 *  
slouken@3407
    72
 *  We compile SDL into a DLL. This means, that it's the DLL which
slouken@3407
    73
 *  creates a new thread for the calling process with the SDL_CreateThread()
slouken@3407
    74
 *  API. There is a problem with this, that only the RTL of the SDL.DLL will
slouken@3407
    75
 *  be initialized for those threads, and not the RTL of the calling 
slouken@3407
    76
 *  application!
slouken@3407
    77
 *  
slouken@3407
    78
 *  To solve this, we make a little hack here.
slouken@3407
    79
 *  
slouken@3407
    80
 *  We'll always use the caller's _beginthread() and _endthread() APIs to
slouken@3407
    81
 *  start a new thread. This way, if it's the SDL.DLL which uses this API,
slouken@3407
    82
 *  then the RTL of SDL.DLL will be used to create the new thread, and if it's
slouken@3407
    83
 *  the application, then the RTL of the application will be used.
slouken@3407
    84
 *  
slouken@3407
    85
 *  So, in short:
slouken@3407
    86
 *  Always use the _beginthread() and _endthread() of the calling runtime 
slouken@3407
    87
 *  library!
slouken@3407
    88
 */
slouken@1471
    89
#define SDL_PASSED_BEGINTHREAD_ENDTHREAD
slouken@1465
    90
#ifndef _WIN32_WCE
slouken@1895
    91
#include <process.h>            /* This has _beginthread() and _endthread() defined! */
icculus@1190
    92
#endif
icculus@1190
    93
slouken@3269
    94
#ifdef __GNUC__
slouken@1895
    95
typedef unsigned long (__cdecl * pfnSDL_CurrentBeginThread) (void *, unsigned,
slouken@1895
    96
                                                             unsigned
slouken@1895
    97
                                                             (__stdcall *
slouken@1895
    98
                                                              func) (void *),
slouken@1895
    99
                                                             void *arg,
slouken@1895
   100
                                                             unsigned,
slouken@1895
   101
                                                             unsigned
slouken@1895
   102
                                                             *threadID);
slouken@1895
   103
typedef void (__cdecl * pfnSDL_CurrentEndThread) (unsigned code);
slouken@1330
   104
#else
slouken@1895
   105
typedef uintptr_t(__cdecl * pfnSDL_CurrentBeginThread) (void *, unsigned,
slouken@1895
   106
                                                        unsigned (__stdcall *
slouken@1895
   107
                                                                  func) (void
slouken@1895
   108
                                                                         *),
slouken@1895
   109
                                                        void *arg, unsigned,
slouken@1895
   110
                                                        unsigned *threadID);
slouken@1895
   111
typedef void (__cdecl * pfnSDL_CurrentEndThread) (unsigned code);
slouken@1330
   112
#endif
icculus@1190
   113
slouken@3407
   114
/**
slouken@3407
   115
 *  Create a thread.
slouken@3407
   116
 */
slouken@2060
   117
extern DECLSPEC SDL_Thread *SDLCALL
slouken@4866
   118
SDL_CreateThread(SDL_ThreadFunction fn, void *data,
slouken@2060
   119
                 pfnSDL_CurrentBeginThread pfnBeginThread,
slouken@2060
   120
                 pfnSDL_CurrentEndThread pfnEndThread);
icculus@1190
   121
slouken@3269
   122
#if defined(_WIN32_WCE)
slouken@3407
   123
slouken@3407
   124
/**
slouken@3407
   125
 *  Create a thread.
slouken@3407
   126
 */
slouken@1330
   127
#define SDL_CreateThread(fn, data) SDL_CreateThread(fn, data, NULL, NULL)
slouken@3407
   128
slouken@1330
   129
#else
slouken@3407
   130
slouken@3407
   131
/**
slouken@3407
   132
 *  Create a thread.
slouken@3407
   133
 */
slouken@1330
   134
#define SDL_CreateThread(fn, data) SDL_CreateThread(fn, data, _beginthreadex, _endthreadex)
slouken@3407
   135
slouken@1330
   136
#endif
icculus@1190
   137
#else
slouken@3407
   138
slouken@3407
   139
/**
slouken@3407
   140
 *  Create a thread.
slouken@3407
   141
 */
slouken@1895
   142
extern DECLSPEC SDL_Thread *SDLCALL
slouken@4866
   143
SDL_CreateThread(SDL_ThreadFunction fn, void *data);
slouken@3407
   144
icculus@1190
   145
#endif
slouken@0
   146
slouken@3407
   147
/**
slouken@3578
   148
 *  Get the thread identifier for the current thread.
slouken@3407
   149
 */
slouken@3578
   150
extern DECLSPEC SDL_threadID SDLCALL SDL_ThreadID(void);
slouken@0
   151
slouken@3407
   152
/**
slouken@3578
   153
 *  Get the thread identifier for the specified thread.
slouken@3407
   154
 *  
slouken@3407
   155
 *  Equivalent to SDL_ThreadID() if the specified thread is NULL.
slouken@0
   156
 */
slouken@3578
   157
extern DECLSPEC SDL_threadID SDLCALL SDL_GetThreadID(SDL_Thread * thread);
slouken@0
   158
slouken@3407
   159
/**
slouken@5509
   160
 *  Set the priority for the current thread
slouken@5506
   161
 */
slouken@5509
   162
extern DECLSPEC int SDLCALL SDL_SetThreadPriority(SDL_ThreadPriority priority);
slouken@5506
   163
slouken@5506
   164
/**
slouken@3407
   165
 *  Wait for a thread to finish.
slouken@3407
   166
 *  
slouken@3407
   167
 *  The return code for the thread function is placed in the area
slouken@3407
   168
 *  pointed to by \c status, if \c status is not NULL.
slouken@0
   169
 */
slouken@1895
   170
extern DECLSPEC void SDLCALL SDL_WaitThread(SDL_Thread * thread, int *status);
slouken@0
   171
slouken@0
   172
slouken@0
   173
/* Ends C function definitions when using C++ */
slouken@0
   174
#ifdef __cplusplus
slouken@1895
   175
/* *INDENT-OFF* */
slouken@0
   176
}
slouken@1895
   177
/* *INDENT-ON* */
slouken@0
   178
#endif
slouken@0
   179
#include "close_code.h"
slouken@0
   180
slouken@0
   181
#endif /* _SDL_thread_h */
slouken@1895
   182
slouken@1895
   183
/* vi: set ts=4 sw=4 expandtab: */