/*  reducer.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 reducer.h
 *
 *  @brief Defines foundation classes for creating Cilk reducers.
 *
 *  @ingroup Reducers
 *
 *  @see @ref pagereducers
 *
 *  @defgroup Reducers Reducers
 */
 
#ifndef REDUCER_H_INCLUDED
#define REDUCER_H_INCLUDED

#include "cilk/hyperobject_base.h"
#include "cilk/metaprogramming.h"

#ifdef __cplusplus

//===================== C++ interfaces ===================================

#include <new>

namespace cilk {

/** Base class for defining monoids.
 *
 *  The monoid_base class template is useful for creating classes that model
 *  the monoid concept. It provides the core type and memory management
 *  functionality.  A subclass of monoid_base need only declare and implement
 *  the `identity` and `reduce` functions. 
 *
 *  The monoid_base class also manages the integration between the monoid, the
 *  reducer class that is based on it, and an optional view class which wraps
 *  value objects and restricts access to their operations.
 *
 *  @tparam Value   The value type for the monoid.
 *  @tparam View    An optional view class that serves as a proxy for the value
 *                  type.
 *
 *  @see monoid_with_view
 */
template <typename Value, typename View = Value>
class monoid_base
{
protected:

    /** Class for provisionally constructed objects.
     *
     *  The monoid_base::construct() functions manually construct both a monoid
     *  and a view. If one of these is constructed successfully, and the
     *  construction of the other (or some other initialization) fails, then 
     *  the first one must be destroyed to avoid a memory leak. Because the
     *  construction is explicit, the destruction must be explicit, too.
     *
     *  A provisional_guard object wraps a pointer to a newly constructed
     *  object. A call to its confirm() function confirms that the object is
     *  really going to be used. If the guard is destroyed without being
     *  confirmed, then the pointed-to object is destroyed (but not
     *  deallocated).
     *  
     *  Expected usage:
     *
     *      provisional_guard<T1> x1_provisional( new (x1) T1() );
     *      … more initialization …
     *      x1_provisional.confirm();
     *
     *  or
     *
     *      provisional_guard<T1> x1_provisional( new (x1) T1() );
     *      x1_provisional.confirm_if( new (x2) T2() );
     *
     *  If an exception is thrown in the “more initialization” code in the 
     *  first example, or in the `T2` constructor in the second example, then
     *  `x1_provisional` will not be confirmed, so when its destructor is 
     *  called during exception unwinding, the `T1` object that was constructed
     *  in `x1` will be destroyed.
     *
     *  @see provisional()
     *
     *  @tparam Type    The type of the provisionally constructed object.
     */
    template <typename Type>
    class provisional_guard {
        Type* m_ptr;
    
    public:
    
        /** Constructor. Creates a guard for a provisionally constructed object.
         *
         *  @param ptr  A pointer to the provisionally constructed object.
         */
        provisional_guard(Type* ptr) : m_ptr(ptr) {}
        
        /** Destructor. Destroy the object pointed to by the contained pointer
         *  if it has not been confirmed.
         */
        ~provisional_guard() { if (m_ptr) m_ptr->~Type(); }
        
        /** Confirm the provisional construction. Do *not* delete the contained
         *  pointer when the guard is destroyed.
         */
        void confirm() { m_ptr = 0; }
        
        /** Confirm provisional construction if argument is non-null. Note that
         *  if an exception is thrown during evaluation of the argument
         *  expression, then this function will not be called, and the
         *  provisional object will not be confirmed. This allows the usage:
         *
         *      x1_provisional.confirm_if( new (x2) T2() );
         *
         *  @param cond An arbitrary pointer. The provisional object will be
         *              confirmed if @a cond is not null.
         * 
         *  @returns    The value of the @a cond argument.
         */
        template <typename Cond>
        Cond* confirm_if(Cond* cond) { if (cond) m_ptr = 0; return cond; }
    };

    
    /** Create a provisional_guard object. This function allows simpler code
     *  when the only use of a provisional_guard is in a
     *  provisional_guard::confirm_if() call immediately following its
     *  creation. Instead of
     *
     *      provisional_guard<T>guard( new (ptr_to_T) T() );
     *      guard.confirm_if( new (ptr_to_U) U() );
     *
     *  you can just write
     *
     *      provisional( new (ptr_to_T) T() ).confirm_if( new (ptr_to_U) U() );
     *
     *  @tparam Type    The type of the provisionally constructed object.
     *
     *  @param  ptr     A pointer to a provisionally constructed object.
     *
     *  @returns        A @ref provisional_guard object that guards the
     *                  provisionally constructed object pointed to by @a ptr.
     */
    template <typename Type> 
    static provisional_guard<Type> provisional(Type* ptr) 
        { return provisional_guard<Type>(ptr); }

public:

    /** Value type of the monoid.
     */
    typedef Value   value_type;
    
    /** View type of the monoid. Defaults to be the same as the value type.
     *  @see monoid_with_view
     */
    typedef View    view_type;
    
    enum { 
        /** Should reducers created with this monoid be aligned?
         *
         *  @details
         *  “Aligned” means that the view is allocated at a cache-line aligned
         *  offset in the reducer, and the reducer must be cache-line aligned.
         *  “Unaligned” means that the reducer as a whole is just naturally 
         *  aligned, but it contains a large enough block of uninitialized 
         *  storage for a cache-line aligned view to be allocated in it at
         *  reducer construction time.
         *
         *  Since the standard heap allocator (new reducer) does not allocate 
         *  cache-line aligned storage, only unaligned reducers can be safely
         *  allocated on the heap.
         *  
         *  Default is false (unaligned) unless overridden in a subclass.
         *
         *  @since 1.02
         *  (In Cilk library versions 1.0 and 1.01, the default was true.
         *  In Cilk library versions prior to 1.0, reducers were always aligned,
         *  and this data member did not exist.)
         */
        align_reducer = false 
    };
    
    /** Destroy a view. Destroys (without deallocating) the @a View object
     *  pointed to by @a p.
     *
     *  @param p    The address of the @a View object to be destroyed.
     */
    void destroy(view_type* p) const { p->~view_type(); }

    /** Allocate raw memory. Allocate @a s bytes of memory with no
     *  initialization.
     *
     *  @param s    The number of bytes of memory to allocate.
     *  @return     An untyped pointer to the allocated memory.
     */
    void* allocate(size_t s) const { return operator new(s); }

    /** Deallocate raw memory. Deallocates the memory pointed to by @a p 
     *  without doing any destruction.
     *
     *  @param p    Pointer to the memory to be deallocated.
     *
     *  @pre        @a p points to a block of memory that was allocated by a
     *              call to allocate().
     */
    void deallocate(void* p) const { operator delete(p); }

    /** Create the identity value. Constructs (without allocating) a @a View
     *  object representing the default value of the @a Value type.
     *
     *  @param p    A pointer to a block of raw memory large enough to hold a 
     *              @a View object.
     *
     *  @post       The memory pointed to by @a p contains a @a View object that
     *              represents the default value of the @a View type.
     *
     *  @deprecated This function constructs the @a View object with its default
     *              constructor, which will often, but not always, yield the
     *              appropriate identity value. Monoid classes should declare
     *              their identity function explicitly, rather than relying on
     *              this default definition.
     */
    void identity(View* p) const { new ((void*) p) View(); }
    
    
    /** @name Construct the monoid and the view with arbitrary arguments.
     *
     *  A @ref reducer object contains monoid and view data members, which are
     *  declared as raw storage (byte arrays), so that they are not implicitly
     *  constructed when the reducer is constructed. Instead, a reducer
     *  constructor calls one of the monoid class’s static construct() 
     *  functions with the addresses of the monoid and the view, and the
     *  construct() function uses placement `new` to construct them.
     *
     *  This allows the monoid to determine the order in which the monoid and
     *  view are constructed, and to make one of them dependent on the other.
     *
     *  Any arguments to the reducer constructor are just passed on as 
     *  additional arguments to the construct() function (after the monoid
     *  and view addresses).
     *
     *  Any monoid whose needs are satisfied by the suite of construct() 
     *  functions below, such as @ref monoid_with_view, can just inherit them
     *  from monoid_base. Other monoids will need to provide their own versions
     *  to override the monoid_base functions.
     */
    //@{
    
    /** Default-construct the monoid, and pass zero to five const reference
     *  arguments to the view constructor.
     */
    //@{
    
