libcilkrts/runtime/cilk-tbb-interop.h

   1 /* cilk-tbb-interop.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 cilk-tbb-interop.h
  41  *
  42  * @brief Interface between TBB and Cilk to allow TBB to associate it's
  43  * per-thread data with Cilk workers, and maintain the association as work
  44  * moves between worker threads.  This handles the case where TBB calls
  45  * into a Cilk function which may later call back to a function making
  46  * TBB calls.
  47  *
  48  * Each thunk structure has two pointers: \"routine\" and \"data\".
  49  * The caller of the thunk invokes *routine, passing \"data\" as the void*
  50  * parameter.
  51  */
  52
  53 #ifndef INCLUDED_CILK_TBB_INTEROP_DOT_H
  54 #define INCLUDED_CILK_TBB_INTEROP_DOT_H
  55
  56 #include <cilk/common.h>  // for CILK_EXPORT
  57
  58 __CILKRTS_BEGIN_EXTERN_C
  59
  60 /** A return code.  0 indicates success. */
  61 typedef int __cilk_tbb_retcode;
  62
  63 /**
  64  * Enumeration of reasons that Cilk will call the TBB stack operation
  65  * function.
  66  *
  67  * When a non-empty stack is transfered between threads, the first thread must
  68  * orphan it and the second thread must adopt it.
  69  *
  70  * An empty stack can be transfered similarly, or simply released by the first
  71  * thread.
  72  *
  73  * Here is a summary of the actions as transitions on a state machine.
  74 @verbatim
  75                        watch                                    ORPHAN
  76                        -->-->                                   -->--
  77                       /      \                                 /     \
  78    (freed empty stack)       (TBB sees stack running on thread)      (stack in limbo)
  79                       \     /                                  \     /
  80                        --<--                                    --<--
  81                        RELEASE or                               ADOPT
  82                        unwatch
  83 @endverbatim
  84  */
  85 typedef enum __cilk_tbb_stack_op {
  86    /**
  87     * Disconnecting stack from a thread.
  88     *
  89     * The thunk must be invoked on the thread disconnecting itself from the
  90     * stack.  Must \"happen before\" the stack is adopted elsewhere.
  91     */
  92     CILK_TBB_STACK_ORPHAN,
  93
  94     /**
  95      * Reconnecting orphaned stack to a thread.
  96      *
  97      * The thunk must be invoked on the thread adopting the stack.
  98      */
  99     CILK_TBB_STACK_ADOPT,
 100
 101    /**
 102     * Releasing stack.
 103     *
 104     * The thunk must be invoked on the thread doing the releasing, Must
 105     * \"happen before\" the stack is used elsewhere.
 106     */
 107     CILK_TBB_STACK_RELEASE
 108 } __cilk_tbb_stack_op;
 109
 110 /**
 111  * Function that will be called by the Cilk runtime to inform TBB of a change
 112  * in the stack associated with the current thread.
 113  *
 114  * It does not matter what stack the thunk runs on.
 115  * The thread (not fiber) on which the thunk runs is important.
 116  *
 117  * @param op Enumerated value indicating what type of change is ocurring.
 118  * @param data Context value provided by TBB in the __cilkrts_watch_stack
 119  * call.  This data is opaque to Cilk.
 120  *
 121  * @return 0 indicates success.
 122  */
 123 typedef __cilk_tbb_retcode (*__cilk_tbb_pfn_stack_op)(enum __cilk_tbb_stack_op op,
 124                                                       void* data);
 125
 126 /**
 127  * Function that will be called by TBB to inform the Cilk runtime that TBB
 128  * is no longer interested in watching the stack bound to the current thread.
 129  *
 130  * @param data Context value provided to TBB by the __cilkrts_watch_stack
 131  * call.  This data is opaque to TBB.
 132  *
 133  * @return 0 indicates success.
 134  */
 135 typedef __cilk_tbb_retcode (*__cilk_tbb_pfn_unwatch_stacks)(void *data);
 136
 137 /**
 138  * Thunk invoked by Cilk to call back to TBB to tell it about a change in
 139  * the stack bound to the current thread.
 140  */
 141 typedef struct __cilk_tbb_stack_op_thunk {
 142     /// Function in TBB the Cilk runtime should call when something
 143     // "interesting" happens involving a stack
 144     __cilk_tbb_pfn_stack_op routine;
 145
 146     /// TBB context data to pass with the call to the stack_op routine
 147     void* data;
 148 } __cilk_tbb_stack_op_thunk;
 149
 150 /**
 151  * Thunk invoked by TBB when it is no longer interested in watching the stack
 152  * bound to the current thread.
 153  */
 154 typedef struct __cilk_tbb_unwatch_thunk {
 155     /// Function in Cilk runtime to call when TBB no longer wants to watch
 156     // stacks
 157     __cilk_tbb_pfn_unwatch_stacks routine;
 158
 159     /// Cilk runtime context data to pass with the call to the unwatch_stacks
 160     /// routine
 161     void* data;
 162 } __cilk_tbb_unwatch_thunk;
 163
 164 /**
 165  * Requests that Cilk invoke __cilk_tbb_orphan_thunk when it orphans a stack.
 166  * Cilk sets *u to a thunk that TBB should call when it is no longer
 167  * interested in watching the stack.
 168  *
 169  * If the thread is not yet bound to the Cilk runtime, the Cilk runtime should
 170  * save this data in thread-local storage until __cilkrts_bind_thread is called.
 171  *
 172  * Called by TBB, defined by Cilk.  This function is exported from the Cilk
 173  * runtime DLL/shared object.  This declaration also appears in
 174  * cilk/cilk_undocumented.h -- don't change one declaration without also
 175  * changing the other.
 176  *
 177  * @param u __cilk_tbb_unwatch_thunk.  This structure will be filled in by
 178  * the Cilk runtime to allow TBB to register that it is no longer interested
 179  * in watching the stack bound to the current thread.
 180  * @param o __cilk_tbb_stack_op_thunk.  This structure specifies the routine
 181  * that the Cilk runtime should call when an "interesting" change in the stack
 182  * associate with the current worker occurs.
 183  *
 184  * @return 0 indicates success.
 185  */
 186 CILK_EXPORT
 187 __cilk_tbb_retcode __cilkrts_watch_stack(__cilk_tbb_unwatch_thunk* u,
 188                                          __cilk_tbb_stack_op_thunk o);
 189
 190 __CILKRTS_END_EXTERN_C
 191
 192 #endif // ! defined(INCLUDED_CILK_TBB_INTEROP_DOT_H)