This file is indexed.

/usr/include/trilinos/Teuchos_TimeMonitor.hpp is in libtrilinos-teuchos-dev 12.12.1-5.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
// @HEADER
// ***********************************************************************
//
//                    Teuchos: Common Tools Package
//                 Copyright (2004) Sandia Corporation
//
// Under terms of Contract DE-AC04-94AL85000, there is a non-exclusive
// license for use of this work by or on behalf of the U.S. Government.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are
// met:
//
// 1. Redistributions of source code must retain the above copyright
// notice, this list of conditions and the following disclaimer.
//
// 2. 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.
//
// 3. Neither the name of the Corporation nor the names of the
// contributors may be used to endorse or promote products derived from
// this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "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 SANDIA CORPORATION OR THE
// 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.
//
// Questions? Contact Michael A. Heroux (maherou@sandia.gov)
//
// ***********************************************************************
// @HEADER

#ifndef TEUCHOS_TIMEMONITOR_HPP
#define TEUCHOS_TIMEMONITOR_HPP


/*! \file Teuchos_TimeMonitor.hpp
 *
 * \brief Scope protection wrapper for Teuchos::Time, with timer reporting functionality.
 *
 * An instance of the Teuchos::TimeMonitor class wraps a nonconst
 * reference to a Teuchos::Time timer object.  TimeMonitor's
 * constructor starts the timer, and its destructor stops the timer.
 * This ensures scope safety of timers, so that no matter how a scope
 * is exited (whether the normal way or when an exception is thrown),
 * a timer started in the scope is stopped when the scope is left.
 *
 * TimeMonitor also has class methods that create or destroy timers
 * (in such a way that it can track the complete set of created timers
 * on each process) and compute global timer statistics.
 */

/** \example TimeMonitor/cxx_main.cpp
 *
 * This is an example of how to use the Teuchos::TimeMonitor class.
 */

#include "Teuchos_PerformanceMonitorBase.hpp"
#include "Teuchos_ParameterList.hpp"
#include "Teuchos_Comm.hpp"
#include "Teuchos_Time.hpp"

#include "Teuchos_CommandLineProcessor.hpp"

/// \brief Defines a static non-member function that returns a Teuchos timer.
///
/// \warning Please don't use this macro.  It is a bad idea to keep
///   around static RCP objects past return from main().
#define TEUCHOS_TIMER(funcName, strName) \
  static Teuchos::Time& funcName() \
  {static Teuchos::RCP<Time> rtn = \
      Teuchos::TimeMonitor::getNewCounter(strName); return *rtn;}


/** \brief Defines a timer for a specific function (with differentiator).
 *
 * Same as TEUCHOS_FUNC_TIME_MONITOR(...) except required when used more than
 * once in the same function (like a block of code).
 *
 * \warning Please don't use this macro.  It is a bad idea to keep
 *   around static RCP objects past return from main().
 */
#define TEUCHOS_FUNC_TIME_MONITOR_DIFF( FUNCNAME, DIFF ) \
  static Teuchos::RCP<Teuchos::Time> DIFF ## blabla_localTimer; \
  if(!DIFF ## blabla_localTimer.get()) { \
    std::ostringstream oss; \
    oss << FUNCNAME; \
    DIFF ## blabla_localTimer = Teuchos::TimeMonitor::getNewCounter(oss.str()); \
  } \
  Teuchos::TimeMonitor DIFF ## blabla_localTimeMonitor(*DIFF ## blabla_localTimer)


/** \brief Defines a timer for a specific function.
 *
 Note that the name of the timer can be formated with stream inserts.
 For example, we can define a time monitor for a function as follows:

 \code
 template<typename Scalar>
 void foo()
 {
   TEUCHOS_FUNC_TIME_MONITOR(
     "foo<" << Teuchos::ScalarTraits<Scalar>::name () << ">()"
     );
   ...
 }
 \endcode

 The timer can then be printed at the end of the program using any of
 various class methods, including summarize():
 \code
 Teuchos::TimeMonitor::summarize ();
 \endcode
*/
#define TEUCHOS_FUNC_TIME_MONITOR( FUNCNAME ) \
  TEUCHOS_FUNC_TIME_MONITOR_DIFF( FUNCNAME, main )


