recursive_lock.h File Reference

Definitions for a recursive mutex. More...

#include <sys/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 () __attribute__((deprecated))
	Allocate a new recursive lock.
void	rlock_destroy (recursive_lock_t *l) __attribute__((deprecated))
	Destroy a recursive lock.
int	rlock_lock (recursive_lock_t *l) __attribute__((deprecated))
	Lock a recursive lock.
int	rlock_lock_timed (recursive_lock_t *l, int timeout) __attribute__((deprecated))
	Lock a recursive lock (with a timeout).
int	rlock_unlock (recursive_lock_t *l) __attribute__((deprecated))
	Unlock a recursive lock.
int	rlock_trylock (recursive_lock_t *l) __attribute__((deprecated))
	Attempt to lock a recursive lock without blocking.
int	rlock_is_locked (recursive_lock_t *l) __attribute__((deprecated))
	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).

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

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

recursive_lock_t* rlock_create

(

)

Allocate a new recursive lock.

This function allocates a new recurisve 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).

void rlock_destroy

(

recursive_lock_t *

l

)

Destroy a recursive lock.

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.

int rlock_is_locked

(

recursive_lock_t *

l

)

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

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.

int rlock_lock

(

recursive_lock_t *

l

)

Lock a recursive lock.

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

int rlock_lock_timed	(	recursive_lock_t *	l,
		int	timeout
	)

Lock a recursive lock (with a timeout).

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

int rlock_trylock

(

recursive_lock_t *

l

)

Attempt to lock a recursive lock without blocking.

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

int rlock_unlock

(

recursive_lock_t *

l

)

Unlock a recursive lock.

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.