    template <typename Monoid>
    static void construct(Monoid* monoid, View* view)
        { provisional( new ((void*)monoid) Monoid() ).confirm_if( 
            (monoid->identity(view), view) ); }

    template <typename Monoid, typename T1>
    static void construct(Monoid* monoid, View* view, const T1& x1)
        { provisional( new ((void*)monoid) Monoid() ).confirm_if( 
            new ((void*)view) View(x1) ); }

    template <typename Monoid, typename T1, typename T2>
    static void construct(Monoid* monoid, View* view, 
                            const T1& x1, const T2& x2)
        { provisional( new ((void*)monoid) Monoid() ).confirm_if( 
            new ((void*)view) View(x1, x2) ); }

    template <typename Monoid, typename T1, typename T2, typename T3>
    static void construct(Monoid* monoid, View* view, 
                            const T1& x1, const T2& x2, const T3& x3)
        { provisional( new ((void*)monoid) Monoid() ).confirm_if( 
            new ((void*)view) View(x1, x2, x3) ); }

    template <typename Monoid, typename T1, typename T2, typename T3, 
                typename T4>
    static void construct(Monoid* monoid, View* view, 
                            const T1& x1, const T2& x2, const T3& x3, 
                            const T4& x4)
        { provisional( new ((void*)monoid) Monoid() ).confirm_if( 
            new ((void*)view) View(x1, x2, x3, x4) ); }

    template <typename Monoid, typename T1, typename T2, typename T3, 
                typename T4, typename T5>
    static void construct(Monoid* monoid, View* view, 
                            const T1& x1, const T2& x2, const T3& x3, 
                            const T4& x4, const T5& x5)
        { provisional( new ((void*)monoid) Monoid() ).confirm_if( 
            new ((void*)view) View(x1, x2, x3, x4, x5) ); }
        
    //@}
    
    /** Default-construct the monoid, and pass one non-const reference argument
     *  to the view constructor.
     */
    //@{
    template <typename Monoid, typename T1>
    static void construct(Monoid* monoid, View* view, T1& x1)
        { provisional( new ((void*)monoid) Monoid() ).confirm_if( 
            new ((void*)view) View(x1) ); }
    //@}

    /** Copy-construct the monoid, and pass zero to four const reference
     *  arguments to the view constructor.
     */
    //@{

    template <typename Monoid>
    static void construct(Monoid* monoid, View* view, const Monoid& m)
        { provisional( new ((void*)monoid) Monoid(m) ).confirm_if( 
            new ((void*)view) View() ); }

    template <typename Monoid, typename T1>
    static void construct(Monoid* monoid, View* view, const Monoid& m, 
                            const T1& x1)
        { provisional( new ((void*)monoid) Monoid(m) ).confirm_if( 
            new ((void*)view) View(x1) ); }
        
    template <typename Monoid, typename T1, typename T2>
    static void construct(Monoid* monoid, View* view, const Monoid& m, 
                            const T1& x1, const T2& x2)
    { provisional( new ((void*)monoid) Monoid(m) ).confirm_if( 
        new ((void*)view) View(x1, x2) ); }
        
    template <typename Monoid, typename T1, typename T2, typename T3>
    static void construct(Monoid* monoid, View* view, const Monoid& m, 
                            const T1& x1, const T2& x2, const T3& x3)
    {
        provisional( new ((void*)monoid) Monoid(m) ).confirm_if(
            new ((void*)view) View(x1, x2, x3) );
    }
        
    template <typename Monoid, typename T1, typename T2, typename T3, 
                typename T4>
    static void construct(Monoid* monoid, View* view, const Monoid& m, 
                            const T1& x1, const T2& x2, const T3& x3, 
                            const T4& x4)
    {
        provisional( new ((void*)monoid) Monoid(m) ).confirm_if(
            new ((void*)view) View(x1, x2, x3, x4) );
    }
        
    //@}
    
    //@}
};


/** Monoid class that gets its value type and identity and reduce operations
 *  from its view.
 *
 *  A simple implementation of the monoid-view-reducer architecture would
 *  distribute knowledge about the type and operations for the reduction 
 *  between the monoid and the view — the identity and reduction operations are
 *  specified in the monoid, the reduction operations are implemented in the
 *  view, and the value type is specified in both the monoid and the view.
 *  This is inelegant.
 *
 *  monoid_with_view is a subclass of @ref monoid_base that gets its value type
 *  and its identity and reduction operations from its view class. No
 *  customization of the monoid_with_view class itself is needed beyond
 *  instantiating it with an appropriate view class. (Customized subclasses of
 *  monoid_with_view may be needed for other reasons, such as to keep some
 *   state for the reducer.) All of the Cilk predefined reducers use
 *  monoid_with_view or one of its subclasses.
 *  
 *  The view class `View` of a monoid_with_view must provide the following public definitions:
 *
 *  Definition                       | Meaning
 *  ---------------------------------|--------
 *  `value_type`                     | a typedef of the value type for the reduction
 *  `View()`                         | a default constructor which constructs the identity value for the reduction
 *  `void reduce(const View* other)` | a member function which applies the reduction operation to the values of `this` view and the `other` view, leaving the result as the value of `this` view, and leaving the value of the `other` view undefined (but valid)
 *
 *  @tparam View    The view class for the monoid.
 *  @tparam Align   If true, reducers instantiated on this monoid will be
 *                  cache-aligned. By default, library reducers (unlike legacy
 *                  library reducer _wrappers_) are aligned only as required by
 *                  contents.
 */
template <class View, bool Align = false>
class monoid_with_view : public monoid_base<typename View::value_type, View>
{
public:
    /** Should reducers created with this monoid be aligned?
     */
    enum { align_reducer = Align };
    
    /** Create the identity value.
     *
     *  Implements the monoid `identity` operation by using the @a View class’s
     *  default constructor.
     *
     *  @param  p   A pointer to a block of raw memory large enough to hold a 
     *              @p View object.
     */
    void identity(View* p) const { new ((void*)p) View(); }
    
    /** Reduce the values of two views.
     *
     *  Implements the monoid `reduce` operation by calling the left view’s
     *  `%reduce()` function with the right view as an operand.
     *
     *  @param  left    The left operand of the reduce operation.
     *  @param  right   The right operand of the reduce operation.
     *  @post           The left view contains the result of the reduce
     *                  operation, and the right view is undefined.
     */
    void reduce(View* left, View* right) const { left->reduce(right); }
};


/** Base class for simple views with (usually) scalar values.
 *
 *  The scalar_view class is intended as a base class which provides about half
 *  of the required definitions for simple views. It defines the `value_type`
 *  required by a @ref monoid_with_view (but not the identity constructor and
 *  reduce operation, which are inherently specific to a particular kind of
 *  reduction). It also defines the value access functions which will be called
 *  by the corresponding @ref reducer functions. (It uses copy semantics for 
 *  the view_move_in() and view_move_out() functions, which is appropriate
 *  for simple scalar types, but not necessarily for more complex types like
 *  STL containers.
 *
 *  @tparam Type    The type of value wrapped by the view.
 */
template <typename Type>
class scalar_view
{
protected:
    Type m_value;       ///< The wrapped accumulator variable.

public:
    /** Value type definition required by @ref monoid_with_view.
     */
    typedef Type value_type;
    
    /** Default constructor.
     */
    scalar_view() : m_value() {}    
    
    /** Value constructor.
     */
    scalar_view(const Type& v) : m_value(v) {}
    
    /** @name Value functions required by the reducer class.
     *
     *  Note that the move in/out functions use simple assignment semantics.
     */
    //@{

    /** Set the value of the view.
     */
    void view_move_in(Type& v) { m_value = v; }

    /** Get the value of the view.
     */
    void view_move_out(Type& v) { v = m_value; }

    /** Set the value of the view.
     */
    void view_set_value(const Type& v) { m_value = v; }

    /** Get the value of the view.
     */
    Type const& view_get_value() const { return m_value; }
    
    /** Get a reference to the value contained in the view. For legacy
     *  reducer support only.
     */
    Type      & view_get_reference()       { return m_value; }
    