namespace Teuchos {

/// \typedef stat_map_type
/// \brief Global statistics collected from timer data.
///
/// Key: name of the timer.
///
/// Value: each entry in the vector is a timing and call count for
///   that timer, corresponding to a particular statistic (e.g.,
///   minimum, arithmetic mean, or maximum).  What statistic that is
///   depends on an auxillary array "statNames" which has the same
///   ordering as the entries in this vector.  See the documentation
///   of \c TimeMonitor::computeGlobalTimerStatistics().
typedef std::map<std::string, std::vector<std::pair<double, double> > > stat_map_type;

/// \class TimeMonitor
/// \brief A scope-safe timer wrapper class, that can compute global timer statistics.
///
/// An instance of the TimeMonitor class wraps a nonconst reference to
/// a Time timer object.  TimeMonitor's constructor starts the timer,
/// and its destructor stops the timer.  This ensures scope safety of
/// timers, so that no matter how a scope is exited (whether the
/// normal way or when an exception is thrown), a timer started in the
/// scope is stopped when the scope is left.
///
/// TimeMonitor also has class methods that create or destroy timers
/// and compute global timer statistics.  If you create a timer using
/// getNewCounter() (or the deprecated getNewTimer()), it will add
/// that timer to the set of timers for which to compute global
/// statistics.  The summarize() and report() methods will print
/// global statistics for these timers, like the minimum, mean, and
/// maximum time over all processes in the communicator, for each
/// timer.  These methods work correctly even if some processes have
/// different timers than other processes.  You may also use
/// computeGlobalTimerStatistics() to compute the same global
/// statistics, if you wish to use them in your program or output them
/// in a different format than that of these methods.
///
/// \warning This class must only be used to time functions that are
///   called only within the main program.  It may <i>not</i> be used
///   in pre-program setup or post-program teardown!
class TEUCHOSCOMM_LIB_DLL_EXPORT TimeMonitor :
    public PerformanceMonitorBase<Time> {
public:

  /** \name Constructor/Destructor */
  //@{

  /// \brief Constructor: starts the timer.
  ///
  /// \param timer [in/out] Reference to the timer to be wrapped.
  ///   This constructor starts the timer, and the destructor stops
  ///   the timer.
  ///
  /// \param reset [in] If true, reset the timer before starting it.
  ///   Default behavior is not to reset the timer.
  TimeMonitor (Time& timer, bool reset=false);

  //! Destructor: stops the timer.
  ~TimeMonitor();
  //@}

  /// \brief Return a new timer with the given name (class method).
  ///
  /// Call getNewCounter() or this method if you want to create a new
  /// named timer, and you would like TimeMonitor to track the timer
  /// for later computation of global statistics over processes.
  ///
  /// This method wraps getNewCounter() (inherited from the base
  /// class) for backwards compatibiity.
  static RCP<Time> getNewTimer (const std::string& name) {
    return getNewCounter (name);
  }

  /// \brief Disable the timer with the given name.
  ///
  /// "Disable" means that the timer (Time instance) will ignore all
  /// calls to start(), stop(), and incrementNumCalls().  The effect
  /// will be as if the TimeMonitor had never touched the timer.
  ///
  /// If the timer with the given name does not exist (was never
  /// created using getNewCounter() or getNewTimer()), then this
  /// method throws std::invalid_argument.  Otherwise, it disables the
  /// timer.  This effect lasts until the timer is cleared or until
  /// the timer is enabled, either by calling enableTimer() (see
  /// below) or by calling the Time instance's enable() method.
  ///
  /// Disabling a timer does <i>not</i> exclude it from the list of
  /// timers printed by summarize() or report().
  static void disableTimer (const std::string& name);

  /// \brief Enable the timer with the given name.
  ///
  /// If the timer with the given name does not exist (was never
  /// created using getNewCounter() or getNewTimer()), then this
  /// method throws std::invalid_argument.  Otherwise, it undoes the
  /// effect of disableTimer() on the timer with the given name.  If
  /// the timer with the given name was not disabled, then this method
  /// does nothing.
  static void enableTimer (const std::string& name);

  /// \brief Reset all global timers to zero.
  ///
  /// This method only affects Time objects created by getNewCounter()
  /// or getNewTimer().
  ///
  /// \pre None of the timers must currently be running.
  static void zeroOutTimers();

  /// \brief Compute global timer statistics for all timers on the given communicator.
  ///
  /// The typical use case for Time and TimeMonitor is that all
  /// processes in a communicator create the same set of timers, and
  /// then want to report summary statistics.  This method supports
  /// that typical use case.  For each timer in the set, this method
  /// computes a list of global statistics.  "Global" means "for all
  /// processes in the communicator."  "Statistic" means the result of
  /// a reduction over the timing and call count values.  Thus, each
  /// statistic includes both a timing and a call count.  The current
  /// list of computed statistics includes the minimum and maximum
  /// timing (and the corresponding call count for each) and the
  /// arithmetic mean (timing and call count).  This list may expand
  /// in the future.
  ///
  /// Different processes may have different sets of timers.  This
  /// method gives you two options for reconciling the sets.  If setOp
  /// is Intersection, it computes the intersection (the common
  /// subset) of timers on all processes in the communicator.
  /// Otherwise, if setOp is Union, this method computes the union of
  /// timers on all processes in the communicator.  Intersection is
  /// the default, since it means that all reported timers exist on
  /// all participating processes.  For setOp=Union, timers that do
  /// not exist on some processes will be given a zero timing and call
  /// count, so that statistics make sense.
  ///
  /// \note This method must called as a collective by all processes
  ///   in the communicator.
  ///
  /// All output arguments are returned redundantly on all processes
  /// in the communicator.  That makes this method an all-reduce.
  ///
  /// \section Teuchos_TimeMonitor_computeGlobalTimerStatistics_stats Statistics collected
  ///
  /// The "MinOverProcs" and "MaxOverProcs" timings are cumulative:
  /// the reported timing is for all calls.  Along with the min resp.
  /// max timing comes the call count of the process who had the min
  /// resp. max.  (If more than one process had the min resp. max
  /// timing, then the call count on the process with the smallest
  /// rank is reported.)
  ///
  /// The "MeanOverProcs" equals the sum of the processes' cumulative
  /// timings, divided by the number of processes.  Thus, it is
  /// cumulative over all calls, and is comparable with the
  /// "MinOverProcs" and "MaxOverProcs" timings.  This differs from
  /// the "MeanOverCallCounts" (see below).  This does <i>not</i>
  /// weight the mean by call counts.
  ///
  /// The "MeanOverCallCounts" is an arithmetic mean of all timings.
  /// It is <i>not</i> cumulative.  It reports the mean timing for a
  /// single invocation over all calls on all processes, not weighting
  /// any one process more than the others.  For each timer, this is
  /// the sum of the cumulative timing over all processes, divided by
  /// the sum of the call counts over all processes for that timing.
  /// (We compute it a bit differently to help prevent overflow.)  The
  /// "MeanOverCallCounts" is <i>not</i> comparable with the min, max,
  /// or "MeanOverProcs".
  ///
  /// We report with both versions of the mean timing the mean call
  /// count over processes.  This may be fractional, which is one
  /// reason why we report call counts as \c double rather than \c
  /// int.  It has no particular connection to the mean timing.
  ///
  /// \section Teuchos_TimeMonitor_computeGlobalTimerStatistics_perf Performance
  ///
  /// This operation requires interprocess communication.  Suppose
  /// there are \f$P\f$ processes in the given communicator, and
  /// \f$N\f$ unique timers in the global union of all processes'
  /// timers.  Then, this method requires \f$O(\log P)\f$ messages
  /// (\f$O(1)\f$ "reductions" and exactly 1 "broadcast") and
  /// \f$O(N)\f$ per-processor storage (in the worst case) when
  /// computing either the intersection or the union of timers (the
  /// algorithm is similar in either case).  The whole algorithm takes
  /// at worst \f$O(N (\log N) (\log P))\f$ time along the critical
  /// path (i.e., on the "slowest process" in the communicator).  The
  /// \f$N \log N\f$ term comes from sorting the timers by label at
  /// each stage of the reduction in order to compute their union or
  /// intersection.
  ///
  /// \param statData [out] On output: Global timer statistics, stored
  ///   as a map with key timer name, and with value the ordered list
  ///   of statistics for that timer.  The \c statNames output has the
  ///   same order as the ordered list of statistics for each timer.
  ///   Each entry of the statistics list is a (timing, call count)
  ///   pair, the meaning of which depends on the particular statistic
  ///   (see above).
  ///
  /// \param statNames [out] On output: Each value in the statData map
  ///   is a vector.  That vector v has the same number of entries as
  ///   statNames.  statNames[k] is the name of the statistic (see
  ///   above) stored as v[k].  Always refer to statNames for the
  ///   number and names of statistics.
  ///
  /// \param comm [in] Communicator whose process(es) will participate
  ///   in the gathering of timer statistics.  This is a Ptr and not
  ///   an RCP, because RCP would suggest that TimeMonitor were
  ///   keeping the communicator around after return of this method.
  ///   Ptr suggests instead that TimeMonitor will only reference the
  ///   communicator during this method.  If you have an RCP, you can
  ///   turn it into a Ptr by calling its ptr() method:
  ///   \code
  ///   RCP<const Comm<int> > myComm = ...;
  ///   TimeMonitor::computeGlobalTimerStatistics (statData, statNames, myComm.ptr());
  ///   \endcode
  ///
  /// \param setOp [in] If \c Intersection, compute statistics for the
  ///   intersection of all created timers over all processes in the
  ///   communicator.  If \c Union, compute statistics for the union
  ///   of all created timers over all processes in the communicator.
  ///
  /// \param filter [in] Filter for timer labels.  If filter is not
  ///   empty, this method will only compute statistics for timers
  ///   whose labels begin with this string.
  static void
  computeGlobalTimerStatistics (stat_map_type& statData,
                                std::vector<std::string>& statNames,
                                Ptr<const Comm<int> > comm,
                                const ECounterSetOp setOp=Intersection,
                                const std::string& filter="");

  /// \brief Compute global timer statistics for all timers on all (MPI) processes.
  ///
  /// This is an overload of the above computeGlobalTimerStatistics()
  /// method for when the caller does not want to provide a
  /// communicator explicitly.  This method "does the right thing" in
  /// that case.  Specifically:
  /// - If Trilinos was not built with MPI support, this method
  ///   assumes a serial "communicator" containing one process.
  /// - If Trilinos was built with MPI support and MPI has been
  ///   initialized (via MPI_Init() or one of the wrappers in
  ///   Epetra or Teuchos), this method uses MPI_COMM_WORLD as the
  ///   communicator.  This is the most common case.
  /// - If Trilinos was built with MPI support and MPI has <i>not</i>
  ///   been initialized, this method will use a "serial" communicator
  ///   (that does not actually use MPI).  This may produce output on
  ///   all the MPI processes if you are running with Trilinos as an
  ///   MPI job with more than one process.  Thus, if you intend to
  ///   use this method in parallel, you should first initialize MPI.
  ///   (We cannot initialize MPI for you, because we have no way to
  ///   know whether you intend to run an MPI-enabled build serially.)
  ///
  /// \warning If you call this method when MPI is running, you
  ///   <i>must</i> call it on all processes in \c MPI_COMM_WORLD.
  ///   Otherwise, the method will never finish, since it will be
  ///   waiting forever for the non-participating processes.  If you
  ///   want to use computeGlobalTimerStatistics() on a
  ///   subcommunicator, please use the overloaded version above that
  ///   takes a communicator as an input argument.
  static void
  computeGlobalTimerStatistics (stat_map_type& statData,
                                std::vector<std::string>& statNames,
                                const ECounterSetOp setOp=Intersection,
                                const std::string& filter="");

  /// \brief Print summary statistics for all timers on the given communicator.
  ///
  /// If writeGlobalStatus=true, this method computes the same
  /// statistics as computeGlobalTimerStatistics(), using the same
  /// collective algorithm.  (<tt>writeGlobalStatus=false</tt> means
  /// that only the process with rank 0 in the communicator reports
  /// its timers' data.)  It then reports the results to the given
  /// output stream on the process with rank 0 in the given
  /// communicator.  Output follows a human-readable tabular form.
  ///
  /// \param comm [in] Communicator whose process(es) will participate
  ///   in the gathering of timer statistics.  This is a Ptr and not
  ///   an RCP, because RCP would suggest that TimeMonitor were
  ///   keeping the communicator around after return of this method.
  ///   Ptr suggests instead that TimeMonitor will only reference the
  ///   communicator during this method.  If you have an RCP, you can
  ///   turn it into a Ptr by calling its ptr() method:
  ///   \code
  ///   RCP<const Comm<int> > myComm = ...;
  ///   TimeMonitor::summarize (myComm.ptr());
  ///   \endcode
  ///
  /// \param out [out] Output stream to which to write.  This will
  ///   only be used on the process with rank 0 in the communicator.
  ///
  /// \param alwaysWriteLocal [in] If true, the process with Rank 0 in
  ///   the communicator will write its local timings to the given
  ///   output stream.  Defaults to false, since the global statistics
  ///   are more meaningful.  If the local set of timers differs from
  ///   the global set of timers (either the union or the
  ///   intersection, depending on \c setOp), Proc 0 will create
  ///   corresponding local timer data (<i>not</i> corresponding
  ///   timers) with zero elapsed times and call counts, just to pad
  ///   the table of output.
  ///
  /// \param writeGlobalStats [in] If true (the default), compute and
  ///   display the statistics that \c computeGlobalTimerStatistics()
  ///   computes.  If there is only one MPI process or if this is a
  ///   non-MPI build of Trilinos, only compute and show the "global"
  ///   timings, without the "statistics" that would be all the same
  ///   anyway.
  ///
  /// \param writeZeroTimers [in] If false, do not display results for
  ///   timers that have never been called (numCalls() == 0).  If
  ///   true, display results for all timers, regardless of their call
  ///   count.  Note that \c setOp and \c writeGlobalStats might
  ///   reintroduce timers with zero call counts.
  ///
  /// \param setOp [in] If \c Intersection, compute and display the
  ///   intersection of all created timers over all processes in the
  ///   communicator.  If \c Union, compute and display the union of
  ///   all created timers over all processes in the communicator.
  ///
  /// \param filter [in] Filter for timer labels.  If filter is not
  ///   empty, this method will only print timers whose labels begin
  ///   with this string.
  ///
  /// \param ignoreZeroTimers [in] Processes that either do not have
  ///   a particular timer or have zero time for a timer are not used
  ///   in calculating global statistics. This mode requires one
  ///   additional all-reduce per invocation.
  ///
  /// \note If \c writeGlobalStats is true, this method <i>must</i> be
  ///   called as a collective by all processes in the communicator.
  ///   This method will <i>only</i> perform communication if
  ///   <tt>writeGlobalStats</tt> is true.
  static void
  summarize (Ptr<const Comm<int> > comm,
             std::ostream &out=std::cout,
             const bool alwaysWriteLocal=false,
             const bool writeGlobalStats=true,
             const bool writeZeroTimers=true,
             const ECounterSetOp setOp=Intersection,
             const std::string& filter="",
             const bool ignoreZeroTimers=false);

  /// \brief Print summary statistics for all timers on all (MPI) processes.
  ///
  /// This is an overload of the above summarize() method for when the
  /// caller does not want to provide a communicator explicitly.  This
  /// method "does the right thing" in that case.  For an explanation
  /// of what that means, see the documentation of the overload of
  /// computeGlobalTimerStatistics() that does not require a
  /// communicator argument.
  ///
  /// \warning If you call this method when MPI is running, you
  ///   <i>must</i> call it on all processes in \c MPI_COMM_WORLD.
  ///   Otherwise, the method will never finish, since it will be
  ///   waiting forever for the non-participating processes.  If you
  ///   want to use \c summarize() on a subcommunicator, please use
  ///   the overloaded version above that takes a communicator as an
  ///   input argument.
  static void
  summarize (std::ostream& out=std::cout,
             const bool alwaysWriteLocal=false,
             const bool writeGlobalStats=true,
             const bool writeZeroTimers=true,
             const ECounterSetOp setOp=Intersection,
             const std::string& filter="",
             const bool ignoreZeroTimers=false);

  /// \brief Report timer statistics to the given output stream.
  ///
  /// This is like summarize(), but gives you more control over the
  /// output format.  To get the default parameters, either call
  /// getValidReportParameters(), or call this method with params
  /// nonnull but empty (it will fill in default parameters).
  ///
  /// \param comm [in] Communicator whose process(es) will participate
  ///   in the gathering of timer statistics.  This is a Ptr and not
  ///   an RCP, because RCP would suggest that TimeMonitor were
  ///   keeping the communicator around after return of this method.
  ///   Ptr suggests instead that TimeMonitor will only reference the
  ///   communicator during this method.  If you have an RCP, you can
  ///   turn it into a Ptr by calling its ptr() method:
  ///   \code
  ///   RCP<const Comm<int> > myComm = ...;
  ///   TimeMonitor::report (myComm.ptr (), ...);
  ///   \endcode
  ///
  /// \param out [out] Output stream to which to write.  This will
  ///   only be used on the process with rank 0 in the communicator.
  ///
  /// \param filter [in] Filter for timer labels.  If filter is not
  ///   empty, this method will only print timers whose labels begin
  ///   with this string.
  ///
  /// \param params [in/out] Parameters to control output format and
  ///   which statistics to generate.  If null, we use default
  ///   parameters if this method was not yet called with params
  ///   nonnull, otherwise we use the previous set of parameters.  If
  ///   nonnull, we read the given parameters, filling in defaults,
  ///   and use the resulting parameters for all subsequent calls to
  ///   report() (until new parameters are set).
  ///
  /// \section Teuchos_TimeMonitor_report_SupportedParams Supported parameters
  ///
  /// Here is the current set of supported parameters:
  /// - "Report format": "Table" (default), "YAML"
  /// - "YAML style": "spacious" (default), "compact"
  /// - "How to merge timer sets": "Intersection" (default), "Union"
  /// - "alwaysWriteLocal": true, false (default)
  /// - "writeGlobalStats": true (default), false
  /// - "writeZeroTimers": true (default), false
  ///
  /// This method currently supports two different output formats.
  /// "Table" format is the same tabular format which summarize()
  /// uses.  It displays times and call counts in a table that is easy
  /// for humans to read, but hard to parse.  "YAML" format uses a
  /// standard, structured, human-readable output format called YAML.
  /// <a href="http://yaml.org">YAML</a> stands for YAML Ain't Markup
  /// Language.
  ///
  /// "YAML style" refers to two variants of YAML output that report()
  /// can generate.  The "compact" mode attempts to put as much data
  /// on each line as possible.  It may be more readable when there
  /// are a small number of timers.  The "spacious" mode prefers one
  /// line per datum whenever possible.  Both modes have the same
  /// schema, that is, their output has the same hierarchical
  /// structure and thus the same parse tree.
  ///
  /// (In technical terms: compact mode uses YAML's so-called "flow
  /// style" for sequences and mappings whenever possible, except at
  /// the outermost level where it would hinder readability.  Spacious
  /// mode does not use "flow style" for lists or mappings.  For an
  /// explanation of YAML's flow style, see <a
  /// href="http://www.yaml.org/spec/1.2/spec.html#style/flow/">Chapter
  /// 7 of the YAML 1.2 spec</a>.)
  ///
  /// "How to merge timer sets" refers to the set operation by which
  /// processors should combine their sets of timers in order to
  /// compute global timer statistics.  This corresponds to the
  /// <tt>setOp</tt> argument of summarize().
  ///
  /// The remaining Boolean parameters are the same as the eponymous
  /// arguments of summarize(), to whose documentation one should
  /// refer.  There are some wrinkles: in particular, YAML output
  /// ignores the "alwaysWriteLocal" parameter and assumes
  /// "writeGlobalStats" is true.
  static void
  report (Ptr<const Comm<int> > comm,
          std::ostream& out,
          const std::string& filter,
          const RCP<ParameterList>& params=null);

  /// \brief Report timer statistics to the given output stream.
  ///
  /// This is like the 4-argument version of report(), but with a
  /// default filter.
  static void
  report (Ptr<const Comm<int> > comm,
          std::ostream& out,
          const RCP<ParameterList>& params=null);

  /// \brief Report timer statistics to the given output stream.
  ///
  /// This is like the 4-argument version of report(), but with a
  /// default communicator.
  static void
  report (std::ostream& out,
          const std::string& filter,
          const RCP<ParameterList>& params=null);

  /// \brief Report timer statistics to the given output stream.
  ///
  /// This is like the 4-argument version of report(), but with a
  /// default communicator and a default filter.
  static void
  report (std::ostream& out,
          const RCP<ParameterList>& params=null);

  //! Default parameters (with validators) for report().
  static RCP<const ParameterList> getValidReportParameters ();

 private:
  /// \brief Valid output formats for report().
  ///
  /// \warning This is an implementation detail of TimeMonitor.  It is
  ///   subject to change at any time without notice.
  enum ETimeMonitorReportFormat {
    REPORT_FORMAT_YAML,
    REPORT_FORMAT_TABLE
  };

  /// \brief Valid YAML output formats for report().
  ///
  /// \warning This is an implementation detail of TimeMonitor.  It is
  ///   subject to change at any time without notice.
  enum ETimeMonitorYamlFormat {
    YAML_FORMAT_COMPACT,
    YAML_FORMAT_SPACIOUS
  };

  /// \brief Like summarize(), but with YAML-format output.
  ///
  /// \param comm [in] Communicator over which to compute timer
  ///   statistics.
  /// \param out [out] Output stream to which to write (on Proc 0 of
  ///   the given communicator only).
  /// \param yamlStyle [in] Whether to print YAML output in "compact"
  ///   or "spacious" style.
  /// \param filter [in] Filter for timer labels.  If filter is not
  ///   empty, this method will only print timers whose labels begin
  ///   with this string.
  ///
  /// \warning This is an experimental interface.  It may change or
  ///   disappear without warning.
  static void
  summarizeToYaml (Ptr<const Comm<int> > comm,
                   std::ostream& out,
                   const ETimeMonitorYamlFormat yamlStyle,
                   const std::string& filter="");

  /// \brief Like summarize(), but with YAML-format output and default communicator.
  ///
  /// \warning This is an experimental interface.  It may change or
  ///   disappear without warning.
  static void
  summarizeToYaml (std::ostream& out,
                   const ETimeMonitorYamlFormat yamlStyle,
                   const std::string& filter="");

  /// \brief Add the "Report format" parameter to plist.
  ///
  /// \note Call this in getValidReportParameters() to set a default
  ///   value and validator for this parameter.
  static void setReportFormatParameter (ParameterList& plist);

  /// \brief Add the "YAML style" parameter to plist.
  ///
  /// \note Call this in getValidReportParameters() to set a default
  ///   value and validator for this parameter.
  static void setYamlFormatParameter (ParameterList& plist);

  /// \brief Add the "How to merge timer sets" parameter to plist.
  ///
  /// \note Call this in getValidReportParameters() to set a default
  ///   value and validator for this parameter.
  static void setSetOpParameter (ParameterList& plist);

  /// \brief Set parameters for report().  Call only from report().
  ///
  /// If this method completes successfully, it sets setParams_ to
  /// true as a flag.
  ///
  /// \param params [in/out] Parameters for report().  This may be
  ///   null, in which case we use defaults or the last set of
  ///   parameters.
  ///
  /// \warning This method is not thread safe, in the sense that it
  ///   does not set the class data atomically.  Behavior when calling
  ///   this method from multiple threads is undefined.  Calling this
  ///   routine with different parameter lists from different threads
  ///   will certainly not accomplish what you want to accomplish.
  static void setReportParameters (const RCP<ParameterList>& params);

  //! Parameters for the report() class method.
  //@{

  //! Current output format for report().  Set via setReportParameters().
  static ETimeMonitorReportFormat reportFormat_;

  /// Current output style for report(), when using YAML output.
  /// Set via setReportParameters().
  static ETimeMonitorYamlFormat yamlStyle_;

  //! Whether report() should use the intersection or union of timers over processes.
  static ECounterSetOp setOp_;

  //! Whether report() should always report Proc 0's local timer results.
  static bool alwaysWriteLocal_;

  /// Whether report() should always compute global timer statistics.
  /// This requires communication equivalent to O(1) all-reduces.
  static bool writeGlobalStats_;

  //! Whether report() should report timers with zero call counts.
  static bool writeZeroTimers_;
  //@}

  /// \brief Whether setReportParameters() completed successfully.
  ///
  /// \note Keeping this helps us avoid keeping the whole
  ///   ParameterList around.
  static bool setParams_;
};


} // namespace Teuchos


