############################
cmakepp_lang/utilities/timer
############################

.. module:: cmakepp_lang/utilities/timer

   Defines functions for managing code timing through CMakePPLang.
   


.. function:: cpp_start_timing(name)

   Starts a timer using the provided name.
   
   This function is used to start a timer under the provided name. If another
   timer has previously been created using this name it will be overridden.
   
   :param name: The name for the timer.
   :type name: desc
   


.. function:: cpp_stop_timing(time name)

   Stops and computes the time since the specified timer was started.
   
   This function will compute the time (in seconds) since the specified timer was
   started. Despite the name of this function, the timer will persist meaning it
   is possible to continue to measure time since the timer was started with
   additional calls.
   
   :param time: Name for variable which will hold how long (in seconds) the
                the timer has been running.
   :type time: desc
   :param name: The name of the timer we want to measure
   :type name: desc
   :returns: ``time`` will be set to the time (in seconds) since the timer
             was started.
   :rtype: int
   
   Error Checking
   ==============
   
   This function will assert that the specified timer exists. If the timer does
   not exist an error will be raised. This error check is always performed.
   


.. function:: cpp_stop_and_print_timing(name)

   Convenience function for printing the time since a timer was started.
   
   Usually when we are timing something we want to log the time. This function is
   a convenience function which will do that by printing the timer to standard
   out.
   
   :param name: The name of the timer we are measuring.
   :type name: desc
   
   Error Checking
   ==============
   
   This function will assert that the specified timer exists. If the timer does
   not exist an error will be raised. This error check is always performed.
   


.. function:: cpp_time_fxn(fxn_name)

   Convenience function for timing a function.
   
   A very common timing scenario is that we want to know how long it takes a
   function to run. This function is a convenience function for doing that and
   will start a timer, call the function to be timed, and print how long the
   function ran for.
   
   :param fxn_name: The name of the function we are timing.
   :type fxn_name: fxn
   :param \*args: The arguments which should be forwarded to the function.