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