2 * Copyright (c) 2004, 2005 Voltaire, Inc. All rights reserved.
3 * Copyright (c) 2002-2010 Mellanox Technologies LTD. All rights reserved.
4 * Copyright (c) 1996-2003 Intel Corporation. All rights reserved.
6 * This software is available to you under a choice of one of two
7 * licenses. You may choose to be licensed under the terms of the GNU
8 * General Public License (GPL) Version 2, available from the file
9 * COPYING in the main directory of this source tree, or the
10 * OpenIB.org BSD license below:
12 * Redistribution and use in source and binary forms, with or
13 * without modification, are permitted provided that the following
16 * - Redistributions of source code must retain the above
17 * copyright notice, this list of conditions and the following
20 * - Redistributions in binary form must reproduce the above
21 * copyright notice, this list of conditions and the following
22 * disclaimer in the documentation and/or other materials
23 * provided with the distribution.
25 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
26 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
27 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
28 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
29 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
30 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
31 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
38 * This file contains the passive lock, which synchronizes passive threads.
39 * The passive lock allows multiple readers to access a resource
40 * simultaneously, exclusive from a single thread allowed writing.
41 * Several writer threads are allowed - but only one can write at a given time
44 #ifndef _CL_PASSIVE_LOCK_H_
45 #define _CL_PASSIVE_LOCK_H_
46 #include <complib/cl_types.h>
50 # define BEGIN_C_DECLS extern "C" {
51 # define END_C_DECLS }
52 #else /* !__cplusplus */
53 # define BEGIN_C_DECLS
55 #endif /* __cplusplus */
58 /****h* Component Library/Passive Lock
63 * The Passive Lock provides synchronization between multiple threads that
64 * are sharing the lock with a single thread holding the lock exclusively.
66 * Passive lock works exclusively between threads and cannot be used in
67 * situations where the caller cannot be put into a waiting state.
69 * The passive lock functions operate a cl_plock_t structure which should
70 * be treated as opaque and should be manipulated only through the provided
78 * cl_plock_construct, cl_plock_init, cl_plock_destroy
81 * cl_plock_acquire, cl_plock_excl_acquire, cl_plock_release
83 /****s* Component Library: Passive Lock/cl_plock_t
88 * Passive Lock structure.
90 * The cl_plock_t structure should be treated as opaque and should
91 * be manipulated only through the provided functions.
95 typedef struct _cl_plock {
96 pthread_rwlock_t lock;
102 * Pthread RWLOCK object
105 * Records the current state of the lock, such as initialized,
112 /****f* Component Library: Passive Lock/cl_plock_construct
117 * The cl_plock_construct function initializes the state of a
122 static inline void cl_plock_construct(IN cl_plock_t * const p_lock)
126 p_lock->state = CL_UNINITIALIZED;
132 * [in] Pointer to a cl_plock_t structure whose state to initialize.
135 * This function does not return a value.
138 * Allows calling cl_plock_destroy without first calling cl_plock_init.
140 * Calling cl_plock_construct is a prerequisite to calling any other
141 * passive lock function except cl_plock_init.
144 * Passive Lock, cl_plock_init, cl_plock_destroy
147 /****f* Component Library: Passive Lock/cl_plock_destroy
152 * The cl_plock_destroy function performs any necessary cleanup
157 static inline void cl_plock_destroy(IN cl_plock_t * const p_lock)
160 p_lock->state = CL_DESTROYING;
161 pthread_rwlock_destroy(&p_lock->lock);
162 p_lock->state = CL_DESTROYED;
168 * [in] Pointer to a cl_plock_t structure whose state to initialize.
171 * This function does not return a value.
174 * cl_plock_destroy performs any necessary cleanup of the specified
177 * This function must only be called if cl_plock_construct or
178 * cl_plock_init has been called. The passive lock must not be held
179 * when calling this function.
182 * Passive Lock, cl_plock_construct, cl_plock_init
185 /****f* Component Library: Passive Lock/cl_plock_init
190 * The cl_plock_init function initializes a passive lock.
194 static inline cl_status_t cl_plock_init(IN cl_plock_t * const p_lock)
199 status = pthread_rwlock_init(&p_lock->lock, NULL);
202 p_lock->state = CL_INITIALIZED;
209 * [in] Pointer to a cl_plock_t structure to initialize.
212 * CL_SUCCESS if the passive lock was initialized successfully.
214 * CL_ERROR otherwise.
217 * Allows calling cl_plock_acquire, cl_plock_release,
218 * cl_plock_excl_acquire
221 * Passive Lock, cl_plock_construct, cl_plock_destroy,
222 * cl_plock_excl_acquire, cl_plock_acquire, cl_plock_release
225 /****f* Component Library: Passive Lock/cl_plock_acquire
230 * The cl_plock_acquire function acquires a passive lock for
235 static inline void cl_plock_acquire(IN cl_plock_t * const p_lock)
237 cl_status_t __attribute__((unused)) status;
239 CL_ASSERT(p_lock->state == CL_INITIALIZED);
241 status = pthread_rwlock_rdlock(&p_lock->lock);
242 CL_ASSERT(status == 0);
248 * [in] Pointer to a cl_plock_t structure to acquire.
251 * This function does not return a value.
254 * Passive Lock, cl_plock_release, cl_plock_excl_acquire
257 /****f* Component Library: Passive Lock/cl_plock_excl_acquire
259 * cl_plock_excl_acquire
262 * The cl_plock_excl_acquire function acquires exclusive access
267 static inline void cl_plock_excl_acquire(IN cl_plock_t * const p_lock)
269 cl_status_t __attribute__((unused)) status;
272 CL_ASSERT(p_lock->state == CL_INITIALIZED);
274 status = pthread_rwlock_wrlock(&p_lock->lock);
275 CL_ASSERT(status == 0);
281 * [in] Pointer to a cl_plock_t structure to acquire exclusively.
284 * This function does not return a value.
287 * Passive Lock, cl_plock_release, cl_plock_acquire
290 /****f* Component Library: Passive Lock/cl_plock_release
295 * The cl_plock_release function releases a passive lock from
296 * shared or exclusive access.
300 static inline void cl_plock_release(IN cl_plock_t * const p_lock)
302 cl_status_t __attribute__((unused)) status;
304 CL_ASSERT(p_lock->state == CL_INITIALIZED);
306 status = pthread_rwlock_unlock(&p_lock->lock);
307 CL_ASSERT(status == 0);
313 * [in] Pointer to a cl_plock_t structure to release.
316 * This function does not return a value.
319 * Passive Lock, cl_plock_acquire, cl_plock_excl_acquire
323 #endif /* _CL_PASSIVE_LOCK_H_ */