include/SDL_thread.h
author Ryan C. Gordon <icculus@icculus.org>
Sat, 15 Sep 2012 10:59:39 -0400
changeset 6430 48d519500f7e
parent 6138 4c64952a58fb
child 6885 700f1b25f77f
permissions -rw-r--r--
Removed Windows CE support from SDL 2.0.

It's a long-dead platform, and we don't have any way to build for, test, or
maintain it, so there's no sense in doing acrobatics to support it.

If you need Windows CE support, use SDL 1.2. If you need Windows Phone support,
send SDL 2.0 patches for the newer Windows Mobile platform.
slouken@0
     1
/*
slouken@5535
     2
  Simple DirectMedia Layer
slouken@6138
     3
  Copyright (C) 1997-2012 Sam Lantinga <slouken@libsdl.org>
slouken@0
     4
slouken@5535
     5
  This software is provided 'as-is', without any express or implied
slouken@5535
     6
  warranty.  In no event will the authors be held liable for any damages
slouken@5535
     7
  arising from the use of this software.
slouken@0
     8
slouken@5535
     9
  Permission is granted to anyone to use this software for any purpose,
slouken@5535
    10
  including commercial applications, and to alter it and redistribute it
slouken@5535
    11
  freely, subject to the following restrictions:
slouken@0
    12
slouken@5535
    13
  1. The origin of this software must not be misrepresented; you must not
slouken@5535
    14
     claim that you wrote the original software. If you use this software
slouken@5535
    15
     in a product, an acknowledgment in the product documentation would be
slouken@5535
    16
     appreciated but is not required.
slouken@5535
    17
  2. Altered source versions must be plainly marked as such, and must not be
slouken@5535
    18
     misrepresented as being the original software.
slouken@5535
    19
  3. This notice may not be removed or altered from any source distribution.
slouken@0
    20
*/
slouken@0
    21
slouken@0
    22
#ifndef _SDL_thread_h
slouken@0
    23
#define _SDL_thread_h
slouken@0
    24
slouken@1895
    25
/**
slouken@3407
    26
 *  \file SDL_thread.h
slouken@3407
    27
 *  
slouken@3407
    28
 *  Header for the SDL thread management routines.
slouken@1895
    29
 */
slouken@0
    30
slouken@1356
    31
#include "SDL_stdinc.h"
slouken@1358
    32
#include "SDL_error.h"
slouken@0
    33
slouken@0
    34
/* Thread synchronization primitives */
slouken@0
    35
#include "SDL_mutex.h"
slouken@0
    36
slouken@0
    37
#include "begin_code.h"
slouken@0
    38
/* Set up for C function definitions, even when using C++ */
slouken@0
    39
#ifdef __cplusplus
slouken@1895
    40
/* *INDENT-OFF* */
slouken@0
    41
