From 4aabf376ffa90105bef0a47f137a935c49b1baf2 Mon Sep 17 00:00:00 2001 From: Matthias Date: Sat, 28 Jan 2023 02:24:42 +0100 Subject: [PATCH 01/39] Add file description comment --- units/sdlthread.inc | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/units/sdlthread.inc b/units/sdlthread.inc index 9536f043..ca464db6 100644 --- a/units/sdlthread.inc +++ b/units/sdlthread.inc @@ -1,5 +1,11 @@ // based on "sdl_thread.h" +{** + * \file SDL_thread.h + * + * Header for the SDL thread management routines. + *} + {* The SDL thread structure, defined in SDL_thread.c *} { TODO : Update this file } type From 25cf33ac333aece70d400686b2db8408a1ce2083 Mon Sep 17 00:00:00 2001 From: Matthias Date: Sat, 28 Jan 2023 02:31:19 +0100 Subject: [PATCH 02/39] Update TSDL_Thread (opaque now) --- units/sdlthread.inc | 13 ++----------- 1 file changed, 2 insertions(+), 11 deletions(-) diff --git a/units/sdlthread.inc b/units/sdlthread.inc index ca464db6..fb6beea0 100644 --- a/units/sdlthread.inc +++ b/units/sdlthread.inc @@ -7,8 +7,9 @@ *} {* The SDL thread structure, defined in SDL_thread.c *} -{ TODO : Update this file } type + PSDL_Thread = ^TSDL_Thread; + TSDL_Thread = record end; {* The SDL thread ID *} TSDL_threadID = culong; @@ -38,16 +39,6 @@ type PSDL_ThreadFunction = ^TSDL_ThreadFunction; TSDL_ThreadFunction = function(data: Pointer): cint; cdecl; - PSDL_Thread = ^TSDL_Thread; - TSDL_Thread = record - threadid: TSDL_ThreadID; - handle: THandle; - status: cint32; - errbuf: TSDL_Error; - name: PAnsiChar; - data: Pointer; - end; - {$IFDEF WINDOWS} {** * SDL_thread.h From ae57afc520bd7a782725cc334b7540a363c0565a Mon Sep 17 00:00:00 2001 From: Matthias Date: Sat, 28 Jan 2023 02:32:07 +0100 Subject: [PATCH 03/39] Make TSDL_threadID a individual type --- units/sdlthread.inc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/units/sdlthread.inc b/units/sdlthread.inc index fb6beea0..a897be2c 100644 --- a/units/sdlthread.inc +++ b/units/sdlthread.inc @@ -12,7 +12,7 @@ type TSDL_Thread = record end; {* The SDL thread ID *} - TSDL_threadID = culong; + TSDL_threadID = type culong; {* Thread local storage ID, 0 is the invalid ID *} TSDL_TLSID = cuint; From 34fe29b4b1fd9e9f222635961425a0b0022a4667 Mon Sep 17 00:00:00 2001 From: Matthias Date: Sat, 28 Jan 2023 02:32:42 +0100 Subject: [PATCH 04/39] Make TSDL_TLSID an individual type --- units/sdlthread.inc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/units/sdlthread.inc b/units/sdlthread.inc index a897be2c..809f45d6 100644 --- a/units/sdlthread.inc +++ b/units/sdlthread.inc @@ -15,7 +15,7 @@ type TSDL_threadID = type culong; {* Thread local storage ID, 0 is the invalid ID *} - TSDL_TLSID = cuint; + TSDL_TLSID = type cuint; {** From 5fa6f9ef57bca5c1394d4da624187a552e9d2d51 Mon Sep 17 00:00:00 2001 From: Matthias Date: Sat, 28 Jan 2023 02:45:03 +0100 Subject: [PATCH 05/39] Update TSDL_ThreadPriority --- units/sdlthread.inc | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/units/sdlthread.inc b/units/sdlthread.inc index 809f45d6..7051e41a 100644 --- a/units/sdlthread.inc +++ b/units/sdlthread.inc @@ -28,10 +28,15 @@ type * * \note On many systems you require special privileges to set high or time critical priority. *} - TSDL_ThreadPriority = (SDL_THREAD_PRIORITY_LOW, - SDL_THREAD_PRIORITY_NORMAL, - SDL_THREAD_PRIORITY_HIGH, - SDL_THREAD_PRIORITY_TIME_CRITICAL); +type + PSDL_ThreadPriority = ^TSDL_ThreadPriority; + TSDL_ThreadPriority = cint; + +const + SDL_THREAD_PRIORITY_LOW = TSDL_ThreadPriority(0); + SDL_THREAD_PRIORITY_NORMAL = TSDL_ThreadPriority(1); + SDL_THREAD_PRIORITY_HIGH = TSDL_ThreadPriority(2); + SDL_THREAD_PRIORITY_TIME_CRITICAL = TSDL_ThreadPriority(3); {* The function passed to SDL_CreateThread() It is passed a void* user context parameter and returns an int. From 48d56fcdf81e28be7688a7f26d3ccd5e457111aa Mon Sep 17 00:00:00 2001 From: Matthias Date: Sat, 28 Jan 2023 02:48:01 +0100 Subject: [PATCH 06/39] Update comment for PSDL_ThreadFunction --- units/sdlthread.inc | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/units/sdlthread.inc b/units/sdlthread.inc index 7051e41a..58f3914a 100644 --- a/units/sdlthread.inc +++ b/units/sdlthread.inc @@ -38,9 +38,13 @@ const SDL_THREAD_PRIORITY_HIGH = TSDL_ThreadPriority(2); SDL_THREAD_PRIORITY_TIME_CRITICAL = TSDL_ThreadPriority(3); - {* The function passed to SDL_CreateThread() - It is passed a void* user context parameter and returns an int. - *} + {** + * The function passed to SDL_CreateThread(). + * + * \param data what was passed as `data` to SDL_CreateThread() + * \returns a value that can be reported through SDL_WaitThread(). + *} +type PSDL_ThreadFunction = ^TSDL_ThreadFunction; TSDL_ThreadFunction = function(data: Pointer): cint; cdecl; From 6c14c65be4d72f6cc7055a50103c263b96768ce0 Mon Sep 17 00:00:00 2001 From: Matthias Date: Sat, 28 Jan 2023 02:58:25 +0100 Subject: [PATCH 07/39] Update TpfnSDL_CurrentEndThread + add 2 todo comments --- units/sdlthread.inc | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/units/sdlthread.inc b/units/sdlthread.inc index 58f3914a..bbc5fda9 100644 --- a/units/sdlthread.inc +++ b/units/sdlthread.inc @@ -72,13 +72,15 @@ type {$DEFINE SDL_PASSED_BEGINTHREAD_ENDTHREAD} type + { #todo : Needed? } {$IFNDEF DELPHI16UP} TThreadID = Cardinal; {$ENDIF} + { #todo : Update this declaration! } TpfnSDL_CurrentBeginThread = function(SecurityAttributes: Pointer; StackSize: LongWord; ThreadFunc: TThreadFunc; Parameter: Pointer; CreationFlags: LongWord; var ThreadId: TThreadID): cint; - TpfnSDL_CurrentEndThread = procedure(ExitCode: cint); + TpfnSDL_CurrentEndThread = procedure(code: cuint); {** * Create a thread. From 7c23835c02b4d99c94a0fd127676b09092bb2766 Mon Sep 17 00:00:00 2001 From: Matthias Date: Sat, 28 Jan 2023 03:09:08 +0100 Subject: [PATCH 08/39] Add SDL_CreateThreadWithStackSize --- units/sdlthread.inc | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/units/sdlthread.inc b/units/sdlthread.inc index bbc5fda9..926a53af 100644 --- a/units/sdlthread.inc +++ b/units/sdlthread.inc @@ -82,18 +82,17 @@ type TpfnSDL_CurrentEndThread = procedure(code: cuint); - {** - * Create a thread. - *} -function SDL_CreateThread(fn: TSDL_ThreadFunction; name: PAnsiChar; - data: Pointer; pfnBeginThread: TpfnSDL_CurrentBeginThread; pfnEndThread: TpfnSDL_CurrentEndThread): PSDL_Thread; cdecl; overload; +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}; - {** - * Create a thread. - *} -function SDL_CreateThread(fn: TSDL_ThreadFunction; name: PAnsiChar; - data: Pointer): PSDL_Thread; overload; +function SDL_CreateThreadWithStackSize(fn: TSDL_ThreadFunction; + name: PAnsiChar; const stacksize: csize_t; data: Pointer; + pfnBeginThread: TpfnSDL_CurrentBeginThread; + pfnEndThread: TpfnSDL_CurrentEndThread): PSDL_Thread; cdecl; overload; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CreateThreadWithStackSize' {$ENDIF} {$ENDIF}; + {$ELSE} From 7c183d9d0bd735a2f91288e0602e820997327a1a Mon Sep 17 00:00:00 2001 From: Matthias Date: Sat, 28 Jan 2023 03:09:46 +0100 Subject: [PATCH 09/39] Remove overload for SDL_CreateThread and SDL_CreateThreadWithStackSize --- units/sdlthread.inc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/units/sdlthread.inc b/units/sdlthread.inc index 926a53af..139eedaa 100644 --- a/units/sdlthread.inc +++ b/units/sdlthread.inc @@ -84,13 +84,13 @@ type function SDL_CreateThread(fn: TSDL_ThreadFunction; name: PAnsiChar; data: Pointer; pfnBeginThread: TpfnSDL_CurrentBeginThread; - pfnEndThread: TpfnSDL_CurrentEndThread): PSDL_Thread; cdecl; overload; + pfnEndThread: TpfnSDL_CurrentEndThread): PSDL_Thread; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CreateThread' {$ENDIF} {$ENDIF}; function SDL_CreateThreadWithStackSize(fn: TSDL_ThreadFunction; name: PAnsiChar; const stacksize: csize_t; data: Pointer; pfnBeginThread: TpfnSDL_CurrentBeginThread; - pfnEndThread: TpfnSDL_CurrentEndThread): PSDL_Thread; cdecl; overload; + pfnEndThread: TpfnSDL_CurrentEndThread): PSDL_Thread; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CreateThreadWithStackSize' {$ENDIF} {$ENDIF}; From e368a10f7b5d3d402ed4aec89f4333686b826160 Mon Sep 17 00:00:00 2001 From: Matthias Date: Sat, 28 Jan 2023 03:20:09 +0100 Subject: [PATCH 10/39] Add comment for code closer review and update comment for SDL_GetThreadName --- units/sdlthread.inc | 23 ++++++++++++++++------- 1 file changed, 16 insertions(+), 7 deletions(-) diff --git a/units/sdlthread.inc b/units/sdlthread.inc index 139eedaa..0a1175f9 100644 --- a/units/sdlthread.inc +++ b/units/sdlthread.inc @@ -94,6 +94,7 @@ function SDL_CreateThreadWithStackSize(fn: TSDL_ThreadFunction; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CreateThreadWithStackSize' {$ENDIF} {$ENDIF}; +{ #todo : THE FOLLOWING CODE UNTIL SDL_GetThreadName functions NEEDS MAJOR REVIEW } {$ELSE} {** @@ -121,13 +122,21 @@ function SDL_CreateThread(fn: TSDL_ThreadFunction; name: PAnsiChar; {$ENDIF} {** - * Get the thread name, as it was specified in SDL_CreateThread(). - * This function returns a pointer to a UTF-8 string that names the - * specified thread, or NULL if it doesn't have a name. This is internal - * memory, not to be free()'d by the caller, and remains valid until the - * specified thread is cleaned up by SDL_WaitThread(). - *} -function SDL_GetThreadName(thread: PSDL_Thread): PAnsiChar cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetThreadName' {$ENDIF}{$ENDIF}; + * Get the thread name as it was specified in SDL_CreateThread(). + * + * This is internal memory, not to be freed by the caller, and remains valid + * until the specified thread is cleaned up by SDL_WaitThread(). + * + * \param thread the thread to query + * \returns a pointer to a UTF-8 string that names the specified thread, or + * NULL if it doesn't have a name. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_CreateThread + *} +function SDL_GetThreadName(thread: PSDL_Thread): PAnsiChar; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetThreadName' {$ENDIF}{$ENDIF}; {** * Get the thread identifier for the current thread. From f47eda40caafec9943ce1f9ab14ed5cbf7b4cb36 Mon Sep 17 00:00:00 2001 From: Matthias Date: Sat, 28 Jan 2023 03:21:31 +0100 Subject: [PATCH 11/39] Update SDL_ThreadID --- units/sdlthread.inc | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/units/sdlthread.inc b/units/sdlthread.inc index 0a1175f9..b71bf313 100644 --- a/units/sdlthread.inc +++ b/units/sdlthread.inc @@ -139,9 +139,23 @@ function SDL_GetThreadName(thread: PSDL_Thread): PAnsiChar; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetThreadName' {$ENDIF}{$ENDIF}; {** - * Get the thread identifier for the current thread. - *} -function SDL_ThreadID: TSDL_ThreadID cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ThreadID' {$ENDIF}{$ENDIF}; + * Get the thread identifier for the current thread. + * + * This thread identifier is as reported by the underlying operating system. + * If SDL is running on a platform that does not support threads the return + * value will always be zero. + * + * This function also returns a valid thread ID when called from the main + * thread. + * + * \returns the ID of the current thread. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_GetThreadID + *} +function SDL_ThreadID: TSDL_ThreadID; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ThreadID' {$ENDIF}{$ENDIF}; {** * Get the thread identifier for the specified thread. From b357e8ea81c20754f79f211339d00f89a8b083ac Mon Sep 17 00:00:00 2001 From: Matthias Date: Sat, 28 Jan 2023 03:22:49 +0100 Subject: [PATCH 12/39] Update SDL_GetThreadID --- units/sdlthread.inc | 21 ++++++++++++++++----- 1 file changed, 16 insertions(+), 5 deletions(-) diff --git a/units/sdlthread.inc b/units/sdlthread.inc index b71bf313..ebc523fa 100644 --- a/units/sdlthread.inc +++ b/units/sdlthread.inc @@ -158,11 +158,22 @@ function SDL_ThreadID: TSDL_ThreadID; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_ThreadID' {$ENDIF}{$ENDIF}; {** - * Get the thread identifier for the specified thread. - * - * Equivalent to SDL_ThreadID() if the specified thread is NULL. - *} -function SDL_GetThreadID(thread: PSDL_Thread): TSDL_ThreadID cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetThreadID' {$ENDIF}{$ENDIF}; + * Get the thread identifier for the specified thread. + * + * This thread identifier is as reported by the underlying operating system. + * If SDL is running on a platform that does not support threads the return + * value will always be zero. + * + * \param thread the thread to query + * \returns the ID of the specified thread, or the ID of the current thread if + * `thread` is NULL. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_ThreadID + *} +function SDL_GetThreadID(thread: PSDL_Thread): TSDL_ThreadID; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetThreadID' {$ENDIF}{$ENDIF}; {** * Set the priority for the current thread From a31530aae1f29457c45ab98c727b3f7f30c383f1 Mon Sep 17 00:00:00 2001 From: Matthias Date: Sat, 28 Jan 2023 03:23:56 +0100 Subject: [PATCH 13/39] Update SDL_SetThreadPriority --- units/sdlthread.inc | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/units/sdlthread.inc b/units/sdlthread.inc index ebc523fa..cd88c9cb 100644 --- a/units/sdlthread.inc +++ b/units/sdlthread.inc @@ -176,9 +176,20 @@ function SDL_GetThreadID(thread: PSDL_Thread): TSDL_ThreadID; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_GetThreadID' {$ENDIF}{$ENDIF}; {** - * Set the priority for the current thread - *} -function SDL_SetThreadPriority(priority: TSDL_ThreadPriority): cint32 cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetThreadPriority' {$ENDIF}{$ENDIF}; + * Set the priority for the current thread. + * + * Note that some platforms will not let you alter the priority (or at least, + * promote the thread to a higher priority) at all, and some require you to be + * an administrator account. Be prepared for this to fail. + * + * \param priority the SDL_ThreadPriority to set + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + *} +function SDL_SetThreadPriority(priority: TSDL_ThreadPriority): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetThreadPriority' {$ENDIF}{$ENDIF}; {** * Wait for a thread to finish. From 9bdbc3684ca939e6db2975cbda17129b9c6a12c0 Mon Sep 17 00:00:00 2001 From: Matthias Date: Sat, 28 Jan 2023 03:24:51 +0100 Subject: [PATCH 14/39] Update SDL_WaitThread --- units/sdlthread.inc | 40 ++++++++++++++++++++++++++++++++++------ 1 file changed, 34 insertions(+), 6 deletions(-) diff --git a/units/sdlthread.inc b/units/sdlthread.inc index cd88c9cb..3d1674e9 100644 --- a/units/sdlthread.inc +++ b/units/sdlthread.inc @@ -192,12 +192,40 @@ function SDL_SetThreadPriority(priority: TSDL_ThreadPriority): cint; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SetThreadPriority' {$ENDIF}{$ENDIF}; {** - * Wait for a thread to finish. - * - * The return code for the thread function is placed in the area - * pointed to by status, if status is not NULL. - *} -procedure SDL_WaitThread(thread: PSDL_Thread; status: pcint) cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_WaitThread' {$ENDIF}{$ENDIF}; + * Wait for a thread to finish. + * + * Threads that haven't been detached will remain (as a "zombie") until this + * function cleans them up. Not doing so is a resource leak. + * + * Once a thread has been cleaned up through this function, the SDL_Thread + * that references it becomes invalid and should not be referenced again. As + * such, only one thread may call SDL_WaitThread() on another. + * + * The return code for the thread function is placed in the area pointed to by + * `status`, if `status` is not NULL. + * + * You may not wait on a thread that has been used in a call to + * SDL_DetachThread(). Use either that function or this one, but not both, or + * behavior is undefined. + * + * It is safe to pass a NULL thread to this function; it is a no-op. + * + * Note that the thread pointer is freed by this function and is not valid + * afterward. + * + * \param thread the SDL_Thread pointer that was returned from the + * SDL_CreateThread() call that started this thread + * \param status pointer to an integer that will receive the value returned + * from the thread function by its 'return', or NULL to not + * receive such value back. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_CreateThread + * \sa SDL_DetachThread + *} +procedure SDL_WaitThread(thread: PSDL_Thread; status: pcint); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_WaitThread' {$ENDIF}{$ENDIF}; {** * A thread may be "detached" to signify that it should not remain until From bb395f386a634165624614d05aa73302f49afac6 Mon Sep 17 00:00:00 2001 From: Matthias Date: Sat, 28 Jan 2023 03:25:34 +0100 Subject: [PATCH 15/39] Update SDL_DetachThread --- units/sdlthread.inc | 61 ++++++++++++++++++++++++++------------------- 1 file changed, 35 insertions(+), 26 deletions(-) diff --git a/units/sdlthread.inc b/units/sdlthread.inc index 3d1674e9..4b9914d3 100644 --- a/units/sdlthread.inc +++ b/units/sdlthread.inc @@ -228,32 +228,41 @@ procedure SDL_WaitThread(thread: PSDL_Thread; status: pcint); cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_WaitThread' {$ENDIF}{$ENDIF}; {** - * A thread may be "detached" to signify that it should not remain until - * another thread has called SDL_WaitThread() on it. Detaching a thread - * is useful for long-running threads that nothing needs to synchronize - * with or further manage. When a detached thread is done, it simply - * goes away. - * - * There is no way to recover the return code of a detached thread. If you - * need this, don't detach the thread and instead use SDL_WaitThread(). - * - * Once a thread is detached, you should usually assume the SDL_Thread isn't - * safe to reference again, as it will become invalid immediately upon - * the detached thread's exit, instead of remaining until someone has called - * SDL_WaitThread() to finally clean it up. As such, don't detach the same - * thread more than once. - * - * If a thread has already exited when passed to SDL_DetachThread(), it will - * stop waiting for a call to SDL_WaitThread() and clean up immediately. - * It is not safe to detach a thread that might be used with SDL_WaitThread(). - * - * You may not call SDL_WaitThread() on a thread that has been detached. - * Use either that function or this one, but not both, or behavior is - * undefined. - * - * It is safe to pass NIL to this function; it is a no-op. - *} -procedure SDL_DetachThread(thread:TSDL_Thread); cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_DetachThread' {$ENDIF}{$ENDIF}; + * Let a thread clean up on exit without intervention. + * + * A thread may be "detached" to signify that it should not remain until + * another thread has called SDL_WaitThread() on it. Detaching a thread is + * useful for long-running threads that nothing needs to synchronize with or + * further manage. When a detached thread is done, it simply goes away. + * + * There is no way to recover the return code of a detached thread. If you + * need this, don't detach the thread and instead use SDL_WaitThread(). + * + * Once a thread is detached, you should usually assume the SDL_Thread isn't + * safe to reference again, as it will become invalid immediately upon the + * detached thread's exit, instead of remaining until someone has called + * SDL_WaitThread() to finally clean it up. As such, don't detach the same + * thread more than once. + * + * If a thread has already exited when passed to SDL_DetachThread(), it will + * stop waiting for a call to SDL_WaitThread() and clean up immediately. It is + * not safe to detach a thread that might be used with SDL_WaitThread(). + * + * You may not call SDL_WaitThread() on a thread that has been detached. Use + * either that function or this one, but not both, or behavior is undefined. + * + * It is safe to pass NULL to this function; it is a no-op. + * + * \param thread the SDL_Thread pointer that was returned from the + * SDL_CreateThread() call that started this thread + * + * \since This function is available since SDL 2.0.2. + * + * \sa SDL_CreateThread + * \sa SDL_WaitThread + *} +procedure SDL_DetachThread(thread:TSDL_Thread); cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_DetachThread' {$ENDIF}{$ENDIF}; {** * Create an identifier that is globally visible to all threads but refers to data that is thread-specific. From f82463d50c517e5f1c2ca5aaf4f1d6d16c33ef66 Mon Sep 17 00:00:00 2001 From: Matthias Date: Sat, 28 Jan 2023 03:27:03 +0100 Subject: [PATCH 16/39] Update SDL_TLSCreate --- units/sdlthread.inc | 43 ++++++++++++++----------------------------- 1 file changed, 14 insertions(+), 29 deletions(-) diff --git a/units/sdlthread.inc b/units/sdlthread.inc index 4b9914d3..a3763179 100644 --- a/units/sdlthread.inc +++ b/units/sdlthread.inc @@ -265,35 +265,20 @@ procedure SDL_DetachThread(thread:TSDL_Thread); cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_DetachThread' {$ENDIF}{$ENDIF}; {** - * Create an identifier that is globally visible to all threads but refers to data that is thread-specific. - * - * The newly created thread local storage identifier, or 0 on error - * - * var tls_lock: TSDL_SpinLock; - * thread_local_storage: TSDL_TLSID; - * - * procedure SetMyThreadData(value: Pointer) - * - * if not (thread_local_storage) then - * begin - * SDL_AtomicLock(@tls_lock); - * if (!thread_local_storage) - * thread_local_storage = SDL_TLSCreate(); - * - * SDL_AtomicUnLock(@tls_lock); - * - * SDL_TLSSet(thread_local_storage, value); - * end; - * - * function GetMyThreadData(): Pointer; - * begin - * Result := SDL_TLSGet(thread_local_storage); - * end; - * - * SDL_TLSGet() - * SDL_TLSSet() - *} -function SDL_TLSCreate: TSDL_TLSID cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_TLSCreate' {$ENDIF} {$ENDIF}; + * Create a piece of thread-local storage. + * + * This creates an identifier that is globally visible to all threads but + * refers to data that is thread-specific. + * + * \returns the newly created thread local storage identifier or 0 on error. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_TLSGet + * \sa SDL_TLSSet + *} +function SDL_TLSCreate: TSDL_TLSID; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_TLSCreate' {$ENDIF} {$ENDIF}; {** * Get the value associated with a thread local storage ID for the current thread. From 8f8e8a4c23215b8f498a9fe3b1f5820afda6be15 Mon Sep 17 00:00:00 2001 From: Matthias Date: Sat, 28 Jan 2023 03:28:16 +0100 Subject: [PATCH 17/39] Update SDL_TLSGet --- units/sdlthread.inc | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/units/sdlthread.inc b/units/sdlthread.inc index a3763179..7efceaae 100644 --- a/units/sdlthread.inc +++ b/units/sdlthread.inc @@ -281,16 +281,19 @@ function SDL_TLSCreate: TSDL_TLSID; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_TLSCreate' {$ENDIF} {$ENDIF}; {** - * Get the value associated with a thread local storage ID for the current thread. - * - * id The thread local storage ID - * - * The value associated with the ID for the current thread, or NULL if no value has been set. - * - * SDL_TLSCreate() - * SDL_TLSSet() - *} -function SDL_TLSGet(id: TSDL_TLSID): Pointer cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_TLSGet' {$ENDIF} {$ENDIF}; + * Get the current thread's value associated with a thread local storage ID. + * + * \param id the thread local storage ID + * \returns the value associated with the ID for the current thread or NULL if + * no value has been set; call SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_TLSCreate + * \sa SDL_TLSSet + *} +function SDL_TLSGet(id: TSDL_TLSID): Pointer; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_TLSGet' {$ENDIF} {$ENDIF}; {** * Set the value associated with a thread local storage ID for the current thread. From 1182d91643f3f1e4d419fd6bdfb1dca5d7a9689c Mon Sep 17 00:00:00 2001 From: Matthias Date: Sat, 28 Jan 2023 03:32:54 +0100 Subject: [PATCH 18/39] Update SDL_TLSSet and Add SDL_TLSCleanup --- units/sdlthread.inc | 45 +++++++++++++++++++++++++++++++++------------ 1 file changed, 33 insertions(+), 12 deletions(-) diff --git a/units/sdlthread.inc b/units/sdlthread.inc index 7efceaae..77135035 100644 --- a/units/sdlthread.inc +++ b/units/sdlthread.inc @@ -296,15 +296,36 @@ function SDL_TLSGet(id: TSDL_TLSID): Pointer; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_TLSGet' {$ENDIF} {$ENDIF}; {** - * Set the value associated with a thread local storage ID for the current thread. - * - * id The thread local storage ID - * value The value to associate with the ID for the current thread - * destructor_ A function called when the thread exits, to free the value. - * - * 0 on success, -1 on error - * - * SDL_TLSCreate() - * SDL_TLSGet() - *} -function SDL_TLSSet(id: TSDL_TLSID; value: Pointer; destructor_: Pointer): cint32 cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_TLSSet' {$ENDIF} {$ENDIF}; + * Set the current thread's value associated with a thread local storage ID. + * + * The function prototype for `destructor` is: + * + * ```c + * void destructor(void *value) + * ``` + * + * where its parameter `value` is what was passed as `value` to SDL_TLSSet(). + * + * \param id the thread local storage ID + * \param value the value to associate with the ID for the current thread + * \param destructor a function called when the thread exits, to free the + * value + * \returns 0 on success or a negative error code on failure; call + * SDL_GetError() for more information. + * + * \since This function is available since SDL 2.0.0. + * + * \sa SDL_TLSCreate + * \sa SDL_TLSGet + *} +function SDL_TLSSet(id: TSDL_TLSID; const value: Pointer; destructor_: Pointer): cint; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_TLSSet' {$ENDIF} {$ENDIF}; + +{** + * Cleanup all TLS data for this thread. + * + * \since This function is available since SDL 2.0.16. + *} +procedure SDL_TLSCleanup; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_TLSCleanup' {$ENDIF} {$ENDIF}; + From 4a791943840295c91011148da4119f90d44e6dd0 Mon Sep 17 00:00:00 2001 From: Matthias Date: Sat, 28 Jan 2023 14:49:59 +0100 Subject: [PATCH 19/39] Add cuintptr_t and cintptr_t types --- units/ctypes.inc | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/units/ctypes.inc b/units/ctypes.inc index 1345a491..e4847ba3 100644 --- a/units/ctypes.inc +++ b/units/ctypes.inc @@ -128,6 +128,16 @@ type ppcuint8 = ^pcuint8; + { "The following type designates an unsigned integer type [or signed respectivly] + with the property that any valid pointer to void can be + converted to this type, then converted back to a pointer + to void, and the result will compare equal to the original + pointer: uintptr_t" + Source: https://pubs.opengroup.org/onlinepubs/000095399/basedefs/stdint.h.html + } + cuintptr_t = PtrUInt; + cintptr_t = PtrInt; + {$IFDEF WANT_CWCHAR_T} (* wchar_t is the "wide character" type of the C language. * The size of this type is platform- and compiler-dependent. From 9fe2fb92e83d1a85c1523f6b428ce22c7be9b88e Mon Sep 17 00:00:00 2001 From: Matthias Date: Sat, 28 Jan 2023 15:10:33 +0100 Subject: [PATCH 20/39] Update TpfnSDL_CurrentBeginThread (WIP) --- units/sdlthread.inc | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/units/sdlthread.inc b/units/sdlthread.inc index 77135035..68a3a7de 100644 --- a/units/sdlthread.inc +++ b/units/sdlthread.inc @@ -78,7 +78,9 @@ type {$ENDIF} { #todo : Update this declaration! } - TpfnSDL_CurrentBeginThread = function(SecurityAttributes: Pointer; StackSize: LongWord; ThreadFunc: TThreadFunc; Parameter: Pointer; CreationFlags: LongWord; var ThreadId: TThreadID): cint; + TpfnSDL_CurrentBeginThread = function( + SecurityAttributes: Pointer; StackSize: LongWord; ThreadFunc: TThreadFunc; + Parameter: Pointer {arg}; CreationFlags: LongWord; var ThreadId: TThreadID {threadID}): cuintptr_t; TpfnSDL_CurrentEndThread = procedure(code: cuint); From df882758b2c663fb39aa1129b9d6a5cd2af6c7d8 Mon Sep 17 00:00:00 2001 From: Matthias Date: Sat, 28 Jan 2023 19:56:33 +0100 Subject: [PATCH 21/39] Fix: Re-add accidentally deleted overloaded SDL_CreateThread declaration --- units/sdlthread.inc | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/units/sdlthread.inc b/units/sdlthread.inc index 68a3a7de..67f04fad 100644 --- a/units/sdlthread.inc +++ b/units/sdlthread.inc @@ -86,9 +86,12 @@ type function SDL_CreateThread(fn: TSDL_ThreadFunction; name: PAnsiChar; data: Pointer; pfnBeginThread: TpfnSDL_CurrentBeginThread; - pfnEndThread: TpfnSDL_CurrentEndThread): PSDL_Thread; cdecl; + pfnEndThread: TpfnSDL_CurrentEndThread): PSDL_Thread; cdecl; overload; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CreateThread' {$ENDIF} {$ENDIF}; +function SDL_CreateThread(fn: TSDL_ThreadFunction; name: PAnsiChar; + data: Pointer): PSDL_Thread; overload; + function SDL_CreateThreadWithStackSize(fn: TSDL_ThreadFunction; name: PAnsiChar; const stacksize: csize_t; data: Pointer; pfnBeginThread: TpfnSDL_CurrentBeginThread; From dfa11cac3aa10170d6dcc11ef532236b14beb50b Mon Sep 17 00:00:00 2001 From: Matthias Date: Sat, 28 Jan 2023 20:33:46 +0100 Subject: [PATCH 22/39] Add comment about OS2 platform part --- units/sdlthread.inc | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/units/sdlthread.inc b/units/sdlthread.inc index 67f04fad..f4103b98 100644 --- a/units/sdlthread.inc +++ b/units/sdlthread.inc @@ -99,6 +99,15 @@ function SDL_CreateThreadWithStackSize(fn: TSDL_ThreadFunction; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CreateThreadWithStackSize' {$ENDIF} {$ENDIF}; +{ #todo : The OS2 part of SDL_thread.h is not translated, yet. + The ELSE block is covering this right now. Not sure if the + OS2 platform switch is implemented in Delphi. } +//{$ELSEIF OS2} +//{* +// * just like the windows case above: We compile SDL2 +// * into a dll with Watcom's runtime statically linked. +// *} + { #todo : THE FOLLOWING CODE UNTIL SDL_GetThreadName functions NEEDS MAJOR REVIEW } {$ELSE} From b02bc3c34d27ffec982f8c7d6e01d7a4b189d84e Mon Sep 17 00:00:00 2001 From: Matthias Date: Sat, 28 Jan 2023 20:43:01 +0100 Subject: [PATCH 23/39] Add overloaded SDL_CreateThreadWithStackSize function --- units/sdl2.pas | 7 +++++++ units/sdlthread.inc | 2 ++ 2 files changed, 9 insertions(+) diff --git a/units/sdl2.pas b/units/sdl2.pas index 2d68861b..0de27300 100644 --- a/units/sdl2.pas +++ b/units/sdl2.pas @@ -242,6 +242,13 @@ function SDL_CreateThread(fn: TSDL_ThreadFunction; name: PAnsiChar; data: Pointe Result := SDL_CreateThread(fn,name,data,nil,nil); end; +function SDL_CreateThreadWithStackSize(fn: TSDL_ThreadFunction; + name: PAnsiChar; const stacksize: csize_t; data: Pointer): PSDL_Thread; overload; +begin + Result := SDL_CreateThreadWithStackSize( + fn,name,stacksize,data,nil,nil); +end; + {$ENDIF} //from "sdl_rect.h" diff --git a/units/sdlthread.inc b/units/sdlthread.inc index f4103b98..7266c361 100644 --- a/units/sdlthread.inc +++ b/units/sdlthread.inc @@ -98,6 +98,8 @@ function SDL_CreateThreadWithStackSize(fn: TSDL_ThreadFunction; pfnEndThread: TpfnSDL_CurrentEndThread): PSDL_Thread; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CreateThreadWithStackSize' {$ENDIF} {$ENDIF}; +function SDL_CreateThreadWithStackSize(fn: TSDL_ThreadFunction; + name: PAnsiChar; const stacksize: csize_t; data: Pointer): PSDL_Thread; overload; { #todo : The OS2 part of SDL_thread.h is not translated, yet. The ELSE block is covering this right now. Not sure if the From b9dac037f916aabee2ad2a36761bda002fdcfe3c Mon Sep 17 00:00:00 2001 From: Matthias Date: Sat, 28 Jan 2023 20:44:07 +0100 Subject: [PATCH 24/39] Overload SDL_CreateThreadWithStackSize function declaration --- units/sdlthread.inc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/units/sdlthread.inc b/units/sdlthread.inc index 7266c361..039daf93 100644 --- a/units/sdlthread.inc +++ b/units/sdlthread.inc @@ -95,7 +95,7 @@ function SDL_CreateThread(fn: TSDL_ThreadFunction; name: PAnsiChar; function SDL_CreateThreadWithStackSize(fn: TSDL_ThreadFunction; name: PAnsiChar; const stacksize: csize_t; data: Pointer; pfnBeginThread: TpfnSDL_CurrentBeginThread; - pfnEndThread: TpfnSDL_CurrentEndThread): PSDL_Thread; cdecl; + pfnEndThread: TpfnSDL_CurrentEndThread): PSDL_Thread; cdecl; overload; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CreateThreadWithStackSize' {$ENDIF} {$ENDIF}; function SDL_CreateThreadWithStackSize(fn: TSDL_ThreadFunction; From b42b4eed83dd451b55fd0d7bdd3c03f8483b3515 Mon Sep 17 00:00:00 2001 From: Matthias Date: Sat, 28 Jan 2023 20:49:05 +0100 Subject: [PATCH 25/39] Re-arrange param. list in SDL_CreateThread/+WithStackSize function declaration --- units/sdl2.pas | 6 ++++-- units/sdlthread.inc | 7 ++++--- 2 files changed, 8 insertions(+), 5 deletions(-) diff --git a/units/sdl2.pas b/units/sdl2.pas index 0de27300..5a77950f 100644 --- a/units/sdl2.pas +++ b/units/sdl2.pas @@ -237,13 +237,15 @@ function SDL_Button(X: cint): cint; {$IFDEF WINDOWS} //from "sdl_thread.h" -function SDL_CreateThread(fn: TSDL_ThreadFunction; name: PAnsiChar; data: Pointer): PSDL_Thread; overload; +function SDL_CreateThread(fn: TSDL_ThreadFunction; name: PAnsiChar; + data: Pointer): PSDL_Thread; overload; begin Result := SDL_CreateThread(fn,name,data,nil,nil); end; function SDL_CreateThreadWithStackSize(fn: TSDL_ThreadFunction; - name: PAnsiChar; const stacksize: csize_t; data: Pointer): PSDL_Thread; overload; + name: PAnsiChar; const stacksize: csize_t; data: Pointer + ): PSDL_Thread; overload; begin Result := SDL_CreateThreadWithStackSize( fn,name,stacksize,data,nil,nil); diff --git a/units/sdlthread.inc b/units/sdlthread.inc index 039daf93..8f34b031 100644 --- a/units/sdlthread.inc +++ b/units/sdlthread.inc @@ -84,7 +84,8 @@ type TpfnSDL_CurrentEndThread = procedure(code: cuint); -function SDL_CreateThread(fn: TSDL_ThreadFunction; name: PAnsiChar; data: Pointer; +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}; @@ -98,8 +99,8 @@ function SDL_CreateThreadWithStackSize(fn: TSDL_ThreadFunction; pfnEndThread: TpfnSDL_CurrentEndThread): PSDL_Thread; cdecl; overload; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CreateThreadWithStackSize' {$ENDIF} {$ENDIF}; -function SDL_CreateThreadWithStackSize(fn: TSDL_ThreadFunction; - name: PAnsiChar; const stacksize: csize_t; data: Pointer): PSDL_Thread; overload; +function SDL_CreateThreadWithStackSize(fn: TSDL_ThreadFunction; name: PAnsiChar; + const stacksize: csize_t; data: Pointer): PSDL_Thread; overload; { #todo : The OS2 part of SDL_thread.h is not translated, yet. The ELSE block is covering this right now. Not sure if the From a43c0375bdff8066ba260d6f812087fa2d7c6a85 Mon Sep 17 00:00:00 2001 From: Matthias Date: Sat, 28 Jan 2023 20:51:44 +0100 Subject: [PATCH 26/39] Remove comment (review finished) --- units/sdlthread.inc | 1 - 1 file changed, 1 deletion(-) diff --git a/units/sdlthread.inc b/units/sdlthread.inc index 8f34b031..5b74aac0 100644 --- a/units/sdlthread.inc +++ b/units/sdlthread.inc @@ -111,7 +111,6 @@ function SDL_CreateThreadWithStackSize(fn: TSDL_ThreadFunction; name: PAnsiChar; // * into a dll with Watcom's runtime statically linked. // *} -{ #todo : THE FOLLOWING CODE UNTIL SDL_GetThreadName functions NEEDS MAJOR REVIEW } {$ELSE} {** From f0579bf82102ab68943c6001f43bf286140cdafe Mon Sep 17 00:00:00 2001 From: Matthias Date: Tue, 31 Jan 2023 19:56:40 +0100 Subject: [PATCH 27/39] Extend 2 comments (open questions) --- units/sdlthread.inc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/units/sdlthread.inc b/units/sdlthread.inc index 5b74aac0..177a6258 100644 --- a/units/sdlthread.inc +++ b/units/sdlthread.inc @@ -72,12 +72,12 @@ type {$DEFINE SDL_PASSED_BEGINTHREAD_ENDTHREAD} type - { #todo : Needed? } + { SDL2-for-Pascal: #todo : Needed? } {$IFNDEF DELPHI16UP} TThreadID = Cardinal; {$ENDIF} - { #todo : Update this declaration! } + { SDL2-for-Pascal #todo : Explanation needed } TpfnSDL_CurrentBeginThread = function( SecurityAttributes: Pointer; StackSize: LongWord; ThreadFunc: TThreadFunc; Parameter: Pointer {arg}; CreationFlags: LongWord; var ThreadId: TThreadID {threadID}): cuintptr_t; From 1b883c478f7f1e9ed3dc770ee47bc556129cad8a Mon Sep 17 00:00:00 2001 From: Matthias Date: Tue, 31 Jan 2023 20:13:14 +0100 Subject: [PATCH 28/39] Exclude (re-)declaration of TThreadID for FPC --- units/sdlthread.inc | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/units/sdlthread.inc b/units/sdlthread.inc index 177a6258..33143364 100644 --- a/units/sdlthread.inc +++ b/units/sdlthread.inc @@ -73,8 +73,10 @@ type type { SDL2-for-Pascal: #todo : Needed? } - {$IFNDEF DELPHI16UP} - TThreadID = Cardinal; + {$IFNDEF FPC} + {$IFNDEF DELPHI16UP} + TThreadID = Cardinal; + {$ENDIF} {$ENDIF} { SDL2-for-Pascal #todo : Explanation needed } From e8ec17e7ae3337852f5385f8c8d15e6960b11877 Mon Sep 17 00:00:00 2001 From: Matthias Date: Tue, 31 Jan 2023 20:20:50 +0100 Subject: [PATCH 29/39] Add SDL_CreateThreadWithStackSize for ELSE-block --- units/sdlthread.inc | 48 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/units/sdlthread.inc b/units/sdlthread.inc index 33143364..92513b15 100644 --- a/units/sdlthread.inc +++ b/units/sdlthread.inc @@ -137,6 +137,54 @@ 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}; +{** + * Create a new thread with a specific stack size. + * + * SDL makes an attempt to report `name` to the system, so that debuggers can + * display it. Not all platforms support this. + * + * Thread naming is a little complicated: Most systems have very small limits + * for the string length (Haiku has 32 bytes, Linux currently has 16, Visual + * C++ 6.0 has _nine_!), and possibly other arbitrary rules. You'll have to + * see what happens with your system's debugger. The name should be UTF-8 (but + * using the naming limits of C identifiers is a better bet). There are no + * requirements for thread naming conventions, so long as the string is + * null-terminated UTF-8, but these guidelines are helpful in choosing a name: + * + * https://stackoverflow.com/questions/149932/naming-conventions-for-threads + * + * If a system imposes requirements, SDL will try to munge the string for it + * (truncate, etc), but the original string contents will be available from + * SDL_GetThreadName(). + * + * The size (in bytes) of the new stack can be specified. Zero means "use the + * system default" which might be wildly different between platforms. x86 + * Linux generally defaults to eight megabytes, an embedded device might be a + * few kilobytes instead. You generally need to specify a stack that is a + * multiple of the system's page size (in many cases, this is 4 kilobytes, but + * check your system documentation). + * + * In SDL 2.1, stack size will be folded into the original SDL_CreateThread + * function, but for backwards compatibility, this is currently a separate + * function. + * + * \param fn the SDL_ThreadFunction function to call in the new thread + * \param name the name of the thread + * \param stacksize the size, in bytes, to allocate for the new thread stack. + * \param data a pointer that is passed to `fn` + * \returns an opaque pointer to the new thread object on success, NULL if the + * new thread could not be created; call SDL_GetError() for more + * information. + * + * \since This function is available since SDL 2.0.9. + * + * \sa SDL_WaitThread + *} +function SDL_CreateThreadWithStackSize(fn: TSDL_ThreadFunction; name: PAnsiChar; + stacksize: csize_t; data: Pointer): PSDL_Thread; cdecl; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SDL_CreateThreadWithStackSize' {$ENDIF} {$ENDIF}; + + {$ENDIF} {** From e219cbe79abe96ecd95d1ca4a8c2ba6d305c1827 Mon Sep 17 00:00:00 2001 From: Matthias Date: Tue, 31 Jan 2023 20:42:47 +0100 Subject: [PATCH 30/39] Update comment of OS2-block --- units/sdlthread.inc | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/units/sdlthread.inc b/units/sdlthread.inc index 92513b15..a1a6f337 100644 --- a/units/sdlthread.inc +++ b/units/sdlthread.inc @@ -104,7 +104,8 @@ function SDL_CreateThreadWithStackSize(fn: TSDL_ThreadFunction; function SDL_CreateThreadWithStackSize(fn: TSDL_ThreadFunction; name: PAnsiChar; const stacksize: csize_t; data: Pointer): PSDL_Thread; overload; -{ #todo : The OS2 part of SDL_thread.h is not translated, yet. +{ SDL2-For-Pascal: #todo : + The OS2 part of SDL_thread.h is not translated, yet. The ELSE block is covering this right now. Not sure if the OS2 platform switch is implemented in Delphi. } //{$ELSEIF OS2} @@ -113,6 +114,8 @@ function SDL_CreateThreadWithStackSize(fn: TSDL_ThreadFunction; name: PAnsiChar; // * into a dll with Watcom's runtime statically linked. // *} +{ ... } + {$ELSE} {** From 59494a89ffbabdb2f1e556942a82bab199457cf6 Mon Sep 17 00:00:00 2001 From: Matthias Date: Tue, 31 Jan 2023 21:08:18 +0100 Subject: [PATCH 31/39] Re-arrange SDL_CreateThread macro and add comment --- units/sdlthread.inc | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/units/sdlthread.inc b/units/sdlthread.inc index a1a6f337..2d3e14cd 100644 --- a/units/sdlthread.inc +++ b/units/sdlthread.inc @@ -86,24 +86,29 @@ type TpfnSDL_CurrentEndThread = procedure(code: cuint); + 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}; -function SDL_CreateThread(fn: TSDL_ThreadFunction; name: PAnsiChar; - data: Pointer): PSDL_Thread; overload; - function SDL_CreateThreadWithStackSize(fn: TSDL_ThreadFunction; name: PAnsiChar; const stacksize: csize_t; data: Pointer; pfnBeginThread: TpfnSDL_CurrentBeginThread; pfnEndThread: TpfnSDL_CurrentEndThread): PSDL_Thread; cdecl; overload; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CreateThreadWithStackSize' {$ENDIF} {$ENDIF}; +{ SDL2-For-Pascal: #note : In the C header are two versions + of these macro functions. One for SDL's dynamic API and one without. + We can go with this for the moment. Improvement surely possible. } +function SDL_CreateThread(fn: TSDL_ThreadFunction; name: PAnsiChar; + data: Pointer): PSDL_Thread; overload; + function SDL_CreateThreadWithStackSize(fn: TSDL_ThreadFunction; name: PAnsiChar; const stacksize: csize_t; data: Pointer): PSDL_Thread; overload; + { SDL2-For-Pascal: #todo : The OS2 part of SDL_thread.h is not translated, yet. The ELSE block is covering this right now. Not sure if the From 590d3a7acc96e337211a1c829fd6b1b3c0e3bace Mon Sep 17 00:00:00 2001 From: Matthias Date: Tue, 31 Jan 2023 21:18:51 +0100 Subject: [PATCH 32/39] Add version tag 2.26.2 for sdlthread.inc --- units/sdl2.pas | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/units/sdl2.pas b/units/sdl2.pas index 5a77950f..d3a48e79 100644 --- a/units/sdl2.pas +++ b/units/sdl2.pas @@ -163,7 +163,7 @@ interface {$I sdlerror.inc} // 2.0.14 {$I sdlplatform.inc} // 2.0.14 {$I sdlpower.inc} // 2.0.14 -{$I sdlthread.inc} +{$I sdlthread.inc} // 2.26.2 {$I sdlatomic.inc} // 2.0.20 {$I sdlmutex.inc} // 2.0.14 WIP {$I sdltimer.inc} // 2.0.18 From fe796f1ae520123bc9e7c4b95c98c6597e5933d5 Mon Sep 17 00:00:00 2001 From: Matthias Date: Tue, 21 Mar 2023 23:24:17 +0100 Subject: [PATCH 33/39] Add EXTERNALSYM for cintptr_t and cuintptr_t --- units/ctypes.inc | 2 ++ 1 file changed, 2 insertions(+) diff --git a/units/ctypes.inc b/units/ctypes.inc index e4847ba3..00529426 100644 --- a/units/ctypes.inc +++ b/units/ctypes.inc @@ -136,7 +136,9 @@ type Source: https://pubs.opengroup.org/onlinepubs/000095399/basedefs/stdint.h.html } cuintptr_t = PtrUInt; + {$EXTERNALSYM cuintptr_t} cintptr_t = PtrInt; + {$EXTERNALSYM cintptr_t} {$IFDEF WANT_CWCHAR_T} (* wchar_t is the "wide character" type of the C language. From e4e241a1ba625633744832846c2aa3169a495286 Mon Sep 17 00:00:00 2001 From: Matthias Date: Tue, 21 Mar 2023 23:28:46 +0100 Subject: [PATCH 34/39] Remove MacOS-IFDEFs in WINDOWS block --- units/sdlthread.inc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/units/sdlthread.inc b/units/sdlthread.inc index 2d3e14cd..5f996a06 100644 --- a/units/sdlthread.inc +++ b/units/sdlthread.inc @@ -91,13 +91,13 @@ 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}; + external SDL_LibName; function SDL_CreateThreadWithStackSize(fn: TSDL_ThreadFunction; name: PAnsiChar; const stacksize: csize_t; data: Pointer; pfnBeginThread: TpfnSDL_CurrentBeginThread; pfnEndThread: TpfnSDL_CurrentEndThread): PSDL_Thread; cdecl; overload; - external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CreateThreadWithStackSize' {$ENDIF} {$ENDIF}; + external SDL_LibName; { SDL2-For-Pascal: #note : In the C header are two versions of these macro functions. One for SDL's dynamic API and one without. From 217d95f9877b73eb6d3bf500369e1e97d744c889 Mon Sep 17 00:00:00 2001 From: Matthias Date: Tue, 21 Mar 2023 23:30:03 +0100 Subject: [PATCH 35/39] Fix: Remove doubled prefix SDL_ --- units/sdlthread.inc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/units/sdlthread.inc b/units/sdlthread.inc index 5f996a06..ef659466 100644 --- a/units/sdlthread.inc +++ b/units/sdlthread.inc @@ -190,7 +190,7 @@ function SDL_CreateThread(fn: TSDL_ThreadFunction; name: PAnsiChar; *} function SDL_CreateThreadWithStackSize(fn: TSDL_ThreadFunction; name: PAnsiChar; stacksize: csize_t; data: Pointer): PSDL_Thread; cdecl; - external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_SDL_CreateThreadWithStackSize' {$ENDIF} {$ENDIF}; + external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_CreateThreadWithStackSize' {$ENDIF} {$ENDIF}; {$ENDIF} From e7a09e435971f6d38c199e694216a9b600cafbdc Mon Sep 17 00:00:00 2001 From: Matthias Date: Tue, 21 Mar 2023 23:49:45 +0100 Subject: [PATCH 36/39] Fix: adds 2 missing cdecl's --- units/sdlthread.inc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/units/sdlthread.inc b/units/sdlthread.inc index ef659466..2286251c 100644 --- a/units/sdlthread.inc +++ b/units/sdlthread.inc @@ -82,9 +82,9 @@ type { SDL2-for-Pascal #todo : Explanation needed } TpfnSDL_CurrentBeginThread = function( SecurityAttributes: Pointer; StackSize: LongWord; ThreadFunc: TThreadFunc; - Parameter: Pointer {arg}; CreationFlags: LongWord; var ThreadId: TThreadID {threadID}): cuintptr_t; + Parameter: Pointer {arg}; CreationFlags: LongWord; var ThreadId: TThreadID {threadID}): cuintptr_t; cdecl; - TpfnSDL_CurrentEndThread = procedure(code: cuint); + TpfnSDL_CurrentEndThread = procedure(code: cuint); cdecl; function SDL_CreateThread(fn: TSDL_ThreadFunction; name: PAnsiChar; From c8b2e48367fae2e4c118d785f82cf0d77222dcc5 Mon Sep 17 00:00:00 2001 From: Matthias Date: Sun, 28 May 2023 00:10:42 +0200 Subject: [PATCH 37/39] Add TTLSDestructor function pointer and use it in SDL_TLSSet --- units/sdlthread.inc | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/units/sdlthread.inc b/units/sdlthread.inc index 2286251c..f3543641 100644 --- a/units/sdlthread.inc +++ b/units/sdlthread.inc @@ -369,6 +369,15 @@ function SDL_TLSCreate: TSDL_TLSID; cdecl; function SDL_TLSGet(id: TSDL_TLSID): Pointer; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_TLSGet' {$ENDIF} {$ENDIF}; +type + { SDL2-For-Pascal: This function pointer is introduced to specifiy the + destructor pointer in the SDL_TLSSet function + according to C headers. + + The TTLSDestructor type itself is not defined + by the original SDL2 headers. } + TTLSDestructor = procedure(value: Pointer); cdecl; + {** * Set the current thread's value associated with a thread local storage ID. * @@ -392,7 +401,7 @@ function SDL_TLSGet(id: TSDL_TLSID): Pointer; cdecl; * \sa SDL_TLSCreate * \sa SDL_TLSGet *} -function SDL_TLSSet(id: TSDL_TLSID; const value: Pointer; destructor_: Pointer): cint; cdecl; +function SDL_TLSSet(id: TSDL_TLSID; const value: Pointer; destructor_: TTLSDestructor): cint; cdecl; external SDL_LibName {$IFDEF DELPHI} {$IFDEF MACOS} name '_SDL_TLSSet' {$ENDIF} {$ENDIF}; {** From 2cba02c2b723f733813478bc7af6dc0d67dca294 Mon Sep 17 00:00:00 2001 From: Matthias Date: Sun, 28 May 2023 00:20:48 +0200 Subject: [PATCH 38/39] TpfnSDL_CurrentBeginThread: Replace LongWord by cuint --- units/sdlthread.inc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/units/sdlthread.inc b/units/sdlthread.inc index f3543641..45e14ade 100644 --- a/units/sdlthread.inc +++ b/units/sdlthread.inc @@ -81,8 +81,8 @@ type { SDL2-for-Pascal #todo : Explanation needed } TpfnSDL_CurrentBeginThread = function( - SecurityAttributes: Pointer; StackSize: LongWord; ThreadFunc: TThreadFunc; - Parameter: Pointer {arg}; CreationFlags: LongWord; var ThreadId: TThreadID {threadID}): cuintptr_t; cdecl; + SecurityAttributes: Pointer; StackSize: cuint; ThreadFunc: TThreadFunc; + Parameter: Pointer {arg}; CreationFlags: cuint; var ThreadId: TThreadID {threadID}): cuintptr_t; cdecl; TpfnSDL_CurrentEndThread = procedure(code: cuint); cdecl; From 80de970741375338589082baabffb801dcee03d6 Mon Sep 17 00:00:00 2001 From: Matthias Date: Wed, 1 May 2024 14:41:33 +0200 Subject: [PATCH 39/39] Update sdlthread.inc version --- units/sdl2.pas | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/units/sdl2.pas b/units/sdl2.pas index ba8fcfff..89bcd16a 100644 --- a/units/sdl2.pas +++ b/units/sdl2.pas @@ -131,7 +131,7 @@ interface {$I sdlerror.inc} // 2.0.14 {$I sdlplatform.inc} // 2.0.14 {$I sdlpower.inc} // 2.0.14 -{$I sdlthread.inc} // 2.26.2 +{$I sdlthread.inc} // 2.30.2 {$I sdlatomic.inc} // 2.0.20 {$I sdlmutex.inc} // 2.26.5 {$I sdltimer.inc} // 2.0.18