1/* worker_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 worker_mutex.h
41 *
42 * @brief Support for Cilk runtime mutexes.
43 *
44 * Cilk runtime mutexes are implemented as simple spin loops.
45 */
46
47#ifndef INCLUDED_WORKER_MUTEX_DOT_H
48#define INCLUDED_WORKER_MUTEX_DOT_H
49
50#include <cilk/common.h>
51#include "rts-common.h"
52
53__CILKRTS_BEGIN_EXTERN_C
54
55/**
56 * Mutexes are treated as an abstract data type within the Cilk
57 * runtime system.  They are implemented as simple spin loops and
58 * owned by a __cilkrts_worker.
59 */
60typedef struct mutex {
61    /** Mutex spin loop variable. 0 if unowned, 1 if owned. */
62    volatile int lock;
63
64    /** Worker that owns the mutex.  Must be 0 if mutex is unowned. */
65    __cilkrts_worker *owner;
66} mutex;
67
68/**
69 * @brief Initialize a Cilk mutex.
70 *
71 * @param m Mutex to be initialized.
72 */
73COMMON_PORTABLE
74void __cilkrts_mutex_init(struct mutex *m);
75
76/**
77 * @brief Acquire a Cilk mutex.
78 *
79 * If statistics are being gathered, the time spent
80 * acquiring the mutex will be attributed to the specified worker.
81 *
82 * @param w Worker that will become the owner of this mutex.
83 * @param m Mutex to be initialized.
84 */
85COMMON_PORTABLE
86void __cilkrts_mutex_lock(__cilkrts_worker *w,
87                          struct mutex *m);
88/**
89 * @brief Attempt to lock a Cilk mutex and fail if it isn't available.
90 *
91 * If statistics are being gathered, the time spent acquiring the
92 * mutex will be attributed to the specified worker.
93 *
94 * @param w Worker that will become the owner of this mutex.
95 * @param m Mutex to be acquired.
96 *
97 * @return 1 if the mutex was acquired.
98 * @return 0 if the mutex was not acquired.
99 */
100COMMON_PORTABLE
101int __cilkrts_mutex_trylock(__cilkrts_worker *w,
102                            struct mutex *m);
103
104/**
105 * @brief Release a Cilk mutex.
106 *
107 * If statistics are being gathered, the time spent
108 * acquiring the mutex will be attributed to the specified worker.
109 *
110 * @pre The mutex must be owned by the worker.
111 *
112 * @param w Worker that owns this mutex.
113 * @param m Mutex to be released.
114 */
115COMMON_PORTABLE
116void __cilkrts_mutex_unlock(__cilkrts_worker *w,
117                            struct mutex *m);
118
119/**
120 * @brief Deallocate a Cilk mutex.  Currently does nothing.
121 *
122 * @param w Unused.
123 * @param m Mutex to be deallocated.
124 */
125COMMON_PORTABLE
126void __cilkrts_mutex_destroy(__cilkrts_worker *w,
127                             struct mutex *m);
128
129__CILKRTS_END_EXTERN_C
130
131#endif // ! defined(INCLUDED_WORKER_MUTEX_DOT_H)
132