debug.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_DEBUG_H_
#define _CnC_DEBUG_H_

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

namespace CnC {

    /// \brief Debugging interface providing tracing and timing capabilities
    ///
    /// \#include <cnc/debug.h>
    ///
    /// For a meaningful tracing the runtime requires a function cnc_format for
    /// every non-standard item and tag type. The expected signature is:
    /// \code
    /// std::ostream & cnc_format( std::ostream & os, const your_type & p )
    /// \endcode
    /// Make sure it is defined in the corresponding namespace.
    struct debug {
        /// \brief sets the number of threads used by the application
        ///
        /// Overwrites environment variable CNC_NUM_THREADS.
        /// To be effective, it must be called prior to context creation.
        static void CNC_API set_num_threads( int n );

        /// \brief enable tracing of a given tag collection at a given level
        ///
        /// To be used in a safe environment only (no steps in flight)
        /// \param tc    the tag collection to be traced
        /// \param name  the name by which the tag collection should be identified in the trace
        /// \param level trace level
        template< typename Tag, typename Range, typename HC >
        static void trace( tag_collection< Tag, Range, HC > & tc, const char * name, int level = 1 )
        { tc.m_tagCollection.set_tracing( name, level ); }

        /// \brief enable tracing of a given item collection at a given level
        ///
        /// To be used in a safe environment only (no steps in flight).
        /// \param ic    the item collection to be traced
        /// \param name  the name by which the item collection should be identified in the trace
        /// \param level trace level
        template< typename Tag, typename Item, typename HC >
        static void trace( item_collection< Tag, Item, HC > & ic, const char * name, int level = 1 )
        { ic.m_itemCollection.set_tracing( name, level ); }

        /// \brief enable tracing of everything in given context
        ///
        /// To be used in a safe environment only (no steps in flight)
        /// names of collections are unavailable unless tracing them was enabled explicitly.
        /// \param c     the context to be traced
        /// \param name  the name by which the context should be identified in the trace
        /// \param level trace level
        template< class Derived >
        static void trace_all( ::CnC::context< Derived > & c, const char * name, int level = 1 )
        { c.set_tracing( name, level ); }

        /// \brief enable tracing of a given step at a given level
        ///
        /// To be used in a safe environment only (no steps in flight)
        /// \param step  the step to be traced
        /// \param name  the name by which the step should be identified in the trace
        /// \param level trace level
        template< typename Step >
        static void trace( Step step, const char * name, int level = 1 )
        { Internal::step_tracer< Step >::s_traceName = name; Internal::step_tracer< Step >::s_traceLevel = level; }
        
        /// \brief initalize timer
        /// \param cycle if true, use cycle counter only
        /// Cycle counters might overflow: TSC results are incorrect if the measured time-interval
        /// is larger than a full turn-around.
        static void init_timer( bool cycle = false )
        { Internal::chronometer::init( cycle ); }

        /// \brief save collected time log to a specified file
        /// \param name  the file to write the time log, pass "-" for printing to stdout
        static void finalize_timer( const char * name )
        { Internal::chronometer::save_log( name ? name : "-" ); }

        /// \brief enable timing of a given step
        ///
        /// To be used in a safe environment only (no steps in flight)
        /// \param step  the step to be timed
        /// \param name  the name by which the step should be identified in the time log
        template< typename Step >
        static void time( Step step, const char * name )
        { Internal::step_timer< Step >::s_timingName = name; Internal::step_timer< Step >::s_timing = true; }

        /// \brief enable collection scheduler statistics per context
        ///
        /// Statistics will be print upon destructino of a context.
        /// \param c     the context to be examined
        template< class Derived >
        static void collect_scheduler_statistics( ::CnC::context< Derived > & c )
        { c.init_scheduler_statistics(); }
    };

} // namespace cnc

#endif // _CnC_DEBUG_H_