CnC
 All Classes Namespaces Functions Variables Typedefs Enumerator Friends Groups Pages
debug.h
1 //********************************************************************************
2 // Copyright (c) 2007-2013 Intel Corporation. All Rights Reserved. **
3 // **
4 // The source code contained or described herein and all documents related to **
5 // the source code ("Material") are owned by Intel Corporation or its suppliers **
6 // or licensors. Title to the Material remains with Intel Corporation or its **
7 // suppliers and licensors. The Material contains trade secrets and proprietary **
8 // and confidential information of Intel or its suppliers and licensors. The **
9 // Material is protected by worldwide copyright and trade secret laws and **
10 // treaty provisions. No part of the Material may be used, copied, reproduced, **
11 // modified, published, uploaded, posted, transmitted, distributed, or **
12 // disclosed in any way without Intel's prior express written permission. **
13 // **
14 // No license under any patent, copyright, trade secret or other intellectual **
15 // property right is granted to or conferred upon you by disclosure or delivery **
16 // of the Materials, either expressly, by implication, inducement, estoppel or **
17 // otherwise. Any license under such intellectual property rights must be **
18 // express and approved by Intel in writing. **
19 //********************************************************************************
20 
21 #ifndef _CnC_DEBUG_H_
22 #define _CnC_DEBUG_H_
23 
24 #include <cnc/internal/cnc_api.h>
25 #include <cnc/internal/chronometer.h>
26 #include <cnc/internal/step_launcher.h>
27 
28 namespace CnC {
29 
30  template< class T > class context;
31  template< typename Tag, typename Tuner > class tag_collection;
32  template< typename Tag, typename Item, typename Tuner > class item_collection;
33  template< typename UserStep, typename Tuner > class step_collection;
34 
35 
36  /// \brief Debugging interface providing tracing and timing capabilities
37  ///
38  /// \#include <cnc/debug.h>
39  ///
40  /// For a meaningful tracing the runtime requires a function cnc_format for
41  /// every non-standard item and tag type. The expected signature is:
42  /// \code
43  /// std::ostream & cnc_format( std::ostream & os, const your_type & p )
44  /// \endcode
45  /// Make sure it is defined in the corresponding namespace.
46  struct debug {
47  /// \brief sets the number of threads used by the application
48  ///
49  /// Overwrites environment variable CNC_NUM_THREADS.
50  /// To be effective, it must be called prior to context creation.
51  static void CNC_API set_num_threads( int n );
52 
53  /// \brief enable tracing of a given tag collection at a given level
54  ///
55  /// To be used in a safe environment only (no steps in flight)
56  /// \param tc the tag collection to be traced
57  /// \param level trace level
58  template< typename Tag, typename Tuner >
59  static void trace( tag_collection< Tag, Tuner > & tc, int level = 1 )
60  { tc.m_tagCollection.set_tracing( level ); }
61 
62  /// \brief enable tracing of a given item collection at a given level
63  ///
64  /// To be used in a safe environment only (no steps in flight).
65  /// \param ic the item collection to be traced
66  /// \param level trace level
67  template< typename Tag, typename Item, typename HC >
68  static void trace( item_collection< Tag, Item, HC > & ic, int level = 1 )
69  { ic.m_itemCollection.set_tracing( level ); }
70 
71  /// \brief enable tracing of a given step-collection at a given level (off=0)
72  ///
73  /// To be used in a safe environment only (no steps in flight)
74  /// \param sc the step-collection to be traced
75  /// \param level trace level
76  template< typename UserStep, typename Tuner >
77  static void trace( step_collection< UserStep, Tuner > & sc, int level = 1 )
78  {
79  sc.set_tracing( level );
80  CNC_ASSERT( sc.trace_level() == level );
81  }
82 
83  /// \brief enable tracing of everything in given context (off=0)
84  ///
85  /// To be used in a safe environment only (no steps in flight)
86  /// names of collections are unavailable unless tracing them was enabled explicitly.
87  /// \param c the context to be traced
88  /// \param level trace level
89  template< class Derived >
90  static void trace_all( ::CnC::context< Derived > & c, int level = 1 )
91  { c.set_tracing( level ); }
92 
93  /// \brief initalize timer
94  /// \param cycle if true, use cycle counter only
95  /// Cycle counters might overflow: TSC results are incorrect if the measured time-interval
96  /// is larger than a full turn-around.
97  static void init_timer( bool cycle = false )
98  { Internal::chronometer::init( cycle ); }
99 
100  /// \brief save collected time log to a specified file
101  /// \param name the file to write the time log, pass "-" for printing to stdout
102  static void finalize_timer( const char * name )
103  { Internal::chronometer::save_log( name ? name : "-" ); }
104 
105  /// \brief enable timing of a given step
106  ///
107  /// To be used in a safe environment only (no steps in flight)
108  /// \param sc the step-collection to be timed
109  template< typename UserStep, typename Tuner >
111  { sc.set_timing(); }
112 
113  /// \brief enable collection scheduler statistics per context
114  ///
115  /// Statistics will be print upon destructino of a context.
116  /// \param c the context to be examined
117  template< class Derived >
119  { c.init_scheduler_statistics(); }
120  };
121 
122 } // namespace cnc
123 
124 #endif // _CnC_DEBUG_H_