mirror
/
SDL
mirror of https://github.com/libsdl-org/SDL.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Sync SDL3 wiki -> header

This commit is contained in:
SDL Wiki Bot 2023-04-28 01:55:15 +00:00
parent e474047ff8
commit 38d22aed67
1 changed files with 61 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

124
include/SDL3/SDL_mutex.h
View File

@ -257,35 +257,33 @@ typedef struct SDL_rwlock SDL_rwlock;
/** /**
* Create a new read/write lock. * Create a new read/write lock.
* *
* A read/write lock is useful for situations where you have multiple * A read/write lock is useful for situations where you have multiple threads
* threads trying to access a resource that is rarely updated. All threads * trying to access a resource that is rarely updated. All threads requesting
* requesting a read-only lock will be allowed to run in parallel; if a * a read-only lock will be allowed to run in parallel; if a thread requests a
* thread requests a write lock, it will be provided exclusive access. * write lock, it will be provided exclusive access. This makes it safe for
* This makes it safe for multiple threads to use a resource at the same * multiple threads to use a resource at the same time if they promise not to
* time if they promise not to change it, and when it has to be changed, * change it, and when it has to be changed, the rwlock will serve as a
* the rwlock will serve as a gateway to make sure those changes can be * gateway to make sure those changes can be made safely.
* made safely.
* *
* In the right situation, a rwlock can be more efficient than a mutex, * In the right situation, a rwlock can be more efficient than a mutex, which
* which only lets a single thread proceed at a time, even if it won't be * only lets a single thread proceed at a time, even if it won't be modifying
* modifying the data. * the data.
* *
* All newly-created read/write locks begin in the _unlocked_ state. * All newly-created read/write locks begin in the _unlocked_ state.
* *
* Calls to SDL_LockRWLockForReading() and SDL_LockRWLockForWriting will * Calls to SDL_LockRWLockForReading() and SDL_LockRWLockForWriting will not
* not return while the rwlock is locked _for writing_ by another thread. * return while the rwlock is locked _for writing_ by another thread. See
* See SDL_TryLockRWLockForReading() and SDL_TryLockRWLockForWriting() to * SDL_TryLockRWLockForReading() and SDL_TryLockRWLockForWriting() to attempt
* attempt to lock without blocking. * to lock without blocking.
* *
* SDL read/write locks are only recursive for read-only locks! They * SDL read/write locks are only recursive for read-only locks! They are not
* are not guaranteed to be fair, or provide access in a FIFO manner! They * guaranteed to be fair, or provide access in a FIFO manner! They are not
* are not guaranteed to favor writers. You may not lock a rwlock for * guaranteed to favor writers. You may not lock a rwlock for both read-only
* both read-only and write access at the same time from the same thread * and write access at the same time from the same thread (so you can't
* (so you can't promote your read-only lock to a write lock without * promote your read-only lock to a write lock without unlocking first).
* unlocking first).
* *
* \returns the initialized and unlocked read/write lock or NULL on * \returns the initialized and unlocked read/write lock or NULL on failure;
* failure; call SDL_GetError() for more information. * call SDL_GetError() for more information.
* *
* \since This function is available since SDL 3.0.0. * \since This function is available since SDL 3.0.0.
* *
@ -301,25 +299,25 @@ extern DECLSPEC SDL_rwlock *SDLCALL SDL_CreateRWLock(void);
/** /**
* Lock the read/write lock for _read only_ operations. * Lock the read/write lock for _read only_ operations.
* *
* This will block until the rwlock is available, which is to say it is * This will block until the rwlock is available, which is to say it is not
* not locked for writing by any other thread. Of all threads waiting to * locked for writing by any other thread. Of all threads waiting to lock the
* lock the rwlock, all may do so at the same time as long as they are * rwlock, all may do so at the same time as long as they are requesting
* requesting read-only access; if a thread wants to lock for writing, * read-only access; if a thread wants to lock for writing, only one may do so
* only one may do so at a time, and no other threads, read-only or not, * at a time, and no other threads, read-only or not, may hold the lock at the
* may hold the lock at the same time. * same time.
* *
* It is legal for the owning thread to lock an already-locked rwlock * It is legal for the owning thread to lock an already-locked rwlock for
* for reading. It must unlock it the same number of times before it is * reading. It must unlock it the same number of times before it is actually
* actually made available for other threads in the system (this is known * made available for other threads in the system (this is known as a
* as a "recursive rwlock"). * "recursive rwlock").
* *
* Note that locking for writing is not recursive (this is only available * Note that locking for writing is not recursive (this is only available to
* to read-only locks). * read-only locks).
* *
* It is illegal to request a read-only lock from a thread that already * It is illegal to request a read-only lock from a thread that already holds
* holds the write lock. Doing so results in undefined behavior. Unlock the * the write lock. Doing so results in undefined behavior. Unlock the write
* write lock before requesting a read-only lock. (But, of course, if you * lock before requesting a read-only lock. (But, of course, if you have the
* have the write lock, you don't need further locks to read in any case.) * write lock, you don't need further locks to read in any case.)
* *
* \param rwlock the read/write lock to lock * \param rwlock the read/write lock to lock
* \returns 0 on success or a negative error code on failure; call * \returns 0 on success or a negative error code on failure; call
@ -334,18 +332,18 @@ extern DECLSPEC int SDLCALL SDL_LockRWLockForReading(SDL_rwlock * rwlock) SDL_AC
/** /**
* Lock the read/write lock for _write_ operations. * Lock the read/write lock for _write_ operations.
* *
* This will block until the rwlock is available, which is to say it is * This will block until the rwlock is available, which is to say it is not
* not locked for reading or writing by any other thread. Only one thread * locked for reading or writing by any other thread. Only one thread may hold
* may hold the lock when it requests write access; all other threads, * the lock when it requests write access; all other threads, whether they
* whether they also want to write or only want read-only access, must wait * also want to write or only want read-only access, must wait until the
* until the writer thread has released the lock. * writer thread has released the lock.
* *
* It is illegal for the owning thread to lock an already-locked rwlock * It is illegal for the owning thread to lock an already-locked rwlock for
* for writing (read-only may be locked recursively, writing can not). Doing * writing (read-only may be locked recursively, writing can not). Doing so
* so results in undefined behavior. * results in undefined behavior.
* *
* It is illegal to request a write lock from a thread that already holds * It is illegal to request a write lock from a thread that already holds a
* a read-only lock. Doing so results in undefined behavior. Unlock the * read-only lock. Doing so results in undefined behavior. Unlock the
* read-only lock before requesting a write lock. * read-only lock before requesting a write lock.
* *
* \param rwlock the read/write lock to lock * \param rwlock the read/write lock to lock
@ -364,8 +362,8 @@ extern DECLSPEC int SDLCALL SDL_LockRWLockForWriting(SDL_rwlock * rwlock) SDL_AC
* This works just like SDL_LockRWLockForReading(), but if the rwlock is not * This works just like SDL_LockRWLockForReading(), but if the rwlock is not
* available, then this function returns `SDL_RWLOCK_TIMEDOUT` immediately. * available, then this function returns `SDL_RWLOCK_TIMEDOUT` immediately.
* *
* This technique is useful if you need access to a resource but * This technique is useful if you need access to a resource but don't want to
* don't want to wait for it, and will return to it to try again later. * wait for it, and will return to it to try again later.
* *
* Trying to lock for read-only access can succeed if other threads are * Trying to lock for read-only access can succeed if other threads are
* holding read-only locks, as this won't prevent access. * holding read-only locks, as this won't prevent access.
@ -386,18 +384,18 @@ extern DECLSPEC int SDLCALL SDL_TryLockRWLockForReading(SDL_rwlock * rwlock) SDL
/** /**
* Try to lock a read/write lock _for writing_ without blocking. * Try to lock a read/write lock _for writing_ without blocking.
* *
* This works just like SDL_LockRWLockForWriting(), but if the rwlock is not available, * This works just like SDL_LockRWLockForWriting(), but if the rwlock is not
* this function returns `SDL_RWLOCK_TIMEDOUT` immediately. * available, this function returns `SDL_RWLOCK_TIMEDOUT` immediately.
* *
* This technique is useful if you need exclusive access to a resource but * This technique is useful if you need exclusive access to a resource but
* don't want to wait for it, and will return to it to try again later. * don't want to wait for it, and will return to it to try again later.
* *
* It is illegal for the owning thread to lock an already-locked rwlock * It is illegal for the owning thread to lock an already-locked rwlock for
* for writing (read-only may be locked recursively, writing can not). Doing * writing (read-only may be locked recursively, writing can not). Doing so
* so results in undefined behavior. * results in undefined behavior.
* *
* It is illegal to request a write lock from a thread that already holds * It is illegal to request a write lock from a thread that already holds a
* a read-only lock. Doing so results in undefined behavior. Unlock the * read-only lock. Doing so results in undefined behavior. Unlock the
* read-only lock before requesting a write lock. * read-only lock before requesting a write lock.
* *
* \param rwlock the rwlock to try to lock * \param rwlock the rwlock to try to lock
@ -438,11 +436,11 @@ extern DECLSPEC int SDLCALL SDL_UnlockRWLock(SDL_rwlock * rwlock) SDL_RELEASE_SH
/** /**
* Destroy a read/write lock created with SDL_CreateRWLock(). * Destroy a read/write lock created with SDL_CreateRWLock().
* *
* This function must be called on any read/write lock that is no longer needed. * This function must be called on any read/write lock that is no longer
* Failure to destroy a rwlock will result in a system memory or resource leak. While * needed. Failure to destroy a rwlock will result in a system memory or
* it is safe to destroy a rwlock that is _unlocked_, it is not safe to attempt * resource leak. While it is safe to destroy a rwlock that is _unlocked_, it
* to destroy a locked rwlock, and may result in undefined behavior depending * is not safe to attempt to destroy a locked rwlock, and may result in
* on the platform. * undefined behavior depending on the platform.
* *
* \param rwlock the rwlock to destroy * \param rwlock the rwlock to destroy
* *