    /** Get a reference to the value contained in the view. For legacy
     *  reducer support only.
     */
    Type const& view_get_reference() const { return m_value; }
    //@}
};


/** Wrapper class for move-in construction.
 *
 *  Some types allow their values to be _moved_ as an alternative to copying.
 *  Moving a value may be much faster than copying it, but may leave the value
 *  of the move’s source undefined. Consider the `swap` operation provided by
 *  many STL container classes:
 *
 *      list<T> x, y;
 *      x = y;      // Copy
 *      x.swap(y);  // Move
 *
 *  The assignment _copies_ the value of `y` into `x` in time linear in the 
 *  size of `y`, leaving `y` unchanged. The `swap` _moves_ the  value of `y`
 *  into `x` in constant time, but it also moves the value of `x` into `y`,
 *  potentially leaving `y` undefined.
 *  
 *  A move_in_wrapper simply wraps a pointer to an object. It is created by a
 *  call to cilk::move_in(). Passing a move_in_wrapper to a view constructor
 *  (actually, passing it to a reducer constructor, which passes it to the
 *  monoid `construct()` function, which passes it to the view constructor)
 *  allows, but does not require, the value pointed to by the wrapper to be
 *  moved into the view instead of copied.
 *
 *  A view class exercises this option by defining a _move-in constructor_,
 *  i.e., a constructor with a move_in_wrapper parameter. The constructor calls
 *  the wrapper’s `value()` function to get a reference to its pointed-to 
 *  value, and can then use that reference in a move operation.
 *
 *  A move_in_wrapper also has an implicit conversion to its pointed-to value,
 *  so if a view class does not define a move-in constructor, its ordinary 
 *  value constructor will be called with the wrapped value. For example, an
 *  @ref ReducersAdd "op_add" view does not have a move-in constructor, so
 *
 *      int x;
 *      reducer< op_add<int> > xr(move_in(x));
 *
 *  will simply call the `op_add_view(const int &)` constructor. But an 
 *  @ref ReducersList "op_list_append" view does have a move-in  constructor,
 *  so
 *
 *      list<int> x;
 *      reducer< op_list_append<int> > xr(move_in(x));
 *
 *  will call the `op_list_append_view(move_in_wrapper<int>)` constructor,
 *  which can `swap` the value of `x` into the view.
 *
 *  @note   Remember that passing the value of a variable to a reducer
 *          constructor using a move_in_wrapper leaves the variable undefined.
 *          You cannot assume that the constructor either will or will not copy
 *          or move the value.
 *
 *  @tparam Type    The type of the wrapped value.
 *
 *  @see cilk::move_in()
 */
template <typename Type>
class move_in_wrapper
{
    Type *m_pointer;
public:
    
    /** Constructor that captures the address of its argument. This is almost
     *  always called from the @ref move_in function.
     */
    explicit move_in_wrapper(Type& ref) : m_pointer(&ref) { }
    
    /** Implicit conversion to the wrapped value. This allows a move_in_wrapper
     *  to be used where a value of the wrapped type is expected, in which case
     *  the wrapper is completely transparent.
     */
    operator Type&() const { return *m_pointer; }
    
    /** Get a reference to the pointed-to value. This has the same effect as 
     *  the implicit conversion, but makes the intent clearer in a move-in
     *  constructor.
     */
    Type& value() const { return *m_pointer; }
};

/** Function to create a move_in_wrapper for a value.
 *
 *  @tparam Type    The type of the argument, which will be the `type` of the 
 *                  created wrapper.
 *
 *  @see move_in_wrapper
 */
template <typename Type>
inline
move_in_wrapper<Type> move_in(Type& ref)
    { return move_in_wrapper<Type>(ref); }


/** @copydoc move_in(Type&)
 *
 *  @note   Applying a function that is explicitly specified as modifying its
 *          argument to a const argument is obviously an irrational thing to 
 *          do. This move_in() variant is just provided to allow calling a
 *          move-in constructor with a function return value, which the 
 *          language treats as a const. Using it for any other purpose will
 *          probably end in tears.
 */
template <typename Type>
inline
move_in_wrapper<Type> move_in(const Type& ref)
    { return move_in_wrapper<Type>(ref); }


/** Wrapper class to allow implicit downcasts to reducer subclasses.
 *
 *  The Cilk library contains a collection of reducer wrapper classes which 
 *  were created before the `cilk::reducer<Monoid>` style was developed. For 
 *  example, `cilk::reducer_opadd<Type>` provided essentially the same
 *  functionality that is now provided by 
 *  `cilk::reducer< cilk::op_add<Type> >`. These legacy reducer classes are 
 *  deprecated, but still supported, and they have been reimplemented as 
 *  subclasses of the corresponding `cilk::reducer` classes. For example:
 *
 *      template <class T>
 *      reducer_opadd<T> : public reducer< op_add<T> > { ... };
 *
 *  This reimplementation allows transparent conversion between legacy and 
 *  new reducers. That is, a `reducer<op_add>*` or `reducer<op_add>&` can be 
 *  used anywhere that a `reducer_opadd*` or `reducer_opadd&` is expected, 
 *  and vice versa. 
 *
 *  The conversion from the legacy reducer to the new reducer is just an 
 *  up-cast, which is provided for free by C++. The conversion from the new 
 *  reducer to the legacy reducer is a down-cast, though, which requires an 
 *  explicit conversion member function in the `reducer` class. The challenge
 *  is to define a function in the reducer template class which will convert
 *  each cilk::reducer specialization to the corresponding legacy reducer, 
 *  if there is one.
 *
 *  The trick is in the legacy_reducer_downcast template class, which provides
 *  a mapping from  `cilk::reducer` specializations to legacy reducer classes.
 *  `reducer<Monoid>` has a conversion function to convert itself to 
 *  `legacy_reducer_downcast< reducer<Monoid> >::%type`. By default,
 *  `legacy_reducer_downcast<Reducer>::%type` is just a trivial subclass of
 *  `Reducer`, which is uninteresting, but a reducer with a legacy counterpart
 *  will have a specialization of `legacy_reducer_downcast` whose `type` is 
 *  the corresponding legacy reducer. For example:
 *
 *      template <typename Type>
 *      struct legacy_reducer_downcast< reducer< op_add<Type> > >
 *      {
 *          typedef reducer_opadd<Type> type;
 *      };
 *
 *
 *  @tparam Reducer The new-style reducer class whose corresponding legacy reducer class
 *                  is `type`, if there is such a legacy reducer class.
 */
template <typename Reducer>
struct legacy_reducer_downcast
{
    /** The related legacy reducer class.
     *
     *  By default, this is just a trivial subclass of Reducer, but it can be 
     *  overridden in the specialization of legacy_reducer_downcast for 
     *  a reducer that has a corresponding legacy reducers.
     */
    struct type : Reducer { };
};


namespace internal {
/// @cond internal

template <typename Value, typename View>
struct reducer_set_get
{
    static View theView;  // Declared but not defined

    // sizeof(notchar) is guaranteed larger than 1
    struct notchar { char x[2]; };

    // check_for_ref returns char if 'get_value' returns by value and notchar
    // if 'get_value' returns by reference.
    static char    check_for_ref(Value,  ...);
    static notchar check_for_ref(Value&, int);

    enum { GET_VALUE_BY_VALUE =
           (1 == sizeof(check_for_ref(theView.view_get_value(), 0))) } ;

    typedef typename condition<GET_VALUE_BY_VALUE,
                               Value, const Value&>::type get_value_type;

    static void move_in(View& view, Value& v)   { view.view_move_in(v); }
    static void move_out(View& view,  Value& v) { view.view_move_out(v); }

    static void set_value(View& view, const Value& v)
        { view.view_set_value(v); }

    static get_value_type get_value(const View& view)
        { return view.view_get_value(); }
};

template <typename Value>
struct reducer_set_get<Value, Value>
{
    typedef const Value& get_value_type;

    static void move_in(Value& view, Value& v)   { view = v; }
    static void move_out(Value& view,  Value& v) { v = view; }

    static void set_value(Value& view, const Value& v) { view = v; }

    static get_value_type get_value(const Value& view) { return view; }
};

/// @endcond


/** Base class defining the data layout that is common to all reducers.
 */
template <typename Monoid> 
class reducer_base {
    typedef typename Monoid::view_type view_type;

    // This makes the reducer a hyper-object. (Partially initialized in
    // the derived reducer_content class.)
    //
    __cilkrts_hyperobject_base      m_base;

    // The monoid is allocated here as raw bytes, and is constructed explicitly
    // by a call to the monoid_type::construct() function in the constructor of
    // the `reducer` subclass.
    //
    storage_for_object<Monoid>      m_monoid;

    // Used for sanity checking at destruction.
    //
    void*                           m_initialThis;
    
    // The leftmost view comes next. It is defined in the derived
    // reducer_content class.
    
    /** @name C-callable wrappers for the C++-coded monoid dispatch functions.
     */
    //@{
    
