1 /* cilk-tbb-interop.h -*-C++-*-
3 *************************************************************************
6 * Copyright (C) 2009-2013, Intel Corporation
10 * Redistribution and use in source and binary forms, with or without
11 * modification, are permitted provided that the following conditions
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
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.
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 **************************************************************************/
40 * @file cilk-tbb-interop.h
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
48 * Each thunk structure has two pointers: \"routine\" and \"data\".
49 * The caller of the thunk invokes *routine, passing \"data\" as the void*
53 #ifndef INCLUDED_CILK_TBB_INTEROP_DOT_H
54 #define INCLUDED_CILK_TBB_INTEROP_DOT_H
56 #include <cilk/common.h> // for CILK_EXPORT
58 __CILKRTS_BEGIN_EXTERN_C
60 /** A return code. 0 indicates success. */
61 typedef int __cilk_tbb_retcode
;
64 * Enumeration of reasons that Cilk will call the TBB stack operation
67 * When a non-empty stack is transfered between threads, the first thread must
68 * orphan it and the second thread must adopt it.
70 * An empty stack can be transfered similarly, or simply released by the first
73 * Here is a summary of the actions as transitions on a state machine.
78 (freed empty stack) (TBB sees stack running on thread) (stack in limbo)
85 typedef enum __cilk_tbb_stack_op
{
87 * Disconnecting stack from a thread.
89 * The thunk must be invoked on the thread disconnecting itself from the
90 * stack. Must \"happen before\" the stack is adopted elsewhere.
92 CILK_TBB_STACK_ORPHAN
,
95 * Reconnecting orphaned stack to a thread.
97 * The thunk must be invoked on the thread adopting the stack.
104 * The thunk must be invoked on the thread doing the releasing, Must
105 * \"happen before\" the stack is used elsewhere.
107 CILK_TBB_STACK_RELEASE
108 } __cilk_tbb_stack_op
;
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.
114 * It does not matter what stack the thunk runs on.
115 * The thread (not fiber) on which the thunk runs is important.
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.
121 * @return 0 indicates success.
123 typedef __cilk_tbb_retcode (*__cilk_tbb_pfn_stack_op
)(enum __cilk_tbb_stack_op op
,
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.
130 * @param data Context value provided to TBB by the __cilkrts_watch_stack
131 * call. This data is opaque to TBB.
133 * @return 0 indicates success.
135 typedef __cilk_tbb_retcode (*__cilk_tbb_pfn_unwatch_stacks
)(void *data
);
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.
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
;
146 /// TBB context data to pass with the call to the stack_op routine
148 } __cilk_tbb_stack_op_thunk
;
151 * Thunk invoked by TBB when it is no longer interested in watching the stack
152 * bound to the current thread.
154 typedef struct __cilk_tbb_unwatch_thunk
{
155 /// Function in Cilk runtime to call when TBB no longer wants to watch
157 __cilk_tbb_pfn_unwatch_stacks routine
;
159 /// Cilk runtime context data to pass with the call to the unwatch_stacks
162 } __cilk_tbb_unwatch_thunk
;
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.
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.
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.
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.
184 * @return 0 indicates success.
187 __cilk_tbb_retcode
__cilkrts_watch_stack(__cilk_tbb_unwatch_thunk
* u
,
188 __cilk_tbb_stack_op_thunk o
);
190 __CILKRTS_END_EXTERN_C
192 #endif // ! defined(INCLUDED_CILK_TBB_INTEROP_DOT_H)