1 /* -*- Mode: C; c-basic-offset:4 ; indent-tabs-mode:nil -*- */
2 /*
3 * Copyright (c) 2004-2005 The Trustees of Indiana University and Indiana
4 * University Research and Technology
5 * Corporation. All rights reserved.
6 * Copyright (c) 2004-2016 The University of Tennessee and The University
7 * of Tennessee Research Foundation. All rights
8 * reserved.
9 * Copyright (c) 2004-2005 High Performance Computing Center Stuttgart,
10 * University of Stuttgart. All rights reserved.
11 * Copyright (c) 2004-2005 The Regents of the University of California.
12 * All rights reserved.
13 * Copyright (c) 2007 Cisco Systems, Inc. All rights reserved.
14 * Copyright (c) 2007-2016 Los Alamos National Security, LLC. All rights
15 * reserved.
16 * Copyright (c) 2007 Voltaire. All rights reserved.
17 * Copyright (c) 2010 Oracle and/or its affiliates. All rights reserved.
18 *
19 * $COPYRIGHT$
20 *
21 * Additional copyrights may follow
22 *
23 * $HEADER$
24 */
25
26 #ifndef OPAL_MUTEX_H
27 #define OPAL_MUTEX_H 1
28
29 #include "opal_config.h"
30
31 #include "opal/threads/thread_usage.h"
32
33 BEGIN_C_DECLS
34
35 /**
36 * @file:
37 *
38 * Mutual exclusion functions.
39 *
40 * Functions for locking of critical sections.
41 */
42
43 /**
44 * Opaque mutex object
45 */
46 typedef struct opal_mutex_t opal_mutex_t;
47 typedef struct opal_mutex_t opal_recursive_mutex_t;
48
49 /**
50 * Try to acquire a mutex.
51 *
52 * @param mutex Address of the mutex.
53 * @return 0 if the mutex was acquired, 1 otherwise.
54 */
55 static inline int opal_mutex_trylock(opal_mutex_t *mutex);
56
57
58 /**
59 * Acquire a mutex.
60 *
61 * @param mutex Address of the mutex.
62 */
63 static inline void opal_mutex_lock(opal_mutex_t *mutex);
64
65
66 /**
67 * Release a mutex.
68 *
69 * @param mutex Address of the mutex.
70 */
71 static inline void opal_mutex_unlock(opal_mutex_t *mutex);
72
73
74 /**
75 * Try to acquire a mutex using atomic operations.
76 *
77 * @param mutex Address of the mutex.
78 * @return 0 if the mutex was acquired, 1 otherwise.
79 */
80 static inline int opal_mutex_atomic_trylock(opal_mutex_t *mutex);
81
82
83 /**
84 * Acquire a mutex using atomic operations.
85 *
86 * @param mutex Address of the mutex.
87 */
88 static inline void opal_mutex_atomic_lock(opal_mutex_t *mutex);
89
90
91 /**
92 * Release a mutex using atomic operations.
93 *
94 * @param mutex Address of the mutex.
95 */
96 static inline void opal_mutex_atomic_unlock(opal_mutex_t *mutex);
97
98 END_C_DECLS
99
100 #include "mutex_unix.h"
101
102 BEGIN_C_DECLS
103
104 /**
105 * Lock a mutex if opal_using_threads() says that multiple threads may
106 * be active in the process.
107 *
108 * @param mutex Pointer to a opal_mutex_t to lock.
109 *
110 * If there is a possibility that multiple threads are running in the
111 * process (as determined by opal_using_threads()), this function will
112 * block waiting to lock the mutex.
113 *
114 * If there is no possibility that multiple threads are running in the
115 * process, return immediately.
116 */
117 #define OPAL_THREAD_LOCK(mutex) \
118 do { \
119 if (OPAL_UNLIKELY(opal_using_threads())) { \
120 opal_mutex_lock(mutex); \
121 } \
122 } while (0)
123
124
125 /**
126 * Try to lock a mutex if opal_using_threads() says that multiple
127 * threads may be active in the process.
128 *
129 * @param mutex Pointer to a opal_mutex_t to trylock
130 *
131 * If there is a possibility that multiple threads are running in the
132 * process (as determined by opal_using_threads()), this function will
133 * trylock the mutex.
134 *
135 * If there is no possibility that multiple threads are running in the
136 * process, return immediately without modifying the mutex.
137 *
138 * Returns 0 if mutex was locked, non-zero otherwise.
139 */
140 #define OPAL_THREAD_TRYLOCK(mutex) \
141 (OPAL_UNLIKELY(opal_using_threads()) ? opal_mutex_trylock(mutex) : 0)
142
143 /**
144 * Unlock a mutex if opal_using_threads() says that multiple threads
145 * may be active in the process.
146 *
147 * @param mutex Pointer to a opal_mutex_t to unlock.
148 *
149 * If there is a possibility that multiple threads are running in the
150 * process (as determined by opal_using_threads()), this function will
151 * unlock the mutex.
152 *
153 * If there is no possibility that multiple threads are running in the
154 * process, return immediately without modifying the mutex.
155 */
156 #define OPAL_THREAD_UNLOCK(mutex) \
157 do { \
158 if (OPAL_UNLIKELY(opal_using_threads())) { \
159 opal_mutex_unlock(mutex); \
160 } \
161 } while (0)
162
163
164 /**
165 * Lock a mutex if opal_using_threads() says that multiple threads may
166 * be active in the process for the duration of the specified action.
167 *
168 * @param mutex Pointer to a opal_mutex_t to lock.
169 * @param action A scope over which the lock is held.
170 *
171 * If there is a possibility that multiple threads are running in the
172 * process (as determined by opal_using_threads()), this function will
173 * acquire the lock before invoking the specified action and release
174 * it on return.
175 *
176 * If there is no possibility that multiple threads are running in the
177 * process, invoke the action without acquiring the lock.
178 */
179 #define OPAL_THREAD_SCOPED_LOCK(mutex, action) \
180 do { \
181 if(OPAL_UNLIKELY(opal_using_threads())) { \
182 opal_mutex_lock(mutex); \
183 action; \
184 opal_mutex_unlock(mutex); \
185 } else { \
186 action; \
187 } \
188 } while (0)
189
190 END_C_DECLS
191
192 #endif /* OPAL_MUTEX_H */