1214152Sed/* spin_mutex.h                  -*-C++-*-
2214152Sed *
3214152Sed *************************************************************************
4214152Sed *
5222656Sed *  @copyright
6222656Sed *  Copyright (C) 2009-2013, Intel Corporation
7214152Sed *  All rights reserved.
8214152Sed *
9214152Sed *  @copyright
10214152Sed *  Redistribution and use in source and binary forms, with or without
11214152Sed *  modification, are permitted provided that the following conditions
12214152Sed *  are met:
13214152Sed *
14214152Sed *    * Redistributions of source code must retain the above copyright
15214152Sed *      notice, this list of conditions and the following disclaimer.
16214152Sed *    * Redistributions in binary form must reproduce the above copyright
17222656Sed *      notice, this list of conditions and the following disclaimer in
18214152Sed *      the documentation and/or other materials provided with the
19214152Sed *      distribution.
20214152Sed *    * Neither the name of Intel Corporation nor the names of its
21222656Sed *      contributors may be used to endorse or promote products derived
22214152Sed *      from this software without specific prior written permission.
23214152Sed *
24214152Sed *  @copyright
25214152Sed *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
26214152Sed *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
27214152Sed *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
28214152Sed *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
29214152Sed *  HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
30214152Sed *  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
31214152Sed *  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 */
65typedef 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 */
79COMMON_PORTABLE
80spin_mutex* spin_mutex_create();
81
82/**
83 * @brief Initialize a Cilk spin_mutex.
84 *
85 * @param m Spin_Mutex to be initialized.
86 */
87COMMON_PORTABLE
88void 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 */
98COMMON_PORTABLE
99void 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 */
108COMMON_PORTABLE
109int 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 */
116COMMON_PORTABLE
117void 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 */
124COMMON_PORTABLE
125void spin_mutex_destroy(struct spin_mutex *m);
126
127__CILKRTS_END_EXTERN_C
128
129#endif // ! defined(INCLUDED_SPIN_MUTEX_DOT_H)
130