    static void reduce_wrapper(void* r, void* lhs, void* rhs);
    static void identity_wrapper(void* r, void* view);
    static void destroy_wrapper(void* r, void* view);
    static void* allocate_wrapper(void* r, __STDNS size_t bytes);
    static void deallocate_wrapper(void* r, void* view);
    
    //@}

protected:

    /** Constructor.
     *
     *  @param  leftmost    The address of the leftmost view in the reducer.
     */
    reducer_base(char* leftmost) 
    {
        static const cilk_c_monoid c_monoid_initializer = {
            (cilk_c_reducer_reduce_fn_t)     &reduce_wrapper,
            (cilk_c_reducer_identity_fn_t)   &identity_wrapper,
            (cilk_c_reducer_destroy_fn_t)    &destroy_wrapper,
            (cilk_c_reducer_allocate_fn_t)   &allocate_wrapper,
            (cilk_c_reducer_deallocate_fn_t) &deallocate_wrapper
        };

        m_base.__c_monoid = c_monoid_initializer;
        m_base.__flags = 0;
        m_base.__view_offset = (char*)leftmost - (char*)this;
        m_base.__view_size = sizeof(view_type);
        m_initialThis = this;
        
        __cilkrts_hyper_create(&m_base);
    }
    
    /** Destructor.
     */
    __CILKRTS_STRAND_STALE(~reducer_base())
    {
        // Make sure we haven't been memcopy'd or corrupted
        __CILKRTS_ASSERT(
            this == m_initialThis ||
            // Allow for a layout bug that may put the initialThis field one 
            // word later in 1.0 reducers than in 0.9  and 1.1 reducers.
            this == *(&m_initialThis + 1)
        );
        __cilkrts_hyper_destroy(&m_base);
    }

    /** Monoid data member.
     *
     *  @return A pointer to the reducer’s monoid data member.
     */
    Monoid* monoid_ptr() { return &m_monoid.object(); }

    /** Leftmost view data member.
     *
     *  @return A pointer to the reducer’s leftmost view data member.
     *
     *  @note   This function returns the address of the *leftmost* view, 
     *          which is unique for the lifetime of the reducer. It is 
     *          intended to be used in constructors and destructors. 
     *          Use the reducer::view() function to access the per-strand 
     *          view instance.
     */
    view_type* leftmost_ptr() 
    {
        char* view_addr = (char*)this + m_base.__view_offset;
        return reinterpret_cast<view_type*>(view_addr);
    }
    
public:

    /** @name Access the current view.
     *
     *  These functions return a reference to the instance of the reducer’s 
     *  view that was created for the current strand of a parallel computation
     *  (and create it if it doesn’t already exist). Note the difference from
     *  the (private) leftmost_ptr() function, which returns a pointer to the
     *  _leftmost_ view, which is the same in all strands.
     */
    //@{
    
    /** Per-strand view instance.
     *
     *  @return A reference to the per-strand view instance.
     */
    view_type& view() 
    {
        return *static_cast<view_type *>(__cilkrts_hyper_lookup(&m_base)); 
    }
    
    /** @copydoc view()
     */
    const view_type& view() const 
    { 
        return const_cast<reducer_base*>(this)->view(); 
    }
    
    //@}
    
    /** Initial view pointer field.
     *
     *  @internal
     *
     *  @return a reference to the m_initialThis field.
     *
     *  @note   This function is provided for “white-box” testing of the
     *          reducer layout code. There is never any reason for user code
     *          to call it.
     */
    const void* const & initial_this() const { return m_initialThis; }
};

template <typename Monoid>
void reducer_base<Monoid>::reduce_wrapper(void* r, void* lhs, void* rhs)
{
    Monoid* monoid = static_cast<reducer_base*>(r)->monoid_ptr();
    monoid->reduce(static_cast<view_type*>(lhs),
                         static_cast<view_type*>(rhs));
}

template <typename Monoid>
void reducer_base<Monoid>::identity_wrapper(void* r, void* view)
{
    Monoid* monoid = static_cast<reducer_base*>(r)->monoid_ptr();
    monoid->identity(static_cast<view_type*>(view));
}

template <typename Monoid>
void reducer_base<Monoid>::destroy_wrapper(void* r, void* view)
{
    Monoid* monoid = static_cast<reducer_base*>(r)->monoid_ptr();
    monoid->destroy(static_cast<view_type*>(view));
}

template <typename Monoid>
void* reducer_base<Monoid>::allocate_wrapper(void* r, __STDNS size_t bytes)
{
    Monoid* monoid = static_cast<reducer_base*>(r)->monoid_ptr();
    return monoid->allocate(bytes);
}

template <typename Monoid>
void reducer_base<Monoid>::deallocate_wrapper(void* r, void* view)
{
    Monoid* monoid = static_cast<reducer_base*>(r)->monoid_ptr();
    monoid->deallocate(static_cast<view_type*>(view));
}


/** Base class defining the data members of a reducer.
 *
 *  @tparam Aligned The `m_view` data member, and therefore the entire 
 *                  structure, are cache-line aligned if this parameter
 *                  is `true'.
 */
template <typename Monoid, bool Aligned = Monoid::align_reducer>
class reducer_content;

/** Base class defining the data members of an aligned reducer.
 */
template <typename Monoid>
class reducer_content<Monoid, true> : public reducer_base<Monoid>
{
    typedef typename Monoid::view_type view_type;
    
    // The leftmost view is defined as raw bytes. It will be constructed
    // by the monoid `construct` function. It is cache-aligned, which 
    // will push it into a new cache line. Furthermore, its alignment causes
    // the reducer as a whole to be cache-aligned, which makes the reducer 
    // size a multiple of a cache line. Since there is nothing in the reducer 
    // after the view, all this means that the leftmost view gets one or more
    // cache lines all to itself, which prevents false sharing.
    //
    __CILKRTS_CACHE_ALIGN
    char m_leftmost[sizeof(view_type)];

    /** Test if the reducer is cache-line-aligned.
     *
     *  Used in assertions.
     */
    bool reducer_is_cache_aligned() const
        { return 0 == ((std::size_t) this & (__CILKRTS_CACHE_LINE__ - 1)); }
        
protected:

    /** Constructor.
     */
    reducer_content() : reducer_base<Monoid>((char*)&m_leftmost)
    {
#ifndef CILK_IGNORE_REDUCER_ALIGNMENT
    assert(reducer_is_cache_aligned() &&
           "Reducer should be cache aligned. Please see comments following this assertion for explanation and fixes.");
#endif
    /*  "REDUCER SHOULD BE CACHE ALIGNED" ASSERTION.
     *
     *  This Reducer class instantiation specifies cache-line alignment of the 
     *  leftmost view field (and, implicitly, of the reducer itself). You got
     *  this assertion because a reducer with this class was allocated at a
     *  non-cache-aligned address, probably because it was allocated on the 
     *  heap with `new`. This can be a problem for two reasons:
     *
     *  1.  If the leftmost view is not on a cache line by itself, there might
     *      be a slowdown resulting from accesses to the same cache line from
     *      different threads.
     *
     *  2.  The compiler thinks that reducer is cache-line aligned, but it
     *      really isn't. If the reducer is contained in a structure, then the
     *      compiler will believe that the containing structure, and other
     *      fields contained in it, are also more aligned than they really
     *      are. In particular, if the structure contains a numeric array that
     *      is used in a vectorizable loop, then the compiler might generate
     *      invalid vector instructions, resulting in a runtime error.
     *
     *  The compiler will always allocate reducer variables, and structure
     *  variables containing reducers, with their required alignment.
     *  Reducers, and structures containing a reducer, which are allocated
     *  on the heap with `new` will _not_ be properly aligned.
     *
     *  There are three ways that you can fix this assertion failure.
     *
     *  A.  Rewrite your code to use the new-style `reducer< op_XXX<Type> >` 
     *      instead of the legacy `reducer_XXX<type>`. The new-style reducers
     *      are not declared to be cache-aligned, and will work properly if
     *      they are not cache-aligned.
     *
     *  B.  If you must allocate an old-style reducer or a structure containing
     *      a reducer on the heap, figure out how to align it correctly. The
     *      suggested fix is to use `cilk::aligned_new()` and 
     *      `cilk::aligned_delete()` instead of `new` and `delete`, as follows:
     *
     *          Type* ptr = cilk::aligned_new<Type>(constructor-arguments);
     *          cilk::aligned_delete(ptr);
     *
     *  C.  Define the macro CILK_IGNORE_REDUCER_ALIGNMENT, which will suppress
     *      the assertion check. Do this only if you are comfortable that
     *      problem (2) above will not occur.
     */
    }
};

/** Base class defining the data members of an unaligned reducer.
 */
template <typename Monoid>
class reducer_content<Monoid, false> : public reducer_base<Monoid>
{
    typedef typename Monoid::view_type view_type;      ///< The view type.