extern "C" {
slouken@1895
    42
/* *INDENT-ON* */
slouken@0
    43
#endif
slouken@0
    44
slouken@0
    45
/* The SDL thread structure, defined in SDL_thread.c */
slouken@0
    46
struct SDL_Thread;
slouken@0
    47
typedef struct SDL_Thread SDL_Thread;
slouken@0
    48
slouken@3578
    49
/* The SDL thread ID */
slouken@3578
    50
typedef unsigned long SDL_threadID;
slouken@3578
    51
slouken@5506
    52
/* The SDL thread priority
slouken@5506
    53
 *
slouken@5506
    54
 * Note: On many systems you require special privileges to set high priority.
slouken@5506
    55
 */
slouken@5506
    56
typedef enum {
slouken@5506
    57
    SDL_THREAD_PRIORITY_LOW,
slouken@5506
    58
    SDL_THREAD_PRIORITY_NORMAL,
slouken@5506
    59
    SDL_THREAD_PRIORITY_HIGH
slouken@5506
    60
} SDL_ThreadPriority;
slouken@5506
    61
slouken@4866
    62
/* The function passed to SDL_CreateThread()
slouken@4866
    63
   It is passed a void* user context parameter and returns an int.
slouken@4866
    64
 */
slouken@4866
    65
typedef int (SDLCALL * SDL_ThreadFunction) (void *data);
slouken@4866
    66
slouken@5086
    67
#if defined(__WIN32__) && !defined(HAVE_LIBC)
slouken@3407
    68
/**
slouken@3407
    69
 *  \file SDL_thread.h
slouken@3407
    70
 *  
slouken@3407
    71
 *  We compile SDL into a DLL. This means, that it's the DLL which
slouken@3407
    72
 *  creates a new thread for the calling process with the SDL_CreateThread()
slouken@3407
    73
 *  API. There is a problem with this, that only the RTL of the SDL.DLL will
slouken@3407
    74
 *  be initialized for those threads, and not the RTL of the calling 
slouken@3407
    75
 *  application!
slouken@3407
    76
 *  
slouken@3407
    77
 *  To solve this, we make a little hack here.
slouken@3407
    78
 *  
slouken@3407
    79
 *  We'll always use the caller's _beginthread() and _endthread() APIs to
slouken@3407
    80
 *  start a new thread. This way, if it's the SDL.DLL which uses this API,
slouken@3407
    81
 *  then the RTL of SDL.DLL will be used to create the new thread, and if it's
slouken@3407
    82
 *  the application, then the RTL of the application will be used.
slouken@3407
    83
 *  
slouken@3407
    84
 *  So, in short:
slouken@3407
    85
 *  Always use the _beginthread() and _endthread() of the calling runtime 
slouken@3407
    86
 *  library!
slouken@3407
    87
 */
slouken@1471
    88
#define SDL_PASSED_BEGINTHREAD_ENDTHREAD
slouken@1895
    89
#include <process.h>            /* This has _beginthread() and _endthread() defined! */
icculus@1190
    90
slouken@1895
    91
typedef uintptr_t(__cdecl * pfnSDL_CurrentBeginThread) (void *, unsigned,
slouken@1895
    92
                                                        unsigned (__stdcall *
slouken@1895
    93
                                                                  func) (void
slouken@1895
    94
                                                                         *),
slouken@1895
    95
                                                        void *arg, unsigned,
slouken@1895
    96
                                                        unsigned *threadID);
slouken@1895
    97
typedef void (__cdecl * pfnSDL_CurrentEndThread) (unsigned code);
icculus@1190
    98
slouken@3407
    99
/**
slouken@3407
   100
 *  Create a thread.
slouken@3407
   101
 */
slouken@2060
   102
extern DECLSPEC SDL_Thread *SDLCALL
icculus@5969
   103
SDL_CreateThread(SDL_ThreadFunction fn, const char *name, void *data,
slouken@2060
   104
                 pfnSDL_CurrentBeginThread pfnBeginThread,
slouken@2060
   105
                 pfnSDL_CurrentEndThread pfnEndThread);
icculus@1190
   106
slouken@3407
   107
/**
slouken@3407
   108
 *  Create a thread.
slouken@3407
   109
 */
icculus@5969
   110
#define SDL_CreateThread(fn, name, data) SDL_CreateThread(fn, name, data, _beginthreadex, _endthreadex)
slouken@3407
   111
icculus@1190
   112
#else
slouken@3407
   113
slouken@3407
   114
/**
slouken@3407
   115
 *  Create a thread.
icculus@5969
   116
 *
icculus@5969
   117
 *   Thread naming is a little complicated: Most systems have very small
icculus@5969
   118
 *    limits for the string length (BeOS has 32 bytes, Linux currently has 16,
icculus@5969
   119
 *    Visual C++ 6.0 has nine!), and possibly other arbitrary rules. You'll
icculus@5969
   120
 *    have to see what happens with your system's debugger. The name should be
icculus@5969
   121
 *    UTF-8 (but using the naming limits of C identifiers is a better bet).
icculus@5969
   122
 *   There are no requirements for thread naming conventions, so long as the
icculus@5969
   123
 *    string is null-terminated UTF-8, but these guidelines are helpful in
icculus@5969
   124
 *    choosing a name:
icculus@5969
   125
 *
icculus@5969
   126
 *    http://stackoverflow.com/questions/149932/naming-conventions-for-threads
icculus@5969
   127
 *
icculus@5969
   128
 *   If a system imposes requirements, SDL will try to munge the string for
icculus@5969
   129
 *    it (truncate, etc), but the original string contents will be available
icculus@5969
   130
 *    from SDL_GetThreadName().
slouken@3407
   131
 */
slouken@1895
   132
extern DECLSPEC SDL_Thread *SDLCALL
icculus@5969
   133
SDL_CreateThread(SDL_ThreadFunction fn, const char *name, void *data);
slouken@3407
   134
icculus@1190
   135
#endif
slouken@0
   136
slouken@3407
   137
/**
icculus@5969
   138
 * Get the thread name, as it was specified in SDL_CreateThread().
icculus@5969
   139
 *  This function returns a pointer to a UTF-8 string that names the
icculus@5969
   140
 *  specified thread, or NULL if it doesn't have a name. This is internal
icculus@5969
   141
 *  memory, not to be free()'d by the caller, and remains valid until the
icculus@5969
   142
 *  specified thread is cleaned up by SDL_WaitThread().
icculus@5969
   143
 */
icculus@5969
   144
extern DECLSPEC const char *SDLCALL SDL_GetThreadName(SDL_Thread *thread);
icculus@5969
   145
icculus@5969
   146
/**
slouken@3578
   147
 *  Get the thread identifier for the current thread.
slouken@3407
   148
 */
slouken@3578
   149
extern DECLSPEC SDL_threadID SDLCALL SDL_ThreadID(void);
slouken@0
   150
slouken@3407
   151
/**
slouken@3578
   152
 *  Get the thread identifier for the specified thread.
slouken@3407
   153
 *  
slouken@3407
   154
 *  Equivalent to SDL_ThreadID() if the specified thread is NULL.
slouken@0
   155
 */
slouken@3578
   156
extern DECLSPEC SDL_threadID SDLCALL SDL_GetThreadID(SDL_Thread * thread);
slouken@0
   157
slouken@3407
   158
/**
slouken@5509
   159
 *  Set the priority for the current thread
slouken@5506
   160
 */
slouken@5509
   161
extern DECLSPEC int SDLCALL SDL_SetThreadPriority(SDL_ThreadPriority priority);
slouken@5506
   162
slouken@5506
   163
/**
slouken@3407
   164
 *  Wait for a thread to finish.
slouken@3407
   165
 *  
slouken@3407
   166
 *  The return code for the thread function is placed in the area
slouken@3407
   167
 *  pointed to by \c status, if \c status is not NULL.
slouken@0
   168
 */
slouken@1895
   169
extern DECLSPEC void SDLCALL SDL_WaitThread(SDL_Thread * thread, int *status);
slouken@0
   170
slouken@0
   171
slouken@0
   172
/* Ends C function definitions when using C++ */
slouken@0
   173
#ifdef __cplusplus
slouken@1895
   174
/* *INDENT-OFF* */
slouken@0
   175
}
slouken@1895
   176
/* *INDENT-ON* */
slouken@0
   177
#endif
slouken@0
   178
#include "close_code.h"
slouken@0
   179
slouken@0
   180
#endif /* _SDL_thread_h */
slouken@1895
   181
slouken@1895
   182
/* vi: set ts=4 sw=4 expandtab: */