sdlthread.inc

   1 //from "sdl_thread.h"
   2
   3 {* The SDL thread structure, defined in SDL_thread.c *}
   4 //todo!
   5 type
   6   {* The SDL thread priority
   7    *
   8    * Note: On many systems you require special privileges to set high priority.
   9    *}
  10
  11   TSDL_ThreadPriority = (SDL_THREAD_PRIORITY_LOW,
  12                          SDL_THREAD_PRIORITY_NORMAL,
  13                          SDL_THREAD_PRIORITY_HIGH);
  14
  15   {* The function passed to SDL_CreateThread()
  16      It is passed a void* user context parameter and returns an int.
  17    *}
  18   PSDL_ThreadFunction = ^TSDL_ThreadFunction;
  19   TSDL_ThreadFunction = function(data: Pointer): Integer; cdecl;
  20
  21   {* The SDL thread ID *}
  22   TSDL_ThreadID = LongWord;
  23    {
  24   PSDL_Thread = Pointer;
  25      }
  26
  27   PSDL_Thread = ^TSDL_Thread;
  28   TSDL_Thread = record
  29     threadid: TSDL_ThreadID;
  30     handle: THandle;
  31     status: SInt32;
  32     errbuf: TSDL_Error;
  33     name: PAnsiChar;
  34     data: Pointer;
  35   end;
  36
  37   TSDL_TLSID = Cardinal;
  38
  39 {$IFDEF WINDOWS}
  40   {**
  41    *  SDL_thread.h
  42    *
  43    *  We compile SDL into a DLL. This means, that it's the DLL which
  44    *  creates a new thread for the calling process with the SDL_CreateThread()
  45    *  API. There is a problem with this, that only the RTL of the SDL.DLL will
  46    *  be initialized for those threads, and not the RTL of the calling
  47    *  application!
  48    *
  49    *  To solve this, we make a little hack here.
  50    *
  51    *  We'll always use the caller's _beginthread() and _endthread() APIs to
  52    *  start a new thread. This way, if it's the SDL.DLL which uses this API,
  53    *  then the RTL of SDL.DLL will be used to create the new thread, and if it's
  54    *  the application, then the RTL of the application will be used.
  55    *
  56    *  So, in short:
  57    *  Always use the _beginthread() and _endthread() of the calling runtime
  58    *  library!
  59    *}
  60 {$DEFINE SDL_PASSED_BEGINTHREAD_ENDTHREAD}
  61
  62 type
  63   {$IFNDEF DELPHI16UP}
  64     TThreadID = Cardinal;
  65   {$ENDIF}
  66
  67   TpfnSDL_CurrentBeginThread = function(SecurityAttributes: Pointer; StackSize: LongWord; ThreadFunc: TThreadFunc; Parameter: Pointer; CreationFlags: LongWord; var ThreadId: TThreadID): Integer;
  68
  69   TpfnSDL_CurrentEndThread = procedure(ExitCode: Integer);
  70
  71   {**
  72    *  Create a thread.
  73    *}
  74 function SDL_CreateThread(fn: TSDL_ThreadFunction; name: PAnsiChar; data: Pointer; pfnBeginThread: TpfnSDL_CurrentBeginThread; pfnEndThread: TpfnSDL_CurrentEndThread): PSDL_Thread; cdecl; overload; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CreateThread' {$ENDIF} {$ENDIF};
  75
  76   {**
  77    *  Create a thread.
  78    *}
  79 function SDL_CreateThread(fn: TSDL_ThreadFunction; name: PAnsiChar; data: Pointer): PSDL_Thread; overload;
  80
  81 {$ELSE}
  82
  83   {**
  84    *  Create a thread.
  85    *
  86    *   Thread naming is a little complicated: Most systems have very small
  87    *    limits for the string length (BeOS has 32 bytes, Linux currently has 16,
  88    *    Visual C++ 6.0 has nine!), and possibly other arbitrary rules. You'll
  89    *    have to see what happens with your system's debugger. The name should be
  90    *    UTF-8 (but using the naming limits of C identifiers is a better bet).
  91    *   There are no requirements for thread naming conventions, so long as the
  92    *    string is null-terminated UTF-8, but these guidelines are helpful in
  93    *    choosing a name:
  94    *
  95    *    http://stackoverflow.com/questions/149932/naming-conventions-for-threads
  96    *
  97    *   If a system imposes requirements, SDL will try to munge the string for
  98    *    it (truncate, etc), but the original string contents will be available
  99    *    from SDL_GetThreadName().
 100    *}
 101 function SDL_CreateThread(fn: TSDL_ThreadFunction; name: PAnsiChar; data: Pointer): PSDL_Thread; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CreateThread' {$ENDIF} {$ENDIF};
 102
 103 {$ENDIF}
 104
 105   {**
 106    * Get the thread name, as it was specified in SDL_CreateThread().
 107    *  This function returns a pointer to a UTF-8 string that names the
 108    *  specified thread, or NULL if it doesn't have a name. This is internal
 109    *  memory, not to be free()'d by the caller, and remains valid until the
 110    *  specified thread is cleaned up by SDL_WaitThread().
 111    *}
 112 function SDL_GetThreadName(thread: PSDL_Thread): PAnsiChar cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetThreadName' {$ENDIF}{$ENDIF};
 113
 114   {**
 115    *  Get the thread identifier for the current thread.
 116    *}
 117 function SDL_ThreadID: TSDL_ThreadID cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ThreadID' {$ENDIF}{$ENDIF};
 118
 119   {**
 120    *  Get the thread identifier for the specified thread.
 121    *
 122    *  Equivalent to SDL_ThreadID() if the specified thread is NULL.
 123    *}
 124 function SDL_GetThreadID(thread: PSDL_Thread): TSDL_ThreadID cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetThreadID' {$ENDIF}{$ENDIF};
 125
 126   {**
 127    *  Set the priority for the current thread
 128    *}
 129 function SDL_SetThreadPriority(priority: TSDL_ThreadPriority): SInt32 cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetThreadPriority' {$ENDIF}{$ENDIF};
 130
 131   {**
 132    *  Wait for a thread to finish.
 133    *
 134    *  The return code for the thread function is placed in the area
 135    *  pointed to by status, if status is not NULL.
 136    *}
 137 procedure SDL_WaitThread(thread: PSDL_Thread; status: PInt) cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_WaitThread' {$ENDIF}{$ENDIF};
 138
 139   {**
 140    *  Create an identifier that is globally visible to all threads but refers to data that is thread-specific.
 141    *
 142    *   The newly created thread local storage identifier, or 0 on error
 143    *
 144    *  static SDL_SpinLock tls_lock;
 145    *  static SDL_TLSID thread_local_storage;
 146    *
 147    *  void SetMyThreadData(void *value)
 148    *  {
 149    *      if (!thread_local_storage) {
 150    *          SDL_AtomicLock(&tls_lock);
 151    *          if (!thread_local_storage) {
 152    *              thread_local_storage = SDL_TLSCreate();
 153    *          }   {
 154    *          SDL_AtomicUnLock(&tls_lock);
 155    *      } {
 156    *      SDL_TLSSet(thread_local_storage, value);
 157    *  } {
 158    *
 159    *  void *GetMyThreadData(void)
 160    *  {
 161    *      return SDL_TLSGet(thread_local_storage);
 162    *  }{
 163    *
 164    *   SDL_TLSGet()
 165    *   SDL_TLSSet()
 166    *}
 167 function SDL_TLSCreate: TSDL_TLSID cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_TLSCreate' {$ENDIF} {$ENDIF};
 168
 169   {**
 170    *  Get the value associated with a thread local storage ID for the current thread.
 171    *
 172    *   id The thread local storage ID
 173    *
 174    *   The value associated with the ID for the current thread, or NULL if no value has been set.
 175    *
 176    *   SDL_TLSCreate()
 177    *   SDL_TLSSet()
 178    *}
 179 function SDL_TLSGet(id: TSDL_TLSID): Pointer cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_TLSGet' {$ENDIF} {$ENDIF};
 180
 181   {**
 182    *  Set the value associated with a thread local storage ID for the current thread.
 183    *
 184    *   id The thread local storage ID
 185    *   value The value to associate with the ID for the current thread
 186    *   destructor_ A function called when the thread exits, to free the value.
 187    *
 188    *   0 on success, -1 on error
 189    *
 190    *   SDL_TLSCreate()
 191    *   SDL_TLSGet()
 192    *}
 193 function SDL_TLSSet(id: TSDL_TLSID; value: Pointer; destructor_: Pointer): SInt32 cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_TLSSet' {$ENDIF} {$ENDIF};