SDL_SetTLS(3)

💖 SDL_SetTLS — set the current thread's vibe (aka its thread local storage value) 💖

okay bestie, welcome to the SDL3 FUNCTIONS corner of the manual, where we're talking about SDL_SetTLS — the girl whose whole job is giving the current thread its very own lil value tied to a thread local storage ID. no sharing, no drama, just per-thread main character energy. 🎀

---

✨ SYNOPSIS ✨

#include <SDL3/SDL_thread.h>

bool SDL_SetTLS(SDL_TLSID *id, const void *value, SDL_TLSDestructorCallback destructor);

like… one function call and your thread is set up fr fr. 🦋

---

🌸 DESCRIPTION 🌸

so here's the tea. if the thread local storage ID isn't initialized yet — and by "isn't initialized" we mean its value is 0 — then a brand new ID gets created, and it happens in a thread-safe way. which means every single call that passes a pointer to that same ID will end up referring to the same local storage. no cap, they all vibe with the same little storage locker. 🔥

💀 and now the important part, the part that lowkey ruins people's whole day: if you're replacing a value that a previous call to this function set on the same thread, that previous value's destructor is _not_ called. NOT called. the old value just… gets ghosted. no cleanup, no goodbye, nothing. so if you were counting on that destructor to free your stuff, bestie, it's not happening. 🙈

and about that destructor — it's totally allowed to be NULL! if it is, the assumption is simply that value doesn't need to be cleaned up at all. easy, no obligations, we love a low-maintenance parameter. ✨

---

🌈 FUNCTION PARAMETERS 🌈

• id — a pointer to the thread local storage ID. and listen, this one may not be NULL. it's giving required. don't test it. 💅
• value — the value you wanna associate with that ID, for the current thread specifically.
• destructor — a function that gets called when the thread exits, and its whole purpose in life is to free the value. it may be NULL. 🫶

---

⭐ RETURN VALUE ⭐

returns true on success, or false on failure. and if it fails? call SDL_GetError() for more info, because the function itself is not gonna elaborate. iconic of it honestly. 😭

---

🧚 THREAD SAFETY 🧚

it is safe to call this function from any thread. every thread, all at once, go off queens. 👑

---

💜 AVAILABILITY 💜

this function has been available since SDL 3.2.0. so if you're on something older, this one's not for you, sorry babe. 🌸

---

🎀 SEE ALSO 🎀

• SDL_GetTLS(3)

---

and that's the whole page, bestie!! this lil masterpiece came to you from the Simple Directmedia Layer girlies, version SDL 3.4.18, and the SDL_SetTLS(3) page itself. go set some TLS, slay responsibly, and remember: destructor or no destructor, that old value is NOT getting cleaned up. 💅✨🦋