Metadata-Version: 1.1
Name: hwcounter
Version: 0.1.1
Summary: Highly accurate counter for measuring elapsed time in Python
Home-page: https://github.com/paulsmith/hwcounter
Author: Paul Smith
Author-email: paulsmith@pobox.com
License: UNKNOWN
Description-Content-Type: UNKNOWN
Description: # hwcounter
        
        Highly accurate counter for measuring elapsed time in Python.
        
        ## Installation
        
        ``` shell
        $ pip install hwcounter
        ```
        
        ## Overview
        
        This Python extension module uses the hardware timestamp counter to
        provide very high precision and accurate measurements of execution
        time.
        
        The module exposes three main objects. Two are plain functions,
        `count` and `count_end`, which return the current value of the
        timestamp counter. They can be used together to manually track the
        start and end of a timing measurement. The third is the `Timer` type,
        which is to be used as a context manager, wrapping a block of code to
        be measured.
        
        Using `Timer` to wrap a block of code is to be preferred over
        manually using `count` and `count_end`. This is for convenience, as well
        as because it factors in the overhead of calling the underlying
        measurement instructions.
        
        ### `count()`
        
        Returns the current value of the timestamp counter, in cycles.
        
        ### `count_end()`
        
        Returns the current value of the timestamp counter, in cycles. It is
        suitable for use at the end of a timing measurement.
        
        ### `Timer`
        
        Class that implements the context manager protocol.
        
        #### `Timer.cycles`
        
        The `cycles` attribute is populated with the elapsed time, in cycles,
        when the Timer context manager exits.
        
        ## Example usage
        
        ``` python
        from hwcounter import Timer, count, count_end
        
        from time import sleep
        from math import sqrt
        
        
        # 1. Manually count cycles elapsed between two points
        
        start = count()
        sqrt(144) / 12
        elapsed = count_end() - start
        print(f'elapsed cycles: {elapsed}')
        # elapsed cycles: 36486
        
        
        # 2. Use Timer object as context manager to wrap a block of code and measure its timing
        
        with Timer() as t:
        	sleep(1)
        print(f'elapsed cycles: {t.cycles}')
        # elapsed cycles: 2912338344
        ```
        
        These examples were performed on an Intel Core i5-6267U CPU @
        2.90GHz. Notice that the sleep for 1 second in the example above
        yields a 2.9 billion cycle count.
        
        ## Notes
        
        The overhead of calling the underlying measurement instructions is
        taken into account when using the Timer context manager. In other
        words, the number of cycles it takes to call the machine instructions
        are subtracted from the elapsed cycle count automatically.
        
        This library returns measurements in processor clock cycles. For
        benchmarking programs and making apples-to-apples comparisons of
        changes in code execution time, this method is sufficient and
        reliable. If elapsed time in seconds is desired, a conversion from
        clock cycles is required: divide the cycle count by the processor's
        clock speed (in Hz). This conversion is outside the scope of this
        module.
        
        ## Portability
        
        This extension uses the `RDTSC` and `RDTSCP` instructions on the x86
        architecture, so it won't work on other platforms. It is Python 3
        only.
        
Keywords: benchmark x86 rdtsc timing
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: System :: Benchmark
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
