default_tuner.h

//********************************************************************************
// Copyright 2007-2010 Intel Corporation All Rights Reserved.                   **
//                                                                              **
// The source code contained or described herein and all documents related to   **
// the source code ("Material") are owned by Intel Corporation or its suppliers **
// or licensors. Title to the Material remains with Intel Corporation or its    **
// suppliers and licensors. The Material contains trade secrets and proprietary **
// and confidential information of Intel or its suppliers and licensors. The    **
// Material is protected by worldwide copyright and trade secret laws and       **
// treaty provisions. No part of the Material may be used, copied, reproduced,  **
// modified, published, uploaded, posted, transmitted, distributed, or          **
// disclosed in any way without Intel's prior express written permission.       **
//                                                                              **
// No license under any patent, copyright, trade secret or other intellectual   **
// property right is granted to or conferred upon you by disclosure or delivery **
// of the Materials, either expressly, by implication, inducement, estoppel or  **
// otherwise. Any license under such intellectual property rights must be       **
// express and approved by Intel in writing.                                    **
//********************************************************************************


#ifndef CNC_DEFAULT_TUNER_H_ALREADY_INCLUDED
#define CNC_DEFAULT_TUNER_H_ALREADY_INCLUDED

#include <cnc/internal/cnc_api.h>
#include <cnc/default_partitioner.h>
#include <cnc/internal/step_delayer.h>

namespace CnC {

    template< class T > class context;
    namespace Internal {
        template< class Tag, class Range, class StepColl, class RangeStepI, class TIR, bool deps > struct range_step;
    }

    enum {
        PASS_ON_LOCAL = -1,       ///< let tuner::pass_on return PASS_ON_NO if the step should be executed locally
        PASS_ON_ROUND_ROBIN = -2  ///< let tuner::pass_on return PASS_ON_ROUND_ROBIN to let the scheduler distribute it in a round-robin fashion
    };

    /// \brief Default (NOP) implementations of the tuner interface.
    ///
    /// Also defines the interface a user-provided tuner must satisfy.
    /// Derive your tuner from this class if you do not want to define the entire interface.
    ///
    /// \#include <cnc/default_tuner.h>
    template< typename Tag, typename Arg, bool check_deps = true, typename Partitioner = default_partitioner<> >
    struct /*CNC_API*/ default_tuner
    {
        /// \brief Allows defnintion of priorites to individual steps (which are identified by the tag).
        /// \return the default implementation always return 1.
        /// \param tag the tag which identifies the step to be executed
        /// \param arg the argument as passed to context< Derived >::prescribed (usually the context)
        int priority( const Tag & /*tag*/, Arg & /*arg*/ ) const
        {
            return 1;
        }

        /// \brief Allows declaration of data dependencies (to items) of
        /// given step (identified by the tag).
        ///
        /// When a step-instance is prescribed through a corresponding
        /// tag_collection::put, this method will be called.  You can
        /// declare dependencies to items by calling dC.depends(
        /// item_collection, dependent_item_tag ) for every item the step
        /// is going to 'get' in its execute mthod. The actual step
        /// execution will be delayed until all dependencies can be
        /// satisfied.  The default implementation does nothing (NOP). Your
        /// own implementation must accept dC by reference (T&).
        /// \param tag the tag which identifies the step to be executed.
        /// \param arg the argument as passed to context< Derived >::prescribed
        ///            (usually the context)
        /// \param dC  opaque object (must be by reference!) providing method depends
        ///            to declare item dependencies
        template< typename T >
        void depends( const Tag & /*tag*/, Arg & /*arg*/, T & /*dC*/ ) const
        {
        }

        /// \brief returns whether the step should be pre-scheduled 
        ///
        /// Pre-scheduling provides an alternative method for detecting
        /// data dependencies.
        ///
        /// The step instance will be run immediately when prescribed
        /// by a tag_collection::put. All items that are not yet available
        /// when accessed by the non-blocking get method will automatically
        /// be treated as dependent items. The pre-run will end at
        /// context::flush_gets() if any items are unavailable.  The step
        /// execution will be delayed until all detected dependencies can
        /// be satisfied.
        bool preschedule() const
        {
            return false;
        }
        /// \brief tell the scheduler on which process to run the step (distCnC)
        /// \return process id where the step will be executed, or PASS_ON_ROUND_ROBIN, or PASS_ON_LOCAL
        int pass_on( const Tag & /*tag*/, Arg & /*arg*/ ) const
        {
            return PASS_ON_ROUND_ROBIN;
        }

        /// \brief The type of the partitioner
        typedef Partitioner partitioner_type;

        /// \brief return a partitioner for range-based features, such as parallel_for
        /// \see default_partitioner for the expected signature of partitioners
        /// overwrite partitioner() if it doesn't come with default-constructor or
        /// if the default constructor is insufficient.
        partitioner_type partitioner() const
        {
            return partitioner_type();
        }

        /// true if steps launched through ranges consume items or need global locking, false otherwise.
        /// Avoiding checks for dependencies and global locks saves overhead and will perform better (e.g. for parallel_for).
        /// Safe execution (with checks) is the default (check_deps template argument).
        static const bool check_deps_in_ranges = check_deps;
    };


} // end namespace CnC


#endif //CNC_DEFAULT_TUNER_H_ALREADY_INCLUDED