Module timer

Facilities for timing a block of code.
Copyright Schrodinger, LLC. All rights reserved.

Example usage:

   from schrodinger.application.desmond.packages.timer import timer

   with timer("Reading the trajectory..."):
       traj.read_trj(trj_fname)

Example output:

   Reading the trajectory...
     100 frames
     Done. (0.5 sec)

In this example, we have three lines in output. Line#1 is the start message, and
line#3 is the timing message. The start-message and the format for the timing
message can be customed by the C{message} and C{fmt} arguments, respectively.

Arguments for C{timer}:

@type    message: C{str} or C{None}
@type    message: The message to print out before the timing starts. Default is
                  C{None} -- no message will be printed.
@type        fmt: C{str}
@type        fmt: The format to print out the timing. Default is
                  "Done. (%.2f sec)". A custom format should contain 1 floating
                  number control paramter.
@type  threshold: C{float}
@param threshold: Specifies a threshold. If the elapsed time is less than
                  C{threshold}, no timing message will not be printed out.
@type     record: C{list} or C{None}
@param    record: If a list value is given, the current elapsed time will be
                  appended to the list. This is handy if you want to accumulate
                  the elapsed times.
@type     logger: A callable object.
@param    logger: Function called to print the messages.