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. More...

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

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.