libcilkrts/runtime/cilk-tbb-interop.h

   1 /* cilk-tbb-interop.h                  -*-C++-*-
   2  *
   3  *************************************************************************
   4  *
   5  *  Copyright (C) 2009-2016, Intel Corporation
   6  *  All rights reserved.
   7  *
   8  *  Redistribution and use in source and binary forms, with or without
   9  *  modification, are permitted provided that the following conditions
  10  *  are met:
  11  *
  12  *    * Redistributions of source code must retain the above copyright
  13  *      notice, this list of conditions and the following disclaimer.
  14  *    * Redistributions in binary form must reproduce the above copyright
  15  *      notice, this list of conditions and the following disclaimer in
  16  *      the documentation and/or other materials provided with the
  17  *      distribution.
  18  *    * Neither the name of Intel Corporation nor the names of its
  19  *      contributors may be used to endorse or promote products derived
  20  *      from this software without specific prior written permission.
  21  *
  22  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  23  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  24  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  25  *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  26  *  HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  27  *  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
  28  *  BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
  29  *  OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
  30  *  AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  31  *  LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY
  32  *  WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  33  *  POSSIBILITY OF SUCH DAMAGE.
  34  *
  35  *  *********************************************************************
  36  *
  37  *  PLEASE NOTE: This file is a downstream copy of a file mainitained in
  38  *  a repository at cilkplus.org. Changes made to this file that are not
  39  *  submitted through the contribution process detailed at
  40  *  http://www.cilkplus.org/submit-cilk-contribution will be lost the next
  41  *  time that a new version is released. Changes only submitted to the
  42  *  GNU compiler collection or posted to the git repository at
  43  *  https://bitbucket.org/intelcilkruntime/intel-cilk-runtime.git are
  44  *  not tracked.
  45  *
  46  *  We welcome your contributions to this open source project. Thank you
  47  *  for your assistance in helping us improve Cilk Plus.
  48  **************************************************************************/
  49
  50 /**
  51  * @file cilk-tbb-interop.h
  52  *
  53  * @brief Interface between TBB and Cilk to allow TBB to associate it's
  54  * per-thread data with Cilk workers, and maintain the association as work
  55  * moves between worker threads.  This handles the case where TBB calls
  56  * into a Cilk function which may later call back to a function making
  57  * TBB calls.
  58  *
  59  * Each thunk structure has two pointers: \"routine\" and \"data\".
  60  * The caller of the thunk invokes *routine, passing \"data\" as the void*
  61  * parameter.
  62  */
  63
  64 #ifndef INCLUDED_CILK_TBB_INTEROP_DOT_H
  65 #define INCLUDED_CILK_TBB_INTEROP_DOT_H
  66
  67 #include <cilk/common.h>  // for CILK_EXPORT
  68
  69 __CILKRTS_BEGIN_EXTERN_C
  70
  71 /** A return code.  0 indicates success. */
  72 typedef int __cilk_tbb_retcode;
  73
  74 /**
  75  * Enumeration of reasons that Cilk will call the TBB stack operation
  76  * function.
  77  *
  78  * When a non-empty stack is transfered between threads, the first thread must
  79  * orphan it and the second thread must adopt it.
  80  *
  81  * An empty stack can be transfered similarly, or simply released by the first
  82  * thread.
  83  *
  84  * Here is a summary of the actions as transitions on a state machine.
  85 @verbatim
  86                        watch                                    ORPHAN
  87                        -->-->                                   -->--
  88                       /      \                                 /     \
  89    (freed empty stack)       (TBB sees stack running on thread)      (stack in limbo)
  90                       \     /                                  \     /
  91                        --<--                                    --<--
  92                        RELEASE or                               ADOPT
  93                        unwatch
  94 @endverbatim
  95  */
  96 typedef enum __cilk_tbb_stack_op {
  97    /**
  98     * Disconnecting stack from a thread.
  99     *
 100     * The thunk must be invoked on the thread disconnecting itself from the
 101     * stack.  Must \"happen before\" the stack is adopted elsewhere.
 102     */
 103     CILK_TBB_STACK_ORPHAN,
 104
 105     /**
 106      * Reconnecting orphaned stack to a thread.
 107      *
 108      * The thunk must be invoked on the thread adopting the stack.
 109      */
 110     CILK_TBB_STACK_ADOPT,
 111
 112    /**
 113     * Releasing stack.
 114     *
 115     * The thunk must be invoked on the thread doing the releasing, Must
 116     * \"happen before\" the stack is used elsewhere.
 117     */
 118     CILK_TBB_STACK_RELEASE
 119 } __cilk_tbb_stack_op;
 120
 121 /**
 122  * Function that will be called by the Cilk runtime to inform TBB of a change
 123  * in the stack associated with the current thread.
 124  *
 125  * It does not matter what stack the thunk runs on.
 126  * The thread (not fiber) on which the thunk runs is important.
 127  *
 128  * @param op Enumerated value indicating what type of change is ocurring.
 129  * @param data Context value provided by TBB in the __cilkrts_watch_stack
 130  * call.  This data is opaque to Cilk.
 131  *
 132  * @return 0 indicates success.
 133  */
 134 typedef __cilk_tbb_retcode (*__cilk_tbb_pfn_stack_op)(enum __cilk_tbb_stack_op op,
 135                                                       void* data);
 136
 137 /**
 138  * Function that will be called by TBB to inform the Cilk runtime that TBB
 139  * is no longer interested in watching the stack bound to the current thread.
 140  *
 141  * @param data Context value provided to TBB by the __cilkrts_watch_stack
 142  * call.  This data is opaque to TBB.
 143  *
 144  * @return 0 indicates success.
 145  */
 146 typedef __cilk_tbb_retcode (*__cilk_tbb_pfn_unwatch_stacks)(void *data);
 147
 148 /**
 149  * Thunk invoked by Cilk to call back to TBB to tell it about a change in
 150  * the stack bound to the current thread.
 151  */
 152 typedef struct __cilk_tbb_stack_op_thunk {
 153     /// Function in TBB the Cilk runtime should call when something
 154     // "interesting" happens involving a stack
 155     __cilk_tbb_pfn_stack_op routine;
 156
 157     /// TBB context data to pass with the call to the stack_op routine
 158     void* data;
 159 } __cilk_tbb_stack_op_thunk;
 160
 161 /**
 162  * Thunk invoked by TBB when it is no longer interested in watching the stack
 163  * bound to the current thread.
 164  */
 165 typedef struct __cilk_tbb_unwatch_thunk {
 166     /// Function in Cilk runtime to call when TBB no longer wants to watch
 167     // stacks
 168     __cilk_tbb_pfn_unwatch_stacks routine;
 169
 170     /// Cilk runtime context data to pass with the call to the unwatch_stacks
 171     /// routine
 172     void* data;
 173 } __cilk_tbb_unwatch_thunk;
 174
 175 /**
 176  * Requests that Cilk invoke __cilk_tbb_orphan_thunk when it orphans a stack.
 177  * Cilk sets *u to a thunk that TBB should call when it is no longer
 178  * interested in watching the stack.
 179  *
 180  * If the thread is not yet bound to the Cilk runtime, the Cilk runtime should
 181  * save this data in thread-local storage until __cilkrts_bind_thread is called.
 182  *
 183  * Called by TBB, defined by Cilk.  This function is exported from the Cilk
 184  * runtime DLL/shared object.  This declaration also appears in
 185  * cilk/cilk_undocumented.h -- don't change one declaration without also
 186  * changing the other.
 187  *
 188  * @param u __cilk_tbb_unwatch_thunk.  This structure will be filled in by
 189  * the Cilk runtime to allow TBB to register that it is no longer interested
 190  * in watching the stack bound to the current thread.
 191  * @param o __cilk_tbb_stack_op_thunk.  This structure specifies the routine
 192  * that the Cilk runtime should call when an "interesting" change in the stack
 193  * associate with the current worker occurs.
 194  *
 195  * @return 0 indicates success.
 196  */
 197 CILK_EXPORT
 198 __cilk_tbb_retcode __cilkrts_watch_stack(__cilk_tbb_unwatch_thunk* u,
 199                                          __cilk_tbb_stack_op_thunk o);
 200
 201 __CILKRTS_END_EXTERN_C
 202
 203 #endif // ! defined(INCLUDED_CILK_TBB_INTEROP_DOT_H)