docs/user/support/StopWatch.dox

   1 /*
   2  * Copyright 2007-2014 Haiku, Inc. All rights reserved.
   3  * Distributed under the terms of the MIT License.
   4  *
   5  * Documentation written by:
   6  *              Niels Sascha Reedijk, niels.reedijk@gmail.com
   7  *              John Scipione, jscipione@gmail.com
   8  *
   9  * Corresponds to:
  10  *              headers/os/support/StopWatch.h rev 19972
  11  *              src/kits/support/StopWatch.cpp rev 14204
  12  */
  13
  14
  15 /*!
  16         \file StopWatch.h
  17         \ingroup support
  18         \ingroup libbe
  19         \brief Provides the BStopWatch class.
  20 */
  21
  22
  23 /*!
  24         \class BStopWatch
  25         \ingroup support
  26         \ingroup libbe
  27         \brief A simple class used to time events like a stop watch.
  28
  29         The interface of this class is designed to behave like a physical
  30         stop watch. It is useful for debugging parts of your code acting as a
  31         quick and dirty profiler.
  32
  33         To use this class first create a BStopWatch object, this starts the timer
  34         going. You may call Suspend() and Resume() to start and stop the stop
  35         watch. Call ElapsedTime() to get the current timer count at any time. You
  36         may call Lap() to start a new lap (up to 10 laps are supported) or call
  37         Reset() to reset the timer back to 0 clearing all lap info. When the
  38         object is destroyed the timing information is streamed to standard out
  39         unless you set the \a silent parameter to \c true in the constructor.
  40
  41         \since BeOS R3
  42 */
  43
  44
  45 /*!
  46         \fn BStopWatch::BStopWatch(const char* name, bool silent)
  47         \brief Constructs a BStopWatch object and starts the timer.
  48
  49         This method creates a new BStopWatch object. As soon as the object is
  50         created the timer starts ticking away.
  51
  52         If you are profiling your code with this class pass \c false to the
  53         \a silent parameter to cause the elapsed time information to be
  54         streamed to standard output when the object is destroyed.
  55
  56         \param name The name of the stop watch. You may pass \c NULL to create an
  57                anonymous stop watch.
  58         \param silent Pass \c true to suppress time information from streaming to
  59                standard output when the object is destroyed.
  60
  61         \since BeOS R3
  62 */
  63
  64
  65 /*!
  66         \fn BStopWatch::~BStopWatch()
  67         \brief Destroys the object stopping the timer.
  68
  69         If \a silent was set to \c false in the constructor then this method
  70         will print elapsed time information to standard output.
  71
  72         \since BeOS R3
  73 */
  74
  75
  76 /*!
  77         \fn void BStopWatch::Resume()
  78         \brief Resume the timer from a suspended state.
  79
  80         \see Suspend()
  81
  82         \since BeOS R3
  83 */
  84
  85
  86 /*!
  87         \fn void BStopWatch::Suspend()
  88         \brief Suspend the timer.
  89
  90         \see Resume()
  91
  92         \since BeOS R3
  93 */
  94
  95
  96 /*!
  97         \fn bigtime_t BStopWatch::Lap()
  98         \brief Starts a new timer lap.
  99
 100         In the current implementation you are unable to actually retrieve the
 101         timings of each lap, they are only printed to the standard output when the
 102         object is destroyed. This makes the Lap() method only usable when doing
 103         some types of profiling.
 104
 105         \note The current implementation is limited to 10 laps. The value returned
 106               is the time that has passed since the timer was last started (not
 107               the time that has passed since the last lap). Any call to Lap()
 108               beyond the 10th lap will overwrite the last value. Calling Lap()
 109               while the timer is suspended does nothing and returns 0.
 110
 111         \since BeOS R3
 112 */
 113
 114
 115 /*!
 116         \fn bigtime_t BStopWatch::ElapsedTime() const
 117         \brief Gets the elapsed time the object has counted.
 118
 119         \return The elapsed time in microseconds.
 120
 121         \since BeOS R3
 122 */
 123
 124
 125 /*!
 126         \fn void BStopWatch::Reset()
 127         \brief Restarts the timer.
 128
 129         Resets the stop watch clearing the start time and stored laps and
 130         restarts the timer.
 131
 132         \since BeOS R3
 133 */
 134
 135
 136 /*!
 137         \fn const char* BStopWatch::Name() const
 138         \brief Returns the name of the stop watch.
 139
 140         If name was set to \c NULL in the constructor this method returns a blank
 141         string.
 142
 143         \return the name of the stop watch set in the constructor.
 144
 145         \since BeOS R3
 146 */