gcc/libcilkrts/runtime/cilk-tbb-interop.h

193 lines
7.2 KiB
C
Raw Normal View History

/* cilk-tbb-interop.h -*-C++-*-
*
*************************************************************************
*
* @copyright
* Copyright (C) 2009-2013, Intel Corporation
* All rights reserved.
*
* @copyright
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* * Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* * Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
* * Neither the name of Intel Corporation nor the names of its
* contributors may be used to endorse or promote products derived
* from this software without specific prior written permission.
*
* @copyright
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
* HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
* INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
* BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
* OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
* AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY
* WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
* POSSIBILITY OF SUCH DAMAGE.
**************************************************************************/
/**
* @file cilk-tbb-interop.h
*
* @brief Interface between TBB and Cilk to allow TBB to associate it's
* per-thread data with Cilk workers, and maintain the association as work
* moves between worker threads. This handles the case where TBB calls
* into a Cilk function which may later call back to a function making
* TBB calls.
*
* Each thunk structure has two pointers: \"routine\" and \"data\".
* The caller of the thunk invokes *routine, passing \"data\" as the void*
* parameter.
*/
#ifndef INCLUDED_CILK_TBB_INTEROP_DOT_H
#define INCLUDED_CILK_TBB_INTEROP_DOT_H
#include <cilk/common.h> // for CILK_EXPORT
__CILKRTS_BEGIN_EXTERN_C
/** A return code. 0 indicates success. */
typedef int __cilk_tbb_retcode;
/**
* Enumeration of reasons that Cilk will call the TBB stack operation
* function.
*
* When a non-empty stack is transfered between threads, the first thread must
* orphan it and the second thread must adopt it.
*
* An empty stack can be transfered similarly, or simply released by the first
* thread.
*
* Here is a summary of the actions as transitions on a state machine.
@verbatim
watch ORPHAN
-->--> -->--
/ \ / \
(freed empty stack) (TBB sees stack running on thread) (stack in limbo)
\ / \ /
--<-- --<--
RELEASE or ADOPT
unwatch
@endverbatim
*/
typedef enum __cilk_tbb_stack_op {
/**
* Disconnecting stack from a thread.
*
* The thunk must be invoked on the thread disconnecting itself from the
* stack. Must \"happen before\" the stack is adopted elsewhere.
*/
CILK_TBB_STACK_ORPHAN,
/**
* Reconnecting orphaned stack to a thread.
*
* The thunk must be invoked on the thread adopting the stack.
*/
CILK_TBB_STACK_ADOPT,
/**
* Releasing stack.
*
* The thunk must be invoked on the thread doing the releasing, Must
* \"happen before\" the stack is used elsewhere.
*/
CILK_TBB_STACK_RELEASE
} __cilk_tbb_stack_op;
/**
* Function that will be called by the Cilk runtime to inform TBB of a change
* in the stack associated with the current thread.
*
* It does not matter what stack the thunk runs on.
* The thread (not fiber) on which the thunk runs is important.
*
* @param op Enumerated value indicating what type of change is ocurring.
* @param data Context value provided by TBB in the __cilkrts_watch_stack
* call. This data is opaque to Cilk.
*
* @return 0 indicates success.
*/
typedef __cilk_tbb_retcode (*__cilk_tbb_pfn_stack_op)(enum __cilk_tbb_stack_op op,
void* data);
/**
* Function that will be called by TBB to inform the Cilk runtime that TBB
* is no longer interested in watching the stack bound to the current thread.
*
* @param data Context value provided to TBB by the __cilkrts_watch_stack
* call. This data is opaque to TBB.
*
* @return 0 indicates success.
*/
typedef __cilk_tbb_retcode (*__cilk_tbb_pfn_unwatch_stacks)(void *data);
/**
* Thunk invoked by Cilk to call back to TBB to tell it about a change in
* the stack bound to the current thread.
*/
typedef struct __cilk_tbb_stack_op_thunk {
/// Function in TBB the Cilk runtime should call when something
// "interesting" happens involving a stack
__cilk_tbb_pfn_stack_op routine;
/// TBB context data to pass with the call to the stack_op routine
void* data;
} __cilk_tbb_stack_op_thunk;
/**
* Thunk invoked by TBB when it is no longer interested in watching the stack
* bound to the current thread.
*/
typedef struct __cilk_tbb_unwatch_thunk {
/// Function in Cilk runtime to call when TBB no longer wants to watch
// stacks
__cilk_tbb_pfn_unwatch_stacks routine;
/// Cilk runtime context data to pass with the call to the unwatch_stacks
/// routine
void* data;
} __cilk_tbb_unwatch_thunk;
/**
* Requests that Cilk invoke __cilk_tbb_orphan_thunk when it orphans a stack.
* Cilk sets *u to a thunk that TBB should call when it is no longer
* interested in watching the stack.
*
* If the thread is not yet bound to the Cilk runtime, the Cilk runtime should
* save this data in thread-local storage until __cilkrts_bind_thread is called.
*
* Called by TBB, defined by Cilk. This function is exported from the Cilk
* runtime DLL/shared object. This declaration also appears in
* cilk/cilk_undocumented.h -- don't change one declaration without also
* changing the other.
*
* @param u __cilk_tbb_unwatch_thunk. This structure will be filled in by
* the Cilk runtime to allow TBB to register that it is no longer interested
* in watching the stack bound to the current thread.
* @param o __cilk_tbb_stack_op_thunk. This structure specifies the routine
* that the Cilk runtime should call when an "interesting" change in the stack
* associate with the current worker occurs.
*
* @return 0 indicates success.
*/
CILK_EXPORT
__cilk_tbb_retcode __cilkrts_watch_stack(__cilk_tbb_unwatch_thunk* u,
__cilk_tbb_stack_op_thunk o);
__CILKRTS_END_EXTERN_C
#endif // ! defined(INCLUDED_CILK_TBB_INTEROP_DOT_H)