src/lib/sdl2/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    *  A thread may be "detached" to signify that it should not remain until
 141    *  another thread has called SDL_WaitThread() on it. Detaching a thread
 142    *  is useful for long-running threads that nothing needs to synchronize
 143    *  with or further manage. When a detached thread is done, it simply
 144    *  goes away.
 145    *
 146    *  There is no way to recover the return code of a detached thread. If you
 147    *  need this, don't detach the thread and instead use SDL_WaitThread().
 148    *
 149    *  Once a thread is detached, you should usually assume the SDL_Thread isn't
 150    *  safe to reference again, as it will become invalid immediately upon
 151    *  the detached thread's exit, instead of remaining until someone has called
 152    *  SDL_WaitThread() to finally clean it up. As such, don't detach the same
 153    *  thread more than once.
 154    *
 155    *  If a thread has already exited when passed to SDL_DetachThread(), it will
 156    *  stop waiting for a call to SDL_WaitThread() and clean up immediately.
 157    *  It is not safe to detach a thread that might be used with SDL_WaitThread().
 158    *
 159    *  You may not call SDL_WaitThread() on a thread that has been detached.
 160    *  Use either that function or this one, but not both, or behavior is
 161    *  undefined.
 162    *
 163    *  It is safe to pass NIL to this function; it is a no-op.
 164    *}
 165 procedure SDL_DetachThread(thread:TSDL_Thread); cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_DetachThread' {$ENDIF}{$ENDIF};
 166
 167   {**
 168    *  Create an identifier that is globally visible to all threads but refers to data that is thread-specific.
 169    *
 170    *   The newly created thread local storage identifier, or 0 on error
 171    *
 172    *  var tls_lock: TSDL_SpinLock;
 173    *    thread_local_storage: TSDL_TLSID;
 174    *
 175    *  procedure SetMyThreadData(value: Pointer)
 176    *
 177    *      if not (thread_local_storage) then
 178    *      begin
 179    *        SDL_AtomicLock(@tls_lock);
 180    *        if (!thread_local_storage)
 181    *              thread_local_storage = SDL_TLSCreate();
 182    *
 183    *        SDL_AtomicUnLock(@tls_lock);
 184    *
 185    *        SDL_TLSSet(thread_local_storage, value);
 186    *      end;
 187    *
 188    *  function GetMyThreadData(): Pointer;
 189    *  begin
 190    *     Result := SDL_TLSGet(thread_local_storage);
 191    *  end;
 192    *
 193    *   SDL_TLSGet()
 194    *   SDL_TLSSet()
 195    *}
 196 function SDL_TLSCreate: TSDL_TLSID cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_TLSCreate' {$ENDIF} {$ENDIF};
 197
 198   {**
 199    *  Get the value associated with a thread local storage ID for the current thread.
 200    *
 201    *   id The thread local storage ID
 202    *
 203    *   The value associated with the ID for the current thread, or NULL if no value has been set.
 204    *
 205    *   SDL_TLSCreate()
 206    *   SDL_TLSSet()
 207    *}
 208 function SDL_TLSGet(id: TSDL_TLSID): Pointer cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_TLSGet' {$ENDIF} {$ENDIF};
 209
 210   {**
 211    *  Set the value associated with a thread local storage ID for the current thread.
 212    *
 213    *   id The thread local storage ID
 214    *   value The value to associate with the ID for the current thread
 215    *   destructor_ A function called when the thread exits, to free the value.
 216    *
 217    *   0 on success, -1 on error
 218    *
 219    *   SDL_TLSCreate()
 220    *   SDL_TLSGet()
 221    *}
 222 function SDL_TLSSet(id: TSDL_TLSID; value: Pointer; destructor_: Pointer): SInt32 cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_TLSSet' {$ENDIF} {$ENDIF};