SDL_CreateRWLock(3)

✨ SDL_CreateRWLock(3) ✨

okay bestie, welcome to the read/write lock factory 💖 this page lives in the SDL3 functions section of the manual, and it's literally just about making one (1) brand new rwlock. let's get into it 🫶

---

🌸 NAME 🌸

SDL_CreateRWLock — Create a new read/write lock.

---

💅 SYNOPSIS 💅

#include <SDL3/SDL_mutex.h>

SDL_RWLock * SDL_CreateRWLock(void);

---

🦋 DESCRIPTION 🦋

so picture this: you've got a resource that everybody wants to read and basically nobody wants to change. that's the rwlock's whole moment. a read/write lock is useful for situations where you have multiple threads trying to access a resource that is rarely updated. all the threads asking for a read-only lock get to run in parallel, no fighting, no queue — iconic. but the second a thread asks for a write lock, it gets exclusive access, like the bouncer at the door. which means it's safe for multiple threads to use a resource at the same time if they promise not to change it, and when it does have to be changed, the rwlock acts as a gateway making sure those changes can be made safely. no chaos, no drama 💖

in the right situation, a rwlock can be more efficient than a mutex — because a mutex only lets a single thread proceed at a time, even if that thread isn't even modifying the data. rude, honestly. 💀

every newly-created read/write lock begins in the unlocked state. fresh out the box, chill, no one's holding it ✨

heads up though: calls to SDL_LockRWLockForReading() and SDL_LockRWLockForWriting will not return while the rwlock is locked for writing by another thread. they'll just... wait there. if you don't vibe with blocking, go look at SDL_TryLockRWLockForReading() and SDL_TryLockRWLockForWriting() to attempt to lock without blocking 👑

now the important lore, because this is where people get got:

• SDL read/write locks are only recursive for read-only locks! 🔁
• They are not guaranteed to be fair, or provide access in a FIFO manner!
• They are not guaranteed to favor writers.
• You may not lock a rwlock for both read-only and write access at the same time from the same thread — so you can't promote your read-only lock to a write lock without unlocking first. no glow-ups mid-lock, sorry bestie 😭

fr fr read those last four bullets again. they are not decorative. they will find you. 👀

---

🎀 RETURN VALUE 🎀

returns the initialized and unlocked read/write lock — or NULL on failure. if you get NULL, call SDL_GetError() for more information, she'll tell you what went wrong 🥺

---

🌈 THREAD SAFETY 🌈

it is safe to call this function from any thread. go off, all of you, simultaneously 💅✨

---

⭐ AVAILABILITY ⭐

this function is available since SDL 3.2.0.

---

🔥 SEE ALSO 🔥

• SDL_DestroyRWLock(3)
• SDL_LockRWLockForReading(3)
• SDL_LockRWLockForWriting(3)
• SDL_TryLockRWLockForReading(3)
• SDL_TryLockRWLockForWriting(3)
• SDL_UnlockRWLock(3)

---

okay that's the whole page, you ate it, go lock something responsibly 🫶💖 this lil writeup came from Simple Directmedia Layer, covering SDL 3.4.18, and it's the SDL_CreateRWLock(3) page — mwah, periodt. 👑