1 /* spin_mutex.h                  -*-C++-*-
2  *
3  *************************************************************************
4  *
5  *  @copyright
6  *  Copyright (C) 2009-2013, Intel Corporation
7  *  All rights reserved.
8  *
9  *  @copyright
10  *  Redistribution and use in source and binary forms, with or without
11  *  modification, are permitted provided that the following conditions
12  *  are met:
13  *
14  *    * Redistributions of source code must retain the above copyright
15  *      notice, this list of conditions and the following disclaimer.
16  *    * Redistributions in binary form must reproduce the above copyright
17  *      notice, this list of conditions and the following disclaimer in
18  *      the documentation and/or other materials provided with the
19  *      distribution.
20  *    * Neither the name of Intel Corporation nor the names of its
21  *      contributors may be used to endorse or promote products derived
22  *      from this software without specific prior written permission.
23  *
24  *  @copyright
25  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
26  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
27  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
28  *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
29  *  HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
30  *  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
31  *  BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
32  *  OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
33  *  AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
34  *  LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY
35  *  WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
36  *  POSSIBILITY OF SUCH DAMAGE.
37  **************************************************************************/
38 
39 /**
40  * @file spin_mutex.h
41  *
42  * @brief Support for Cilk runtime mutexes.
43  *
44  * Cilk runtime mutexes are implemented as simple spin loops.
45  *
46  * This file is similar to a worker_mutex, except it does not have an
47  * owner field.
48  *
49  * TBD: This class, worker_mutex, and os_mutex overlap quite a bit in
50  * functionality.  Can we unify these mutexes somehow?
51  */
52 #ifndef INCLUDED_SPIN_MUTEX_DOT_H
53 #define INCLUDED_SPIN_MUTEX_DOT_H
54 
55 #include <cilk/common.h>
56 #include "rts-common.h"
57 #include "cilk_malloc.h"
58 
59 __CILKRTS_BEGIN_EXTERN_C
60 
61 /**
62  * Mutexes are treated as an abstract data type within the Cilk
63  * runtime system.  They are implemented as simple spin loops.
64  */
65 typedef struct spin_mutex {
66     /** Mutex spin loop variable. 0 if unowned, 1 if owned. */
67     volatile int lock;
68 
69     /** Padding so the mutex takes up a cache line. */
70     char pad[64/sizeof(int) - 1];
71 } spin_mutex;
72 
73 
74 /**
75  * @brief Create a new Cilk spin_mutex.
76  *
77  * @return Returns an initialized spin mutex.
78  */
79 COMMON_PORTABLE
80 spin_mutex* spin_mutex_create();
81 
82 /**
83  * @brief Initialize a Cilk spin_mutex.
84  *
85  * @param m Spin_Mutex to be initialized.
86  */
87 COMMON_PORTABLE
88 void spin_mutex_init(spin_mutex *m);
89 
90 /**
91  * @brief Acquire a Cilk spin_mutex.
92  *
93  * If statistics are being gathered, the time spent
94  * acquiring the spin_mutex will be attributed to the specified worker.
95  *
96  * @param m Spin_Mutex to be initialized.
97  */
98 COMMON_PORTABLE
99 void spin_mutex_lock(struct spin_mutex *m);
100 /**
101  * @brief Attempt to lock a Cilk spin_mutex and fail if it isn't available.
102  *
103  * @param m Spin_Mutex to be acquired.
104  *
105  * @return 1 if the spin_mutex was acquired.
106  * @return 0 if the spin_mutex was not acquired.
107  */
108 COMMON_PORTABLE
109 int spin_mutex_trylock(struct spin_mutex *m);
110 
111 /**
112  * @brief Release a Cilk spin_mutex.
113  *
114  * @param m Spin_Mutex to be released.
115  */
116 COMMON_PORTABLE
117 void spin_mutex_unlock(struct spin_mutex *m);
118 
119 /**
120  * @brief Deallocate a Cilk spin_mutex.  Currently does nothing.
121  *
122  * @param m Spin_Mutex to be deallocated.
123  */
124 COMMON_PORTABLE
125 void spin_mutex_destroy(struct spin_mutex *m);
126 
127 __CILKRTS_END_EXTERN_C
128 
129 #endif // ! defined(INCLUDED_SPIN_MUTEX_DOT_H)
130