recursive_lock.h File Reference

Definitions for a recursive mutex. More...

#include <kos/cdefs.h>
#include <kos/mutex.h>

Go to the source code of this file.

Typedefs
typedef mutex_t	recursive_lock_t
	Recursive lock structure.

Functions
recursive_lock_t *	rlock_create (void) __depr("Use mutexes instead.")
	Allocate a new recursive lock.
void	rlock_destroy (recursive_lock_t *l) __depr("Use mutexes instead.")
	Destroy a recursive lock.
int	rlock_lock (recursive_lock_t *l) __depr("Use mutexes instead.")
	Lock a recursive lock.
int	rlock_lock_timed (recursive_lock_t *l, int timeout) __depr("Use mutexes instead.")
	Lock a recursive lock (with a timeout).
int	rlock_unlock (recursive_lock_t *l) __depr("Use mutexes instead.")
	Unlock a recursive lock.
int	rlock_trylock (recursive_lock_t *l) __depr("Use mutexes instead.")
	Attempt to lock a recursive lock without blocking.
int	rlock_is_locked (recursive_lock_t *l) __depr("Use mutexes instead.")
	Check if a recursive lock is currently held by any thread.

Detailed Description

Definitions for a recursive mutex.

This file defines a recursive lock mechanism, similar to a mutex, but that a single thread can obtain as many times as it wants. A single thread is still limited to holding the lock at a time, but it can hold it an "unlimited" number of times (actually limited to INT_MAX, but who's counting).

Deprecated

These are now just wrappers around the MUTEX_TYPE_RECURSIVE that is now provided and will be removed at some point in the future. Please update your code to use that type instead.

Author

Lawrence Sebald

Typedef Documentation

recursive_lock_t

typedef mutex_t recursive_lock_t

Recursive lock structure.

Recursive locks are just a simple wrapper around mutexes at this point. You should not use this type in any new code.

Function Documentation

rlock_create()

recursive_lock_t * rlock_create

(

void

)

Allocate a new recursive lock.

Deprecated

This function allocates a new recursive lock that is initially not locked.

Returns

The created lock, or NULL on failure (errno will be set to ENOMEM to indicate that the system appears to be out of memory).

rlock_destroy()

void rlock_destroy

(

recursive_lock_t *

l

)

Destroy a recursive lock.

Deprecated

This function cleans up a recursive lock. It is an error to attempt to destroy a locked recursive lock.

Parameters

l	The recursive lock to destroy. It must be unlocked.

rlock_is_locked()

int rlock_is_locked

(

recursive_lock_t *

l

)

Check if a recursive lock is currently held by any thread.

Deprecated

This function checks whether or not a lock is currently held by any thread, including the calling thread. Note that this is NOT a safe way to check if a lock will be held by the time you get around to locking it.

Return values

TRUE	If the lock is held by any thread.
FALSE	If the lock is not currently held by any thread.

rlock_lock()

int rlock_lock

(

recursive_lock_t *

l

)

Lock a recursive lock.

Deprecated

This function attempts to lock the requested lock, and if it cannot it will block until that is possible.

Parameters

l	The recursive lock to lock.

Return values

-1	On error, errno will be set to EPERM if this function is called inside an interrupt, or EINTR if it is interrupted.
0	On success.

See also

rlock_trylock

rlock_lock_timed

rlock_lock_timed()

int rlock_lock_timed	(	recursive_lock_t *	l,
		int	timeout )

Lock a recursive lock (with a timeout).

Deprecated

This function attempts to lock the requested lock, and if it cannot it will block until either it is possible to acquire the lock or timeout milliseconds have elapsed.

Parameters

l	The recursive lock to lock.
timeout	The maximum number of milliseconds to wait. 0 is an unlimited timeout (equivalent to rlock_lock).

Return values

-1	On error, errno will be set to EPERM if this function is called inside an interrupt, EINTR if the function is interrupted, or EAGAIN if the timeout expires.
0	On success.

See also

rlock_trylock

rlock_lock_timed

rlock_trylock()

int rlock_trylock

(

recursive_lock_t *

l

)

Attempt to lock a recursive lock without blocking.

Deprecated

This function attempts to lock a recursive lock without blocking. This function, unlike rlock_lock and rlock_lock_timed is safe to call inside an interrupt.

Parameters

l	The recursive lock to lock.

Return values

-1	On error, errno will be set to EWOULDBLOCK if the lock is currently held by another thread.
0	On success.

See also

rlock_lock

rlock_lock_timed

rlock_unlock()

int rlock_unlock

(

recursive_lock_t *

l

)

Unlock a recursive lock.

Deprecated

This function releases the lock one time from the current thread.

Parameters

l	The recursive lock to unlock.

Return values

-1	On error, errno will be set to EPERM if the lock is not held by the calling thread.
0	On success.