CnC
debug.h
1 /* *******************************************************************************
2  * Copyright (c) 2007-2014, Intel Corporation
3  *
4  * Redistribution and use in source and binary forms, with or without
5  * modification, are permitted provided that the following conditions are met:
6  *
7  * * Redistributions of source code must retain the above copyright notice,
8  * this list of conditions and the following disclaimer.
9  * * Redistributions in binary form must reproduce the above copyright
10  * notice, this list of conditions and the following disclaimer in the
11  * documentation and/or other materials provided with the distribution.
12  * * Neither the name of Intel Corporation nor the names of its contributors
13  * may be used to endorse or promote products derived from this software
14  * without specific prior written permission.
15  *
16  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
19  * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
20  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
21  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
22  * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
23  * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
24  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
25  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26  ********************************************************************************/
27 
28 /*
29  CnC debug interface.
30 */
31 
32 #ifndef _CnC_DEBUG_H_
33 #define _CnC_DEBUG_H_
34 
35 #include <cnc/internal/cnc_api.h>
36 #include <cnc/internal/chronometer.h>
37 #include <cnc/internal/step_launcher.h>
38 
39 namespace CnC {
40 
41  class graph;
42  template< class T > class context;
43  template< typename Tag, typename Tuner > class tag_collection;
44  template< typename Tag, typename Item, typename Tuner > class item_collection;
45  template< typename UserStep, typename Tuner > class step_collection;
46 
47 
48  /// \brief Debugging interface providing tracing and timing capabilities
49  ///
50  /// \#include <cnc/debug.h>
51  ///
52  /// For a meaningful tracing the runtime requires a function cnc_format for
53  /// every non-standard item and tag type. The expected signature is:
54  /// \code std::ostream & cnc_format( std::ostream & os, const your_type & p ) \endcode
55  /// Make sure it is defined in the corresponding namespace.
56  struct debug {
57  /// \brief sets the number of threads used by the application
58  ///
59  /// Overwrites environment variable CNC_NUM_THREADS.
60  /// To be effective, it must be called prior to context creation.
61  static void CNC_API set_num_threads( int n );
62 
63  /// \brief enable tracing of a given tag collection at a given level
64  ///
65  /// To be used in a safe environment only (no steps in flight)
66  /// \param tc the tag collection to be traced
67  /// \param level trace level
68  template< typename Tag, typename Tuner >
69  static void trace( tag_collection< Tag, Tuner > & tc, int level = 1 )
70  { tc.m_tagCollection.set_tracing( level ); }
71 
72  /// \brief enable tracing of a given item collection at a given level
73  ///
74  /// To be used in a safe environment only (no steps in flight).
75  /// \param ic the item collection to be traced
76  /// \param level trace level
77  template< typename Tag, typename Item, typename HC >
78  static void trace( item_collection< Tag, Item, HC > & ic, int level = 1 )
79  { ic.m_itemCollection.set_tracing( level ); }
80 
81  /// \brief enable tracing of a given step-collection at a given level (off=0)
82  ///
83  /// To be used in a safe environment only (no steps in flight)
84  /// \param sc the step-collection to be traced
85  /// \param level trace level
86  template< typename UserStep, typename Tuner >
87  static void trace( step_collection< UserStep, Tuner > & sc, int level = 1 )
88  {
89  sc.set_tracing( level );
90  CNC_ASSERT( sc.trace_level() == level );
91  }
92 
93  /// \brief enable tracing of graph internals (not including its I/O collections)
94  ///
95  /// To be used in a safe environment only (no steps in flight)
96  /// names of collections are unavailable unless tracing them was enabled explicitly.
97  /// \param g the graph to be traced
98  /// \param level trace level
99  static void CNC_API trace( ::CnC::graph & g, int level = 1 );
100 
101  /// \brief enable tracing of everything in given context (off=0)
102  ///
103  /// To be used in a safe environment only (no steps in flight)
104  /// \param c the context to be traced
105  /// \param level trace level
106  template< class Derived >
107  static void trace_all( ::CnC::context< Derived > & c, int level = 1 )
108  { c.set_tracing( level ); }
109 
110  /// \brief initalize timer
111  /// \param cycle if true, use cycle counter only
112  /// Cycle counters might overflow: TSC results are incorrect if the measured time-interval
113  /// is larger than a full turn-around.
114  static void init_timer( bool cycle = false )
115  { Internal::chronometer::init( cycle ); }
116 
117  /// \brief save collected time log to a specified file
118  /// \param name the file to write the time log, pass "-" for printing to stdout
119  static void finalize_timer( const char * name )
120  { Internal::chronometer::save_log( name ? name : "-" ); }
121 
122  /// \brief enable timing of a given step
123  ///
124  /// To be used in a safe environment only (no steps in flight)
125  /// \param sc the step-collection to be timed
126  template< typename UserStep, typename Tuner >
128  { sc.set_timing(); }
129 
130  /// \brief enable collection scheduler statistics per context
131  ///
132  /// Statistics will be print upon destructino of a context.
133  /// \param c the context to be examined
134  template< class Derived >
136  { c.init_scheduler_statistics(); }
137  };
138 
139 } // namespace cnc
140 
141 #endif // _CnC_DEBUG_H_
Debugging interface providing tracing and timing capabilities.
Definition: debug.h:56
static void collect_scheduler_statistics(::CnC::context< Derived > &c)
enable collection scheduler statistics per context
Definition: debug.h:135
static void init_timer(bool cycle=false)
initalize timer
Definition: debug.h:114
CnC API.
Definition: cnc.h:49
A tag collection is a set of tags of the same type. It is used to prescribe steps. By default, tags are not stored.
Definition: cnc.h:56
Base class for defining and using CnC (sub-)graphs.
Definition: cnc.h:429
CnC context bringing together collections (for steps, items and tags).
Definition: cnc.h:54
static void trace(item_collection< Tag, Item, HC > &ic, int level=1)
enable tracing of a given item collection at a given level
Definition: debug.h:78
static void CNC_API set_num_threads(int n)
sets the number of threads used by the application
static void trace(step_collection< UserStep, Tuner > &sc, int level=1)
enable tracing of a given step-collection at a given level (off=0)
Definition: debug.h:87
A step collection is logical set of step instances.
Definition: cnc.h:70
static void trace_all(::CnC::context< Derived > &c, int level=1)
enable tracing of everything in given context (off=0)
Definition: debug.h:107
An item collection is a mapping from tags to items.
Definition: cnc.h:57
static void time(step_collection< UserStep, Tuner > &sc)
enable timing of a given step
Definition: debug.h:127
static void finalize_timer(const char *name)
save collected time log to a specified file
Definition: debug.h:119
static void trace(tag_collection< Tag, Tuner > &tc, int level=1)
enable tracing of a given tag collection at a given level
Definition: debug.h:69