SDL_WaitThread(3)

📦
version 3.4.18 · 10 versions
, in fedora 43, fedora 44

💖 SDL_WaitThread 💖

okay bestie, so this is a page from the SDL3 FUNCTIONS manual — the one and only SDL_WaitThread(3) — and we're gonna make it make sense, fr fr. no cap.

✨ NAME ✨

SDL_WaitThread — bestie, it just waits for a thread to finish. that's the whole vibe. patient queen energy. 💅

🌸 SYNOPSIS 🌸

#include <SDL3/SDL_thread.h>

void SDL_WaitThread(SDL_Thread *thread, int *status);

🦋 DESCRIPTION 🦋

okay so here's the tea: threads that haven't been detached will literally just stay there until this function comes along and cleans them up. and if you don't do it?? that's a resource leak. like, not cute at all. clean up after yourself, bestie. 🧹✨

Once a thread has been cleaned up through this function, the SDL_Thread that references it becomes invalid and should not be referenced again. so like… it's gone gone. 💀 As such, only one thread may call SDL_WaitThread() on another. one waiter per thread, that's the rule, periodt.

The return code from the thread function gets placed in the area pointed to by status — if status is not NULL, obviously. if it is NULL, we just vibe and don't collect it.

⚠️ MAJOR WARNING ⚠️ 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. pick a lane, babes. 🚫

Good news tho: it is safe to pass a NULL thread to this function — it's a no-op. nothing happens. it's giving "I showed up but there was no party." 🎀

Also note: the thread pointer is freed by this function and is not valid afterward. so don't go touching it after, iykyk. 🙈

👑 FUNCTION PARAMETERS 👑

  • thread — the SDL_Thread pointer that was returned from the SDL_CreateThread() call that started this thread. yes, the exact one. the og. the main character. ⭐
  • status — a pointer filled in with the value returned from the thread function by its 'return', or -1 if the thread has been detached or isn't valid. may be NULL. so it's either the real answer, -1, or you just don't ask. 🌈

🔥 THREAD SAFETY 🔥

It is safe to call this function from any thread — everyone's invited to the function, no gatekeeping. 💜

BUT only a single thread can wait any specific thread to finish. one waiter per thread, we said it, we meant it. 🫶

⭐ AVAILABILITY ⭐

This function is available since SDL 3.2.0. so if you're on something older… bestie. upgrade. 😭

💀 SEE ALSO 💀

and that's the whole page, bestie!! go forth and wait on your threads responsibly — one waiter, no leaks, no double-dipping with SDL_DetachThread, and don't touch the pointer after. slay. 💅✨

this lil manual page came from the Simple Directmedia Layer crew, it's SDL 3.4.18, and it's dated SDL_WaitThread(3) — mwah, ty for coming to my ted talk 🫶🌸

📦 where this page comes from