/* 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)