SDL_CREATETHREADWITHPROPERTIES(3)

✨ SDL_CreateThreadWithProperties ✨

okay bestie, welcome to the SDL3 FUNCTIONS corner of the manual, where we're about to spawn a whole entire thread 💖 no cap, this one's a lil fancy — it's the properties-based glow-up of thread creation.

---

🎀 NAME 🎀

SDL_CreateThreadWithProperties — create a new thread with with the specified properties. yes, "with with". the original said it like that and honestly? iconic. we don't edit the queen's typo 💅

---

🌸 SYNOPSIS 🌸

#include <SDL3/SDL_thread.h>

SDL_Thread * SDL_CreateThreadWithProperties(SDL_PropertiesID props);

---

🦋 DESCRIPTION 🦋

so like, here's the tea ☕ — these are the supported properties:

• SDL_PROP_THREAD_CREATE_ENTRY_FUNCTION_POINTER — an SDL_ThreadFunction value that gets called right at the start of the new thread's whole life. Required. you literally cannot skip this one, it's the main character.
• SDL_PROP_THREAD_CREATE_NAME_STRING — the name of the new thread, which might be available to debuggers. optional, defaults to NULL.
• SDL_PROP_THREAD_CREATE_USERDATA_POINTER — an arbitrary app-defined pointer, passed to the entry function on the new thread as its only parameter. optional, defaults to NULL.
• SDL_PROP_THREAD_CREATE_STACKSIZE_NUMBER — the size, in bytes, of the new thread's stack. optional, defaults to 0 (system-defined default).

SDL makes an attempt to report SDL_PROP_THREAD_CREATE_NAME_STRING to the system, so that debuggers can display it. not all platforms support this, so don't come for SDL if your debugger acts brand new 🙈

thread naming is a little complicated, ngl: 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 with SDL_PROP_THREAD_CREATE_STACKSIZE_NUMBER. 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). fr fr, go check.

💀 plot twist alert 💀 note that this "function" is actually a macro that calls an internal function with two extra parameters not listed here; they are hidden through preprocessor macros and are needed to support various C runtimes at the point of the function call. language bindings that aren't using the C headers will need to deal with this. so like… it's giving fake function. it's giving macro in a trench coat.

the actual symbol in SDL is SDL_CreateThreadWithPropertiesRuntime, so there is no symbol clash, but trying to load an SDL shared library and look for "SDL_CreateThreadWithProperties" will fail. 💀

usually, apps should just call this function the same way on every platform and let the macros hide the details. slay, that's the whole point.

---

🌈 FUNCTION PARAMETERS 🌈

• props — the properties to use.

---

⭐ RETURN VALUE ⭐

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. so if you get NULL, bestie, go read the error, don't just sit there 😭

---

💜 THREAD SAFETY 💜

it is safe to call this function from any thread. periodt. no anxiety needed.

---

🧚 AVAILABILITY 🧚

this function is available since SDL 3.2.0.

---

👑 SEE ALSO 👑

• SDL_CreateThread(3)
• SDL_WaitThread(3)

---

okay that's the whole page, you ate that 💅 go forth and spawn threads responsibly 🦋

— with love, from the Simple Directmedia Layer, version SDL 3.4.18 🎀 (that's the source + version deets, bestie, we keep receipts) ✨