namespace Teuchos {

/// \class TimeMonitorSurrogateImpl
/// \brief Implementation of TimeMonitorSurrogate that invokes TimeMonitor.
/// \warning Users should not use this class or rely on it in any way.
///   It is an implementation detail.
///
/// Please refer to the documentation of
/// TimeMonitorSurrogateImplInserter and TimeMonitorSurrogate for an
/// explanation of the purpose of this class.
class TimeMonitorSurrogateImpl : public CommandLineProcessor::TimeMonitorSurrogate
{
  virtual void summarize (std::ostream& out) {
    TimeMonitor::summarize (out);
  }
};

/// \class TimeMonitorSurrogateImplInserter
/// \brief Injects run-time dependency of a class on TimeMonitor.
/// \warning Users should not use this class or rely on it in any way.
///   It is an implementation detail.
///
/// \section Teuchos_TimeMonitorSurrogateImplInserter_Summary Summary
///
/// Classes and functions with the name "TimeMonitorSurrogate" in them
/// let CommandLineProcessor optionally call TimeMonitor::summarize(),
/// without needing to know that the TimeMonitor class exists.  This
/// allows Teuchos to put CommandLineProcessor in a separate package
/// from TimeMonitor.  We want to do this because TimeMonitor depends
/// on Comm, and is therefore in the TeuchosComm subpackage (which
/// depends on TeuchosCore), but CommandLineProcessor is in a
/// different subpackage which does not depend on Comm.
///
/// The TimeMonitorSurrogateImplInserter class' constructor ensures
/// that CommandLineProcessor gets informed about TimeMonitor even
/// before the program starts executing main().  This happens
/// automatically, without changes to main(), because we declare an
/// instance of this class in the header file.  If the TeuchosComm
/// subpackage was built and its libraries were linked in,
/// CommandLineProcessor will know about TimeMonitor.
///
/// \section Teuchos_TimeMonitorSurrogateImplInserter_Note Note to Teuchos developers
///
/// This is an instance of the
/// <a href="http://en.wikipedia.org/wiki/Dependency_injection">Dependency injection</a>
/// design pattern.  CommandLineProcessor is not supposed to know
/// about TimeMonitor, because CommandLineProcessor's subpackage does
/// not depend on TimeMonitor's subpackage.  Thus,
/// CommandLineProcessor interacts with TimeMonitor through the
/// TimeMonitorSurrogate interface.  TimeMonitorSurrogateImplInserter
/// "injects" the dependency at run time, if the TeuchosComm
/// subpackage was enabled and the application linked with its
/// libraries.
///
/// Teuchos developers could imitate the pattern of this class in
/// order to use TimeMonitor's class methods (such as summarize())
/// from any other class that does not depend on the TeuchosComm
/// subpackage.
class TimeMonitorSurrogateImplInserter {
public:
  //! Constructor: inject dependency on TimeMonitor into CommandLineProcessor.
  TimeMonitorSurrogateImplInserter () {
    if (is_null (CommandLineProcessor::getTimeMonitorSurrogate ())) {
      CommandLineProcessor::setTimeMonitorSurrogate (Teuchos::rcp (new TimeMonitorSurrogateImpl));
    }
  }
};

} // end namespace Teuchos


namespace {

// Inject the implementation in every translation unit.
Teuchos::TimeMonitorSurrogateImplInserter timeMonitorSurrogateImplInserter;

} // namespace (anonymous)

#endif // TEUCHOS_TIMEMONITOR_H