    // Reserve space for the leftmost view. The view will be allocated at an
    // aligned offset in this space at runtime, to guarantee that the view
    // will get one or more cache lines all to itself, to prevent false 
    // sharing.
    //
    // The number of bytes to reserve is determined as follows:
    // * Start with the view size.
    // * Round up to a multiple of the cache line size, to get the total size
    //   of the cache lines that will be dedicated to the view.
    // * Add (cache line size - 1) filler bytes to guarantee that the reserved
    //   area will contain a cache-aligned block of the required cache lines,
    //   no matter where the reserved area starts.
    //
    char m_leftmost[
        // View size rounded up to multiple cache lines
        (   (sizeof(view_type) + __CILKRTS_CACHE_LINE__ - 1)
            & ~ (__CILKRTS_CACHE_LINE__ - 1)
        )
        // plus filler to allow alignment.
        + __CILKRTS_CACHE_LINE__ - 1
        ];

protected:

    /** Constructor. Find the first cache-aligned position in the reserved
     *  area, and pass it to the base constructor as the leftmost view 
     *  address.
     */
    reducer_content() : 
        reducer_base<Monoid>(
            (char*)( ((std::size_t)&m_leftmost + __CILKRTS_CACHE_LINE__ - 1)
                     & ~ (__CILKRTS_CACHE_LINE__ - 1) ) )
    {}
};


} // namespace internal


// The __cilkrts_hyperobject_ functions are defined differently depending on
// whether a file is compiled with or without the CILK_STUB option. Therefore,
// reducers compiled in the two modes should be link-time incompatible, so that
// object files compiled with stubbed reducers won't be linked into an
// unstubbed program, or vice versa. We achieve this by putting the reducer
// class definition into the cilk::stub namespace in a stubbed compilation.

#ifdef CILK_STUB
namespace stub {
#endif

/** Reducer class.
 *
 *  A reducer is instantiated on a Monoid.  The Monoid provides the value
 *  type, associative reduce function, and identity for the reducer.
 *
 *  @tparam Monoid  The monoid class that the reducer is instantiated on. It must model
 *                  the @ref reducers_monoid_concept "monoid concept".
 *
 *  @see @ref pagereducers
 */
template <class Monoid>
class reducer : public internal::reducer_content<Monoid>
{
    typedef internal::reducer_content<Monoid> base;
    using base::monoid_ptr;
    using base::leftmost_ptr;
  public:
    typedef Monoid                          monoid_type;    ///< The monoid type.
    typedef typename Monoid::value_type     value_type;     ///< The value type.
    typedef typename Monoid::view_type      view_type;      ///< The view type.

  private:
    typedef internal::reducer_set_get<value_type, view_type> set_get;
    
    reducer(const reducer&);                ///< Disallow copying.
    reducer& operator=(const reducer&);     ///< Disallow assignment.

  public:
  
    /** @name Constructors
     *
     *  All reducer constructors call the static `construct()` function of the monoid class to
     *  construct the reducer's monoid and leftmost view. 
     *
     *  The reducer constructor arguments are simply passed through to the construct() function.
     *  Thus, the constructor parameters accepted by a particular reducer class are determined
     *  by its monoid class.
     */
    //@{

    /** 0 – 6 const reference parameters.
     */
    //@{
    
    reducer()
    {
        monoid_type::construct(monoid_ptr(), leftmost_ptr());
    }

    template <typename T1>
    reducer(const T1& x1)
    {
        monoid_type::construct(monoid_ptr(), leftmost_ptr(), x1);
    }

    template <typename T1, typename T2>
    reducer(const T1& x1, const T2& x2)
    {
        monoid_type::construct(monoid_ptr(), leftmost_ptr(), x1, x2);
    }

    template <typename T1, typename T2, typename T3>
    reducer(const T1& x1, const T2& x2, const T3& x3)
    {
        monoid_type::construct(monoid_ptr(), leftmost_ptr(), x1, x2, x3);
    }

    template <typename T1, typename T2, typename T3, typename T4>
    reducer(const T1& x1, const T2& x2, const T3& x3, const T4& x4)
    {
        monoid_type::construct(monoid_ptr(), leftmost_ptr(), x1, x2, x3, x4);
    }

    template <typename T1, typename T2, typename T3, typename T4, typename T5>
    reducer(const T1& x1, const T2& x2, const T3& x3, const T4& x4, const T5& x5)
    {
        monoid_type::construct(monoid_ptr(), leftmost_ptr(), x1, x2, x3, x4, x5);
    }

    template <typename T1, typename T2, typename T3, typename T4, typename T5, typename T6>
    reducer(const T1& x1, const T2& x2, const T3& x3, const T4& x4, const T5& x5, const T6& x6)
    {
        monoid_type::construct(monoid_ptr(), leftmost_ptr(), x1, x2, x3, x4, x5, x6);
    }
    
    //@}
    
    /** 1 non-const reference parameter.
     */
    //@{

    template <typename T1>
    reducer(T1& x1)
    {
        monoid_type::construct(monoid_ptr(), leftmost_ptr(), x1);
    }
    
    //@}

    /** Destructor.
     */
    __CILKRTS_STRAND_STALE(~reducer())
    {
        leftmost_ptr()->~view_type();
        monoid_ptr()->~monoid_type();
    }

    //@{
    /** Get the monoid.
     *
     *  @return A reference to the monoid object belonging to this reducer.
     */
    Monoid& monoid() { return *monoid_ptr(); }
    
    const Monoid& monoid() const 
    { return const_cast<reducer*>(this)->monoid(); }
    //@}

    //@{
    /** Access the current view.
     *
     *  Return a reference to the instance of the reducer’s view that was 
     *  created for the current strand of a parallel computation (and create
     *  it if it doesn’t already exist).
     */
          view_type& view()       { return base::view(); }
    const view_type& view() const { return base::view(); }
    //@}
        

    /** @name Dereference the reducer to get the view.
     *
     *  “Dereferencing” a reducer yields the view for the current strand. The
     *  view, in turn, acts as a proxy for its contained value, exposing only
     *  those operations which are consistent with the reducer’s monoid. Thus,
     *  all modifications of the reducer’s accumulator variable are written as
     *
     *      *reducer OP ...
     *
     *  or
     *
     *      reducer->func(...)
     *
     *  (The permitted operations on a reducer’s accumulator are listed in the
     *  documentation for that particular kind of reducer.)
     *
     *  @note   `*r` is a synonym for `r.view()`. Recommended style is to use
     *          `*r` (or `r->`) in the common case where code is simply
     *          updating the accumulator variable wrapped in the view, and to
     *          use `r.view()` in the unusual case where it is desirable to
     *          call attention to the view itself.
     */
    //@{
    
    //@{
    /** Dereference operator.
     *
     *  @return A reference to the per-strand view instance.
     */
    view_type&       operator*()       { return view(); }
    view_type const& operator*() const { return view(); }
    //@}

    //@{
    /** Pointer operator.
     *
     *  @return A pointer to the per-strand view instance.
     */
    view_type*       operator->()       { return &view(); }
    view_type const* operator->() const { return &view(); }
    //@}
    
    //@{
    /** Deprecated view access.
     *
     *  `r()` is a synonym for `*r` which was used with early versions of Cilk
     *  reducers. `*r` is now the preferred usage.
     *
     *  @deprecated Use operator*() instead of operator()().
     *
     *  @return A reference to the per-strand view instance.
     */
    view_type&       operator()()       { return view(); }
    view_type const& operator()() const { return view(); }
    //@}
    
    //@}
    
    /** @name Set and get the value.
     *
     *  These functions are used to set an initial value for the reducer before
     *  starting the reduction, or to get the final value after the reduction
     *  is complete.
     *
     *  @note   These functions are completely different from the view
     *          operations that are made available via operator*() and
     *          operator->(), which are used to _modify_ the reducer’s value
     *          _during_ the reduction.
     *
     *  @warning    These functions _can_ be called at any time, and in 
     *              general, they will refer to the value contained in the view
     *              for the current strand. However, using them other than to
     *              set the reduction’s initial value or get its final value
     *              will almost always result in undefined behavior.
     */
    //@{

