libcilkrts/runtime/worker_mutex.h

   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  */
  60 typedef 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  */
  73 COMMON_PORTABLE
  74 void __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  */
  85 COMMON_PORTABLE
  86 void __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  */
 100 COMMON_PORTABLE
 101 int __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  */
 115 COMMON_PORTABLE
 116 void __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  */
 125 COMMON_PORTABLE
 126 void __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)