Version:  2.0.40 2.2.26 2.4.37 3.13 3.14 3.15 3.16 3.17 3.18 3.19 4.0 4.1 4.2 4.3 4.4 4.5 4.6 4.7 4.8 4.9 4.10

Linux/include/linux/mutex.h

  1 /*
  2  * Mutexes: blocking mutual exclusion locks
  3  *
  4  * started by Ingo Molnar:
  5  *
  6  *  Copyright (C) 2004, 2005, 2006 Red Hat, Inc., Ingo Molnar <mingo@redhat.com>
  7  *
  8  * This file contains the main data structure and API definitions.
  9  */
 10 #ifndef __LINUX_MUTEX_H
 11 #define __LINUX_MUTEX_H
 12 
 13 #include <asm/current.h>
 14 #include <linux/list.h>
 15 #include <linux/spinlock_types.h>
 16 #include <linux/linkage.h>
 17 #include <linux/lockdep.h>
 18 #include <linux/atomic.h>
 19 #include <asm/processor.h>
 20 #include <linux/osq_lock.h>
 21 #include <linux/debug_locks.h>
 22 
 23 /*
 24  * Simple, straightforward mutexes with strict semantics:
 25  *
 26  * - only one task can hold the mutex at a time
 27  * - only the owner can unlock the mutex
 28  * - multiple unlocks are not permitted
 29  * - recursive locking is not permitted
 30  * - a mutex object must be initialized via the API
 31  * - a mutex object must not be initialized via memset or copying
 32  * - task may not exit with mutex held
 33  * - memory areas where held locks reside must not be freed
 34  * - held mutexes must not be reinitialized
 35  * - mutexes may not be used in hardware or software interrupt
 36  *   contexts such as tasklets and timers
 37  *
 38  * These semantics are fully enforced when DEBUG_MUTEXES is
 39  * enabled. Furthermore, besides enforcing the above rules, the mutex
 40  * debugging code also implements a number of additional features
 41  * that make lock debugging easier and faster:
 42  *
 43  * - uses symbolic names of mutexes, whenever they are printed in debug output
 44  * - point-of-acquire tracking, symbolic lookup of function names
 45  * - list of all locks held in the system, printout of them
 46  * - owner tracking
 47  * - detects self-recursing locks and prints out all relevant info
 48  * - detects multi-task circular deadlocks and prints out all affected
 49  *   locks and tasks (and only those tasks)
 50  */
 51 struct mutex {
 52         atomic_long_t           owner;
 53         spinlock_t              wait_lock;
 54 #ifdef CONFIG_MUTEX_SPIN_ON_OWNER
 55         struct optimistic_spin_queue osq; /* Spinner MCS lock */
 56 #endif
 57         struct list_head        wait_list;
 58 #ifdef CONFIG_DEBUG_MUTEXES
 59         void                    *magic;
 60 #endif
 61 #ifdef CONFIG_DEBUG_LOCK_ALLOC
 62         struct lockdep_map      dep_map;
 63 #endif
 64 };
 65 
 66 static inline struct task_struct *__mutex_owner(struct mutex *lock)
 67 {
 68         return (struct task_struct *)(atomic_long_read(&lock->owner) & ~0x03);
 69 }
 70 
 71 /*
 72  * This is the control structure for tasks blocked on mutex,
 73  * which resides on the blocked task's kernel stack:
 74  */
 75 struct mutex_waiter {
 76         struct list_head        list;
 77         struct task_struct      *task;
 78 #ifdef CONFIG_DEBUG_MUTEXES
 79         void                    *magic;
 80 #endif
 81 };
 82 
 83 #ifdef CONFIG_DEBUG_MUTEXES
 84 
 85 #define __DEBUG_MUTEX_INITIALIZER(lockname)                             \
 86         , .magic = &lockname
 87 
 88 extern void mutex_destroy(struct mutex *lock);
 89 
 90 #else
 91 
 92 # define __DEBUG_MUTEX_INITIALIZER(lockname)
 93 
 94 static inline void mutex_destroy(struct mutex *lock) {}
 95 
 96 #endif
 97 
 98 /**
 99  * mutex_init - initialize the mutex
100  * @mutex: the mutex to be initialized
101  *
102  * Initialize the mutex to unlocked state.
103  *
104  * It is not allowed to initialize an already locked mutex.
105  */
106 #define mutex_init(mutex)                                               \
107 do {                                                                    \
108         static struct lock_class_key __key;                             \
109                                                                         \
110         __mutex_init((mutex), #mutex, &__key);                          \
111 } while (0)
112 
113 #ifdef CONFIG_DEBUG_LOCK_ALLOC
114 # define __DEP_MAP_MUTEX_INITIALIZER(lockname) \
115                 , .dep_map = { .name = #lockname }
116 #else
117 # define __DEP_MAP_MUTEX_INITIALIZER(lockname)
118 #endif
119 
120 #define __MUTEX_INITIALIZER(lockname) \
121                 { .owner = ATOMIC_LONG_INIT(0) \
122                 , .wait_lock = __SPIN_LOCK_UNLOCKED(lockname.wait_lock) \
123                 , .wait_list = LIST_HEAD_INIT(lockname.wait_list) \
124                 __DEBUG_MUTEX_INITIALIZER(lockname) \
125                 __DEP_MAP_MUTEX_INITIALIZER(lockname) }
126 
127 #define DEFINE_MUTEX(mutexname) \
128         struct mutex mutexname = __MUTEX_INITIALIZER(mutexname)
129 
130 extern void __mutex_init(struct mutex *lock, const char *name,
131                          struct lock_class_key *key);
132 
133 /**
134  * mutex_is_locked - is the mutex locked
135  * @lock: the mutex to be queried
136  *
137  * Returns 1 if the mutex is locked, 0 if unlocked.
138  */
139 static inline int mutex_is_locked(struct mutex *lock)
140 {
141         /*
142          * XXX think about spin_is_locked
143          */
144         return __mutex_owner(lock) != NULL;
145 }
146 
147 /*
148  * See kernel/locking/mutex.c for detailed documentation of these APIs.
149  * Also see Documentation/locking/mutex-design.txt.
150  */
151 #ifdef CONFIG_DEBUG_LOCK_ALLOC
152 extern void mutex_lock_nested(struct mutex *lock, unsigned int subclass);
153 extern void _mutex_lock_nest_lock(struct mutex *lock, struct lockdep_map *nest_lock);
154 
155 extern int __must_check mutex_lock_interruptible_nested(struct mutex *lock,
156                                         unsigned int subclass);
157 extern int __must_check mutex_lock_killable_nested(struct mutex *lock,
158                                         unsigned int subclass);
159 
160 #define mutex_lock(lock) mutex_lock_nested(lock, 0)
161 #define mutex_lock_interruptible(lock) mutex_lock_interruptible_nested(lock, 0)
162 #define mutex_lock_killable(lock) mutex_lock_killable_nested(lock, 0)
163 
164 #define mutex_lock_nest_lock(lock, nest_lock)                           \
165 do {                                                                    \
166         typecheck(struct lockdep_map *, &(nest_lock)->dep_map); \
167         _mutex_lock_nest_lock(lock, &(nest_lock)->dep_map);             \
168 } while (0)
169 
170 #else
171 extern void mutex_lock(struct mutex *lock);
172 extern int __must_check mutex_lock_interruptible(struct mutex *lock);
173 extern int __must_check mutex_lock_killable(struct mutex *lock);
174 
175 # define mutex_lock_nested(lock, subclass) mutex_lock(lock)
176 # define mutex_lock_interruptible_nested(lock, subclass) mutex_lock_interruptible(lock)
177 # define mutex_lock_killable_nested(lock, subclass) mutex_lock_killable(lock)
178 # define mutex_lock_nest_lock(lock, nest_lock) mutex_lock(lock)
179 #endif
180 
181 /*
182  * NOTE: mutex_trylock() follows the spin_trylock() convention,
183  *       not the down_trylock() convention!
184  *
185  * Returns 1 if the mutex has been acquired successfully, and 0 on contention.
186  */
187 extern int mutex_trylock(struct mutex *lock);
188 extern void mutex_unlock(struct mutex *lock);
189 
190 extern int atomic_dec_and_mutex_lock(atomic_t *cnt, struct mutex *lock);
191 
192 /*
193  * These values are chosen such that FAIL and SUCCESS match the
194  * values of the regular mutex_trylock().
195  */
196 enum mutex_trylock_recursive_enum {
197         MUTEX_TRYLOCK_FAILED    = 0,
198         MUTEX_TRYLOCK_SUCCESS   = 1,
199         MUTEX_TRYLOCK_RECURSIVE,
200 };
201 
202 /**
203  * mutex_trylock_recursive - trylock variant that allows recursive locking
204  * @lock: mutex to be locked
205  *
206  * This function should not be used, _ever_. It is purely for hysterical GEM
207  * raisins, and once those are gone this will be removed.
208  *
209  * Returns:
210  *  MUTEX_TRYLOCK_FAILED    - trylock failed,
211  *  MUTEX_TRYLOCK_SUCCESS   - lock acquired,
212  *  MUTEX_TRYLOCK_RECURSIVE - we already owned the lock.
213  */
214 static inline /* __deprecated */ __must_check enum mutex_trylock_recursive_enum
215 mutex_trylock_recursive(struct mutex *lock)
216 {
217         if (unlikely(__mutex_owner(lock) == current))
218                 return MUTEX_TRYLOCK_RECURSIVE;
219 
220         return mutex_trylock(lock);
221 }
222 
223 #endif /* __LINUX_MUTEX_H */
224 

This page was automatically generated by LXR 0.3.1 (source).  •  Linux is a registered trademark of Linus Torvalds  •  Contact us