    /** Move a value into the reducer.
     *
     *  This function is used to set the initial value of the reducer’s
     *  accumulator variable by either copying or _moving_ the value of @a obj
     *  into it. Moving a value can often be performed in constant time, even
     *  for large container objects, but has the side effect of leaving the
     *  value of @a obj undefined. (See the description of the 
     *  @ref move_in_wrapper class for a discussion of moving values.) 
     *
     *  @par    Usage
     *          A move_in() call to initialize a reducer is often paired with a
     *          move_out() call to get its final value:
     *
     *              reducer<Type> xr;
     *              xr.move_in(x);
     *              … do the reduction …
     *              xr.move_out(x);
     *
     *  @par Assumptions
     *      -   You cannot assume either that this will function will copy its
     *          value or that it will move it. 
     *      -   You must assume that the value of @a obj will be undefined 
     *          after the call to move_in(). 
     *      -   You can assume that move_in() will be at least as efficient as
     *          set_value(), and you should therefore prefer move_in() unless
     *          you need the value of @a obj to be unchanged after the call.
     *          (But you should usually prefer the move-in constructor over a
     *          move_in() call — see the note below.)
     *
     *  @note   The behavior of a default constructor followed by move-in
     *          initialization:
     *
     *              reducer<Type> xr;
     *              xr.move_in(x);
     *
     *  @note   is not necessarily the same as a move-in constructor:
     *
     *      reducer<Type> xr(move_in(x));
     * 
     *  @note   In particular, when @a Type is a container type with a 
     *          non-empty allocator, the move-in constructor will create the
     *          accumulator variable with the same allocator as the input
     *          argument @a x, while the default constructor will create the
     *          accumulator variable with a default allocator. The mismatch of
     *          allocators in the latter case means that the input argument 
     *          @a x may have to be copied in linear time instead of being 
     *          moved in constant time.
     *
     *  @note   Best practice is to prefer the move-in constructor over the
     *          move-in function unless the move-in function is required for
     *          some specific reason.
     *
     *  @warning    Calling this function other than to set the initial value
     *              for a reduction will almost always result in undefined
     *              behavior.
     *
     *  @param  obj The object containing the value that will be moved into the
     *              reducer.
     *
     *  @post   The reducer contains the value that was initially in @a obj.
     *  @post   The value of @a obj is undefined.
     *
     *  @see set_value()
     */
    void move_in(value_type& obj) { set_get::move_in(view(), obj);}

    /** Move the value out of the reducer.
     *
     *  This function is used to retrieve the final value of the reducer’s
     *  accumulator variable by either copying or _moving_ the value of @a obj
     *  into it. Moving a value can often be performed in constant time, even
     *  for large container objects, but has the side effect of leaving the
     *  value of the reducer’s accumulator variable undefined. (See the
     *  description of the @ref move_in_wrapper class for a discussion of 
     *  moving values.) 
     *
     *  @par    Usage
     *          A move_in() call to initialize a reducer is often paired with a
     *          move_out() call to get its final value:
     *
     *              reducer<Type> xr;
     *              xr.move_in(x);
     *              … do the reduction …
     *              xr.move_out(x);
     *
     *  @par Assumptions
     *      -   You cannot assume either that this will function will copy its
     *          value or that it will move it. 
     *      -   You must assume that the value of the reducer’s accumulator
     *          variable will be undefined after the call to move_out().
     *      -   You can assume that move_out() will be at least as efficient as
     *          get_value(), and you should therefore prefer move_out() unless
     *          you need the accumulator variable to be preserved after the
     *          call.
     *
     *  @warning    Calling this function other than to retrieve the final 
     *              value of a reduction will almost always result in undefined
     *              behavior.
     *
     *  @param  obj The object that the value of the reducer will be moved into.
     *
     *  @post   @a obj contains the value that was initially in the reducer.
     *  @post   The value of the reducer is undefined.
     *
     *  @see get_value()
     */
    void move_out(value_type& obj) { set_get::move_out(view(), obj); }

    /** Set the value of the reducer.
     *
     *  This function sets the initial value of the reducer’s accumulator
     *  variable to the value of @a obj.
     *
     *  @note   The behavior of a default constructor followed by
     *          initialization:
     *
     *      reducer<Type> xr;
     *      xr.set_value(x);
     *
     *  @note   is not necessarily the same as a value constructor:
     *
     *      reducer<Type> xr(x);
     * 
     *  @note   In particular, when @a Type is a container type with a 
     *          non-empty allocator, the value constructor will create the
     *          accumulator variable with the same allocator as the input
     *          argument @a x, while the default constructor will create the
     *          accumulator variable with a default allocator.
     *
     *  @warning    Calling this function other than to set the initial value
     *              for a reduction will almost always result in undefined
     *              behavior.
     *
     *  @param  obj The object containing the value that will be copied into 
     *              the reducer.
     *
     *  @post   The reducer contains a copy of the value in @a obj.
     *
     *  @see move_in()
     */
    void set_value(const value_type& obj) { set_get::set_value(view(), obj); }

    /** Get the value of the reducer.
     *
     *  This function gets the final value of the reducer’s accumulator
     *  variable.
     *
     *  @warning    Calling this function other than to retrieve the final 
     *              value of a reduction will almost always result in undefined
     *              behavior.
     *
     *  @return     A reference to the value contained in the reducer.
     *
     *  @see move_out()
     */
    typename set_get::get_value_type get_value() const 
        { return set_get::get_value(view()); }
    
    //@}

    /** Implicit downcast to legacy reducer wrapper, if any.
     *
     *  @see legacy_reducer_downcast
     */
    operator typename legacy_reducer_downcast<reducer>::type& ()
    {
        typedef typename legacy_reducer_downcast<reducer>::type downcast_type;
        return *reinterpret_cast<downcast_type*>(this);
    }


    /** Implicit downcast to legacy reducer wrapper, if any.
     *
     *  @see legacy_reducer_downcast
     */
    operator const typename legacy_reducer_downcast<reducer>::type& () const
    {
        typedef typename legacy_reducer_downcast<reducer>::type downcast_type;
        return *reinterpret_cast<const downcast_type*>(this);
    }
};

#ifdef CILK_STUB
} // namespace stub
using stub::reducer;
#endif

} // end namespace cilk

#endif /* __cplusplus */

