KallistiOS  ##version##
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups
Typedefs | Functions
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_trlock_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

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
lThe 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
TRUEIf the lock is held by any thread.
FALSEIf 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
lThe recursive lock to lock.
Return values
-1On error, errno will be set to EPERM if this function is called inside an interrupt, or EINTR if it is interrupted.
0On 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
lThe recursive lock to lock.
timeoutThe maximum number of milliseconds to wait. 0 is an unlimited timeout (equivalent to rlock_lock).
Return values
-1On 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.
0On 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
lThe recursive lock to lock.
Return values
-1On error, errno will be set to EWOULDBLOCK if the lock is currently held by another thread.
0On 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
lThe recursive lock to unlock.
Return values
-1On error, errno will be set to EPERM if the lock is not held by the calling thread.
0On success.