KallistiOS git master
Independent SDK for the Sega Dreamcast
Loading...
Searching...
No Matches
recursive_lock.h
Go to the documentation of this file.
1/* KallistiOS ##version##
2
3 include/kos/recursive_lock.h
4 Copyright (C) 2008, 2010, 2012 Lawrence Sebald
5
6*/
7
8/** \file kos/recursive_lock.h
9 \brief Definitions for a recursive mutex.
10 \ingroup kthreads
11
12 This file defines a recursive lock mechanism, similar to a mutex, but that a
13 single thread can obtain as many times as it wants. A single thread is still
14 limited to holding the lock at a time, but it can hold it an "unlimited"
15 number of times (actually limited to INT_MAX, but who's counting).
16
17 \deprecated
18 These are now just wrappers around the MUTEX_TYPE_RECURSIVE that is now
19 provided and will be removed at some point in the future. Please update your
20 code to use that type instead.
21
22 \author Lawrence Sebald
23*/
24
25#ifndef __KOS_RECURSIVE_LOCK_H
26#define __KOS_RECURSIVE_LOCK_H
27
28#include <kos/cdefs.h>
29
30__BEGIN_DECLS
31
32#include <kos/mutex.h>
33
34/** \brief Recursive lock structure.
35
36 Recursive locks are just a simple wrapper around mutexes at this point. You
37 should not use this type in any new code.
38
39 \headerfile kos/recursive_lock.h
40*/
41typedef mutex_t recursive_lock_t;
42
43/** \brief Allocate a new recursive lock.
44
45 \deprecated
46 This function allocates a new recursive lock that is initially not locked.
47
48 \return The created lock, or NULL on failure (errno will be set to ENOMEM to
49 indicate that the system appears to be out of memory).
50*/
51recursive_lock_t *rlock_create(void) __depr("Use mutexes instead.");
52
53/** \brief Destroy a recursive lock.
54
55 \deprecated
56 This function cleans up a recursive lock. It is an error to attempt to
57 destroy a locked recursive lock.
58
59 \param l The recursive lock to destroy. It must be unlocked.
60*/
61void rlock_destroy(recursive_lock_t *l) __depr("Use mutexes instead.");
62
63/** \brief Lock a recursive lock.
64
65 \deprecated
66 This function attempts to lock the requested lock, and if it cannot it will
67 block until that is possible.
68
69 \param l The recursive lock to lock.
70 \retval -1 On error, errno will be set to EPERM if this function is
71 called inside an interrupt, or EINTR if it is interrupted.
72 \retval 0 On success.
73 \sa rlock_trylock
74 \sa rlock_lock_timed
75*/
76int rlock_lock(recursive_lock_t *l) __depr("Use mutexes instead.");
77
78/** \brief Lock a recursive lock (with a timeout).
79
80 \deprecated
81 This function attempts to lock the requested lock, and if it cannot it will
82 block until either it is possible to acquire the lock or timeout
83 milliseconds have elapsed.
84
85 \param l The recursive lock to lock.
86 \param timeout The maximum number of milliseconds to wait. 0 is an
87 unlimited timeout (equivalent to rlock_lock).
88 \retval -1 On error, errno will be set to EPERM if this function is
89 called inside an interrupt, EINTR if the function is
90 interrupted, or EAGAIN if the timeout expires.
91 \retval 0 On success.
92 \sa rlock_trylock
93 \sa rlock_lock_timed
94*/
95int rlock_lock_timed(recursive_lock_t *l, int timeout)
96 __depr("Use mutexes instead.");
97
98/** \brief Unlock a recursive lock.
99
100 \deprecated
101 This function releases the lock one time from the current thread.
102
103 \param l The recursive lock to unlock.
104 \retval -1 On error, errno will be set to EPERM if the lock is not held
105 by the calling thread.
106 \retval 0 On success.
107*/
108int rlock_unlock(recursive_lock_t *l) __depr("Use mutexes instead.");
109
110/** \brief Attempt to lock a recursive lock without blocking.
111
112 \deprecated
113 This function attempts to lock a recursive lock without blocking. This
114 function, unlike rlock_lock and rlock_lock_timed is safe to call inside an
115 interrupt.
116
117 \param l The recursive lock to lock.
118 \retval -1 On error, errno will be set to EWOULDBLOCK if the lock is
119 currently held by another thread.
120 \retval 0 On success.
121 \sa rlock_lock
122 \sa rlock_lock_timed
123*/
124int rlock_trylock(recursive_lock_t *l) __depr("Use mutexes instead.");
125
126/** \brief Check if a recursive lock is currently held by any thread.
127
128 \deprecated
129 This function checks whether or not a lock is currently held by any thread,
130 including the calling thread. Note that this is <b>NOT</b> a safe way to
131 check if a lock <em>will</em> be held by the time you get around to locking
132 it.
133
134 \retval TRUE If the lock is held by any thread.
135 \retval FALSE If the lock is not currently held by any thread.
136*/
137int rlock_is_locked(recursive_lock_t *l) __depr("Use mutexes instead.");
138
139__END_DECLS
140
141#endif /* !__KOS_RECURSIVE_LOCK_H */
cdefs.h
Definitions for builtin attributes and compiler directives.
__depr
#define __depr(m)
Mark something as deprecated, with an informative message.
Definition cdefs.h:119
mutex.h
Mutual exclusion locks.
rlock_lock
int rlock_lock(recursive_lock_t *l) __depr("Use mutexes instead.")
Lock a recursive lock.
rlock_unlock
int rlock_unlock(recursive_lock_t *l) __depr("Use mutexes instead.")
Unlock a recursive lock.
rlock_destroy
void rlock_destroy(recursive_lock_t *l) __depr("Use mutexes instead.")
Destroy a recursive lock.
rlock_lock_timed
int rlock_lock_timed(recursive_lock_t *l, int timeout) __depr("Use mutexes instead.")
Lock a recursive lock (with a timeout).
rlock_create
recursive_lock_t * rlock_create(void) __depr("Use mutexes instead.")
Allocate a new recursive lock.
rlock_trylock
int rlock_trylock(recursive_lock_t *l) __depr("Use mutexes instead.")
Attempt to lock a recursive lock without blocking.
recursive_lock_t
mutex_t recursive_lock_t
Recursive lock structure.
Definition recursive_lock.h:41
rlock_is_locked
int rlock_is_locked(recursive_lock_t *l) __depr("Use mutexes instead.")
Check if a recursive lock is currently held by any thread.
mutex_t
Mutual exclusion lock type.
Definition mutex.h:68