/** @page page_reducers_in_c Creating and Using Reducers in C
 *
 *  @tableofcontents
 *  
 *  The Cilk runtime supports reducers written in C as well as in C++. The basic logic is the
 *  same, but the implementation details are very different. The C++ reducer implementation uses
 *  templates heavily to create very generic components. The C reducer implementation uses
 *  macros, which are a much blunter instrument. The most immediate consequence is that the 
 *  monoid/view/reducer architecture is mostly implicit rather than explicit in C reducers.
 *  
 *  @section reducers_c_overview Overview of Using Reducers in C
 *  
 *  The basic usage pattern for C reducers is:
 *  
 *  1.  Create and initialize a reducer object.
 *  2.  Tell the Cilk runtime about the reducer.
 *  3.  Update the value contained in the reducer in a parallel computation.
 *  4.  Tell the Cilk runtime that you are done with the reducer.
 *  5.  Retrieve the value from the reducer.
 *  
 *  @subsection reducers_c_creation Creating and Initializing a C Reducer
 *  
 *  The basic pattern for creating and initializing a reducer object in C is
 *  
 *      CILK_C_DECLARE_REDUCER(value-type) reducer-name =
 *          CILK_C_INIT_REDUCER(value-type,
 *                              reduce-function,
 *                              identity-function,
 *                              destroy-function,
 *                              initial-value);
 *                              
 *  This is simply an initialized definition of a variable named _reducer-name_. The
 *  @ref CILK_C_DECLARE_REDUCER macro expands to an anonymous `struct` declaration for a reducer 
 *  object containing a view of type _value-type_, and the @ref CILK_C_INIT_REDUCER macro
 *  expands to a struct initializer.
 *  
 *  @subsection reducers_c_reduce_func Reduce Functions
 *  
 *  The reduce function for a reducer is called when a parallel execution strand terminates, to
 *  combine the values computed by the terminating strand and the strand to its left. It takes
 *  three arguments:
 *  
 *  -   `void* reducer` — the address of the reducer.
 *  -   `void* left` — the address of the value for the left strand.
 *  -   `void* right` — the address of the value for the right (terminating) strand.
 *  
 *  It must apply the reducer’s reduction operation to the `left` and `right` values, leaving
 *  the result in the `left` value. The `right` value is undefined after the reduce function
 *  call.
 *  
 *  @subsection reducers_c_identity_func Identity Functions
 *  
 *  The identity function for a reducer is called when a parallel execution strand begins, to
 *  initialize its value to the reducer’s identity value. It takes two arguments:
 *  
 *  -   `void* reducer` — the address of the reducer.
 *  -   `void* v` — the address of a freshly allocated block of memory of size
 *      `sizeof(value-type)`.
 *  
 *  It must initialize the memory pointed to by `v` so that it contains the reducer’s identity 
 *  value.
 *  
 *  @subsection reducers_c_destroy_func Destroy Functions
 *  
 *  The destroy function for a reducer is called when a parallel execution strand terminates, to
 *  do any necessary cleanup before its value is deallocated. It takes two arguments:
 *  
 *  -   `void* reducer` — the address of the reducer.
 *  -   `void* p` — the address of the value for the terminating strand.
 *  
 *  It must release any resources belonging to the value pointed to by `p`, to avoid a resource 
 *  leak when the memory containing the value is deallocated.
 *  
 *  The runtime function `__cilkrts_hyperobject_noop_destroy` can be used for the destructor 
 *  function if the reducer’s values do not need any cleanup.
 *  
 *  @subsection reducers_c_register Tell the Cilk Runtime About the Reducer
 *  
 *  Call the @ref CILK_C_REGISTER_REDUCER macro to register the reducer with the Cilk runtime:
 *  
 *      CILK_C_REGISTER_REDUCER(reducer-name);
 *  
 *  The runtime will manage reducer values for all registered reducers when parallel execution 
 *  strands begin and end.
 *  
 *  @subsection reducers_c_update Update the Value Contained in the Reducer
 *  
 *  The @ref REDUCER_VIEW macro returns a reference to the reducer’s value for the  current
 *  parallel strand:
 *  
 *      REDUCER_VIEW(reducer-name) = REDUCER_VIEW(reducer-name) OP x;
 *      
 *  C++ reducer views restrict access to the wrapped value so that it can only be modified in
 *  ways consistent with the reducer’s operation. No such protection is provided for C reducers.
 *  It is
 *  entirely the responsibility of the user to avoid modifying the value in any
 *  inappropriate way.
 *  
 *  @subsection c_reducers_unregister Tell the Cilk Runtime That You Are Done with the Reducer
 *  
 *  When the parallel computation is complete, call the @ref CILK_C_UNREGISTER_REDUCER macro to 
 *  unregister the reducer with the Cilk runtime:
 *  
 *      CILK_C_UNREGISTER_REDUCER(reducer-name);
 *  
 *  The runtime will stop managing reducer values for the reducer.
 *  
 *  @subsection c_reducers_retrieve Retrieve the Value from the Reducer
 *  
 *  When the parallel computation is complete, use the @ref REDUCER_VIEW macro to retrieve the
 *  final value computed by the reducer.
 *  
 *  @subsection reducers_c_example_custom Example — Creating and Using a Custom C Reducer
 *  
 *  The `IntList` type represents a simple list of integers.
 *  
 *      struct _intListNode {
 *          int value;
 *          _intListNode* next;
 *      } IntListNode;
 *      typedef struct { IntListNode* head; IntListNode* tail; } IntList;
 *      
 *      // Initialize a list to be empty
 *      void IntList_init(IntList* list) { list->head = list->tail = 0; }
 *      
 *      // Append an integer to the list
 *      void IntList_append(IntList* list, int x) 
 *      { 
 *          IntListNode* node = (IntListNode*) malloc(sizeof(IntListNode));
 *          if (list->tail) list->tail->next = node; else list->head = node;
 *          list->tail = node;
 *      }
 *      
 *      // Append the right list to the left list, and leave the right list empty
 *      void IntList_concat(IntList* left, IntList* right)
 *      {
 *          if (left->head) {
 *              left->tail->next = right->head;
 *              if (right->tail) left->tail = right->tail;
 *          }
 *          else {
 *              *left = *right;
 *          }
 *          IntList_init(*right);
 *      }
 *      
 *  This code creates a reducer that supports creating an `IntList` by appending values to it.
 *  
 *      void identity_IntList(void* reducer, void* list)
 *      {
 *          IntList_init((IntList*)list);
 *      }
 *      
 *      void reduce_IntList(void* reducer, void* left, void* right)
 *      {
 *          IntList_concat((IntList*)left, (IntList*)right);
 *      }
 *          
 *      CILK_C_DECLARE_REDUCER(IntList) my_list_int_reducer =
 *          CILK_C_INIT_REDUCER(IntList,
 *                              reduce_int_list,
 *                              identity_int_list,
 *                              __cilkrts_hyperobject_noop_destroy);
 *                              // Initial value omitted //
 *      ListInt_init(&REDUCER_VIEW(my_int_list_reducer));
 *
 *      CILK_C_REGISTER_REDUCER(my_int_list_reducer);
 *      cilk_for (int i = 0; i != n; ++i) {
 *          IntList_append(&REDUCER_VIEW(my_int_list_reducer), a[i]);
 *      }
 *      CILK_C_UNREGISTER_REDUCER(my_int_list_reducer);
 *      
 *      IntList result = REDUCER_VIEW(my_int_list_reducer);
 *
 *  @section reducers_c_predefined Predefined C Reducers
 *
 *  Some of the predefined reducer classes in the Cilk library come with a set of predefined
 *  macros to provide the same capabilities in C. In general, two macros are provided for each
 *  predefined reducer family:
 *
 *  -   `CILK_C_REDUCER_operation(reducer-name, type-name, initial-value)` — Declares a
 *      reducer object named _reducer-name_ with initial value _initial-value_ to perform
 *      a reduction using the _operation_ on values of the type specified by _type-name_.
 *      This is the equivalent of the general code described in @ref reducers_c_creation :
 *
 *          CILK_C_DECLARE_REDUCER(type) reducer-name =
 *              CILK_C_INIT_REDUCER(type, ..., initial-value);
 *
 *      where _type_ is the C type corresponding to _type_name_. See @ref reducers_c_type_names
 *      below for the _type-names_ that you can use.
 *
 *  -   `CILK_C_REDUCER_operation_TYPE(type-name)` — Expands to the `typedef` name for the type
 *      of the reducer object declared by
 *      `CILK_C_REDUCER_operation(reducer-name, type-name, initial-value)`.
 *
 *  See @ref reducers_c_example_predefined.
 *
 *  The predefined C reducers are:
 *
 *  |   Operation       |   Name        |   Documentation               |
 *  |-------------------|---------------|-------------------------------|
 *  |   addition        |   `OPADD`     |   @ref ReducersAdd            |
 *  |   bitwise and     |   `OPAND`     |   @ref ReducersAnd            |
 *  |   bitwise or      |   `OPOR`      |   @ref ReducersOr             |
 *  |   bitwise xor     |   `OPXOR`     |   @ref ReducersXor            |
 *  |   multiplication  |   `OPMUL`     |   @ref ReducersMul            |
 *  |   minimum         |   `MIN`       |   @ref ReducersMinMax         |
 *  |   minimum & index |   `MIN_INDEX` |   @ref ReducersMinMax         |
 *  |   maximum         |   `MIN`       |   @ref ReducersMinMax         |
 *  |   maximum & index |   `MIN_INDEX` |   @ref ReducersMinMax         |
 *      
 *  @subsection reducers_c_type_names Numeric Type Names
 *  
 *  The type and function names created by the C reducer definition macros incorporate both the
 *  reducer kind (`opadd`, `opxor`, etc.) and the value type of the reducer (`int`, `double`, 
 *  etc.). The value type is represented by a _numeric type name_ string. The types supported 
 *  in C reducers, and their corresponding numeric type names, are given in the following table:
 *  
 *  |   Type                |   Numeric Type Name           |
 *  |-----------------------|-------------------------------|
 *  |  `char`               |  `char`                       |
 *  |  `unsigned char`      |  `uchar`                      |
 *  |  `signed char`        |  `schar`                      |
 *  |  `wchar_t`            |  `wchar_t`                    |
 *  |  `short`              |  `short`                      |
 *  |  `unsigned short`     |  `ushort`                     |
 *  |  `int`                |  `int`                        |
 *  |  `unsigned int`       |  `uint`                       |
 *  |  `unsigned int`       |  `unsigned` (alternate name)  |
 *  |  `long`               |  `long`                       |
 *  |  `unsigned long`      |  `ulong`                      |
 *  |  `long long`          |  `longlong`                   |
 *  |  `unsigned long long` |  `ulonglong`                  |
 *  |  `float`              |  `float`                      |
 *  |  `double`             |  `double`                     |
 *  |  `long double`        |  `longdouble`                 |
 *  
 *  @subsection reducers_c_example_predefined Example — Using a Predefined C Reducer
 *
 *  To compute the sum of all the values in an array of `unsigned int`:
 *
 *      CILK_C_REDUCER_OPADD(sum, uint, 0);
 *      CILK_C_REGISTER_REDUCER(sum);
 *      cilk_for(int i = 0; i != n; ++i) {
 *          REDUCER_VIEW(sum) += a[i];
 *      }
 *      CILK_C_UNREGISTER_REDUCER(sum);
 *      printf("The sum is %u\n", REDUCER_VIEW(sum));
 */

 
 /** @name C language reducer macros
 *
 *  These macros are used to declare and work with reducers in C code.
 *
 *  @see @ref page_reducers_in_c
 */
 //@{

