0
# Benchmark Execution
1

2
Core benchmarking functionality providing the primary interface for executing precise performance measurements. The Runner class manages worker processes, automatic calibration, and statistical validation to ensure reliable benchmark results.
3

4
## Capabilities
5

6
### Runner Class
7

8
The central interface for benchmark execution with comprehensive configuration options and automatic optimization for different Python implementations.
9

10
```python { .api }
11
class Runner:
12
    def __init__(self, values=None, processes=None, loops=0, min_time=0.1, 
13
                 metadata=None, show_name=True, program_args=None, 
14
                 add_cmdline_args=None, _argparser=None, warmups=1):
15
        """
16
        Create a benchmark runner.
17
        
18
        Args:
19
            values: Number of values per process (default: 3 for CPython, 10 for PyPy)
20
            processes: Number of worker processes (default: 20 for CPython, 6 for PyPy)  
21
            loops: Number of loops per value (0 for auto-calibration)
22
            min_time: Minimum duration per measurement in seconds
23
            metadata: Custom metadata dictionary
24
            show_name: Whether to show benchmark names in output
25
            program_args: Command line arguments for worker processes
26
            add_cmdline_args: Callback for preparing worker arguments
27
            warmups: Number of warmup iterations
28
        """
29
```
30

31
### Function Benchmarking
32

33
Direct benchmarking of Python functions with argument passing and automatic loop calibration.
34

35
```python { .api }
36
def bench_func(self, name: str, func: callable, *args, **kwargs) -> Benchmark:
37
    """
38
    Benchmark a Python function.
39
    
40
    Args:
41
        name: Benchmark name for identification
42
        func: Function to benchmark
43
        *args: Positional arguments to pass to function
44
        **kwargs: Keyword arguments (inner_loops, metadata supported)
45
        
46
    Returns:
47
        Benchmark object with timing results
48
    """
49

50
def bench_time_func(self, name: str, time_func: callable, *args, **kwargs) -> Benchmark:
51
    """
52
    Benchmark a function that returns elapsed time.
53
    
54
    Args:
55
        name: Benchmark name for identification  
56
        time_func: Function that returns timing measurements
57
        *args: Positional arguments to pass to function
58
        **kwargs: Keyword arguments (inner_loops, metadata supported)
59
        
60
    Returns:
61
        Benchmark object with timing results
62
    """
63
```
64

65
### Async Function Benchmarking
66

67
Specialized benchmarking for asynchronous functions with event loop management.
68

69
```python { .api }
70
def bench_async_func(self, name: str, func: callable, *args, **kwargs) -> Benchmark:
71
    """
72
    Benchmark an async function.
73
    
74
    Args:
75
        name: Benchmark name for identification
76
        func: Async function to benchmark
77
        *args: Positional arguments to pass to function
78
        **kwargs: Keyword arguments (inner_loops, metadata, loop_factory supported)
79
        
80
    Returns:
81
        Benchmark object with timing results
82
    """
83
```
84

85
### Python Code Benchmarking
86

87
timeit-style code benchmarking with setup and teardown phases.
88

89
```python { .api }
90
def timeit(self, name: str, stmt=None, setup="pass", teardown="pass", 
91
           inner_loops=None, duplicate=None, metadata=None, globals=None) -> Benchmark:
92
    """
93
    Benchmark Python code statements (like timeit module).
94
    
95
    Args:
96
        name: Benchmark name for identification
97
        stmt: Code statement to benchmark
98
        setup: Setup code executed once before timing
99
        teardown: Teardown code executed after timing
100
        inner_loops: Number of inner loop iterations
101
        duplicate: Number of statement duplicates per loop
102
        metadata: Custom metadata for this benchmark
103
        globals: Global namespace for code execution
104
        
105
    Returns:
106
        Benchmark object with timing results
107
    """
108
```
109

110
### External Command Benchmarking
111

112
Benchmarking of external processes and command-line tools.
113

114
```python { .api }
115
def bench_command(self, name: str, command: list) -> Benchmark:
116
    """
117
    Benchmark an external command.
118
    
119
    Args:
120
        name: Benchmark name for identification
121
        command: Command and arguments as list (e.g., ['python', '-c', 'print("hello")'])
122
        
123
    Returns:
124
        Benchmark object with timing results
125
    """
126
```
127

128
### Configuration Management
129

130
Command-line argument parsing and configuration management.
131

132
```python { .api }
133
def parse_args(self, args=None) -> argparse.Namespace:
134
    """
135
    Parse command line arguments for benchmark configuration.
136
    
137
    Args:
138
        args: Argument list (defaults to sys.argv)
139
        
140
    Returns:
141
        Parsed arguments namespace
142
    """
143
```
144

145
## Usage Examples
146

147
### Basic Function Benchmarking
148

149
```python
150
import pyperf
151

152
def fibonacci(n):
153
    if n < 2:
154
        return n
155
    return fibonacci(n-1) + fibonacci(n-2)
156

157
runner = pyperf.Runner()
158
benchmark = runner.bench_func('fibonacci_20', fibonacci, 20)
159
print(f"Mean: {benchmark.mean():.6f} ± {benchmark.stdev():.6f} seconds")
160
```
161

162
### Python Code Benchmarking
163

164
```python
165
import pyperf
166

167
runner = pyperf.Runner()
168

169
# Simple statement timing
170
benchmark = runner.timeit('list_comprehension', 
171
                         stmt='[i*2 for i in range(1000)]')
172

173
# With setup code
174
benchmark = runner.timeit('dict_lookup',
175
                         stmt='d[key]',
176
                         setup='d = {i: i*2 for i in range(1000)}; key = 500')
177
```
178

179
### Async Function Benchmarking
180

181
```python
182
import pyperf
183
import asyncio
184

185
async def async_task(n):
186
    await asyncio.sleep(0.001)  # Simulate async work
187
    return sum(range(n))
188

189
runner = pyperf.Runner()
190
benchmark = runner.bench_async_func('async_task', async_task, 100)
191
```
192

193
### External Command Benchmarking
194

195
```python
196
import pyperf
197

198
runner = pyperf.Runner()
199
benchmark = runner.bench_command('python_version', 
200
                                ['python', '-c', 'import sys; print(sys.version)'])
201
```
202

203
### Advanced Configuration
204

205
```python
206
import pyperf
207

208
# Rigorous benchmarking with more samples
209
runner = pyperf.Runner(values=10, processes=10, min_time=0.2)
210

211
# Quick rough measurements  
212
runner = pyperf.Runner(values=1, processes=3, min_time=0.05)
213

214
# Custom metadata
215
runner = pyperf.Runner(metadata={'test_environment': 'production'})
216
benchmark = runner.bench_func('test', some_function, 
217
                             metadata={'algorithm': 'quicksort'})
218
```