/// @cond internal

/** @name Compound identifier macros.
 *
 *  These macros are used to construct an identifier by concatenating two or three identifiers.
 */
//@{

/** Expand to an identifier formed by concatenating two identifiers.
 */
#define __CILKRTS_MKIDENT(a,b) __CILKRTS_MKIDENT_IMP(a,b,)

/** Expand to an identifier formed by concatenating three identifiers.
 */
#define __CILKRTS_MKIDENT3(a,b,c) __CILKRTS_MKIDENT_IMP(a,b,c)

/** Helper macro to do the concatenation.
 */
#define __CILKRTS_MKIDENT_IMP(a,b,c) a ## b ## c

//@}

/** Compiler-specific keyword for the “type of” operator.
 */
#if defined(__GNUC__) && !defined(__INTEL_COMPILER)
# define _Typeof __typeof__
#endif

/** @name Predefined reducer function declaration macros.
 *
 *  These macros are used to create the function headers for the identity, reduction,
 *  and destructor functions for a builtin reducer family. The macro can be followed by
 *  a semicolon to create a declaration, or by a brace-enclosed body to create a definition.
 */
//@{

/** Create an identity function header.
 *
 *  @note   The name of the function’s value pointer parameter will always be `v`.
 *
 *  @param name The reducer family name.
 *  @param tn   The type name.
 */
#define __CILKRTS_DECLARE_REDUCER_IDENTITY(name,tn)  CILK_EXPORT         \
    void __CILKRTS_MKIDENT3(name,_identity_,tn)(void* key, void* v)

/** Create a reduction function header.
 *
 *  @param name The reducer family name.
 *  @param tn   The type name.
 *  @param l    The name to use for the function’s left value pointer parameter.
 *  @param r    The name to use for the function’s right value pointer parameter.
 */
#define __CILKRTS_DECLARE_REDUCER_REDUCE(name,tn,l,r) CILK_EXPORT        \
    void __CILKRTS_MKIDENT3(name,_reduce_,tn)(void* key, void* l, void* r)

/** Create a destructor function header.
 *
 *  @param name The reducer family name.
 *  @param tn   The type name.
 *  @param p    The name to use for the function’s value pointer parameter.
 */
#define __CILKRTS_DECLARE_REDUCER_DESTROY(name,tn,p) CILK_EXPORT         \
    void __CILKRTS_MKIDENT3(name,_destroy_,tn)(void* key, void* p)

//@}

/// @endcond


/***************************************************************************
 *              Real implementation
 ***************************************************************************/

/** Declaration of a C reducer structure type.
 *
 *  This macro expands into an anonymous structure declaration for a C reducer structure
 *  which contains a @a Type value. For example:
 *
 *      CILK_C_DECLARE_REDUCER(int) my_add_int_reducer =
 *          CILK_C_INIT_REDUCER(int, …);
 *
 *  @param Type The type of the value contained in the reducer object.
 *
 *  @see @ref reducers_c_creation
 */
#define CILK_C_DECLARE_REDUCER(Type) struct {                      \
        __cilkrts_hyperobject_base   __cilkrts_hyperbase;          \
        __CILKRTS_CACHE_ALIGN Type   value;                        \
    }

/** Initializer for a C reducer structure.
 *
 *  This macro expands into a brace-enclosed structure initializer for a C reducer structure
 *  that was declared with `CILK_C_DECLARE_REDUCER(Type)`. For example:
 *
 *      CILK_C_DECLARE_REDUCER(int) my_add_int_reducer =
 *          CILK_C_INIT_REDUCER(int, 
 *                              add_int_reduce, 
 *                              add_int_identity, 
 *                              __cilkrts_hyperobject_noop_destroy,
 *                              0);
 *
 *  @param Type     The type of the value contained in the reducer object. Must be the same as
 *                  the @a Type argument of the CILK_C_DECLARE_REDUCER macro call that created
 *                  the reducer.
 *  @param Reduce   The address of the @ref reducers_c_reduce_func "reduce function" for the
 *                  reducer.
 *  @param Identity The address of the @ref reducers_c_identity_func "identity function" for
 *                  the reducer.
 *  @param Destroy  The address of the @ref reducers_c_destroy_func "destroy function" for the
 *                  reducer.
 *  @param ...      The initial value for the reducer. (A single expression if @a Type is a
 *                  scalar type; a list of values if @a Type is a struct or array type.)
 *
 *  @see @ref reducers_c_creation
 */

#define CILK_C_INIT_REDUCER(Type, Reduce, Identity, Destroy, ...)       \
    {   {   {   Reduce                                                  \
            ,   Identity                                                \
            ,   Destroy                                                 \
            ,   __cilkrts_hyperobject_alloc                             \
            ,   __cilkrts_hyperobject_dealloc                           \
            }                                                           \
        ,   0                                                           \
        ,   __CILKRTS_CACHE_LINE__                                      \
        ,   sizeof(Type)                                                \
        }                                                               \
    ,   __VA_ARGS__                                                     \
    }

/** Register a reducer with the Cilk runtime.
 *
 *  The runtime will manage reducer values for all registered reducers when parallel execution 
 *  strands begin and end. For example:
 *
 *      CILK_C_REGISTER_REDUCER(my_add_int_reducer);
 *      cilk_for (int i = 0; i != n; ++i) {
 *          …
 *      }
 *
 *  @param Expr The reducer to be registered.
 *
 *  @see @ref page_reducers_in_c
 */
#define CILK_C_REGISTER_REDUCER(Expr) \
    __cilkrts_hyper_create(&(Expr).__cilkrts_hyperbase)

/** Unregister a reducer with the Cilk runtime.
 *
 *  The runtime will stop managing reducer values for a reducer after it is unregistered. For
 *  example:
 *
 *      cilk_for (int i = 0; i != n; ++i) {
 *          …
 *      }
 *      CILK_C_UNREGISTER_REDUCER(my_add_int_reducer);
 *
 *  @param Expr The reducer to be unregistered.
 *
 *  @see @ref page_reducers_in_c
 */
#define CILK_C_UNREGISTER_REDUCER(Expr) \
    __cilkrts_hyper_destroy(&(Expr).__cilkrts_hyperbase)

/** Get the current view for a reducer.
 *
 *  The `REDUCER_VIEW(reducer-name)` returns a reference to the reducer’s value for the 
 *  current parallel strand. This can be used to initialize thevalue of the  reducer before it
 *  is used, to modify the value of the reducer on the current parallel strand, or to retrieve
 *  the final value of the reducer at the end of the parallel computation.
 *
 *      REDUCER_VIEW(my_add_int_reducer) = REDUCER_VIEW(my_add_int_reducer) + x;
 *
 *  @note   C++ reducer views restrict access to the wrapped value so that it can only be
 *  modified in ways consistent with the reducer’s operation. No such protection is provided 
 *  for C reducers. It is entirely the responsibility of the user to refrain from modifying the
 *  value in any inappropriate way.
 *
 *  @param Expr The reducer whose value is to be returned.
 *
 *  @see @ref page_reducers_in_c
 */
#define REDUCER_VIEW(Expr) (*(_Typeof((Expr).value)*)               \
    __cilkrts_hyper_lookup(&(Expr).__cilkrts_hyperbase))

//@} C language reducer macros

#endif // CILK_REDUCER_H_INCLUDED