# myTimer.py 函数文档

高精度计时器模块，提供多种计时方式和装饰器功能。

## myTimer 类

### 初始化
```python
def __init__(self)
```
- **功能**: 初始化计时器
- **属性**:
  - start_time: 开始时间戳
  - end_time: 结束时间戳

### 基本计时方法

#### start(self)
```python
def start(self)
```
- **功能**: 开始计时
- **实现**: 记录当前毫秒时间戳
- **返回**: self (支持链式调用)

#### stop(self)
```python
def stop(self)
```
- **功能**: 停止计时
- **实现**: 记录结束时间戳
- **返回**: self (支持链式调用)

#### reset(self)
```python
def reset(self)
```
- **功能**: 重置计时器
- **实现**: 清零开始和结束时间戳
- **返回**: self (支持链式调用)

### 时间获取方法

#### elapsed(self)
```python
def elapsed(self)
```
- **功能**: 获取经过的秒数
- **返回**: 浮点数，精确到毫秒
- **单位**: 秒

#### elapsed_ms(self)
```python
def elapsed_ms(self)
```
- **功能**: 获取经过的毫秒数
- **返回**: 整数
- **单位**: 毫秒

### 上下文管理器支持
```python
def __enter__(self)
def __exit__(self, exc_type, exc_val, exc_tb)
```
- **功能**: 支持with语句使用
- **特性**: 自动处理开始和结束计时
- **异常处理**: 不捕获异常

## measure_time 装饰器

### 函数定义
```python
def measure_time(func=None, *, unit='s', print_result=True)
```
- **功能**: 测量函数运行时间的装饰器
- **参数**:
  - func: 要测量的函数
  - unit: 时间单位 ('s'秒或'ms'毫秒)
  - print_result: 是否打印结果
- **返回值**:
  - print_result=True: 返回原函数结果
  - print_result=False: 返回(原函数结果, 运行时间)元组

## 使用示例

### 基本计时
```python
# 方式1：直接使用
timer = myTimer()
timer.start()
# 执行代码
timer.stop()
print(f"耗时: {timer.elapsed():.3f} 秒")
```

### 上下文管理器
```python
# 方式2：with语句
with myTimer() as timer:
    # 执行代码
print(f"耗时: {timer.elapsed():.3f} 秒")
```

### 装饰器使用
```python
# 方式3：简单装饰器
@measure_time
def my_function():
    # 函数代码
    pass

# 方式4：带参数装饰器
@measure_time(unit='ms', print_result=False)
def another_function():
    # 函数代码
    return "结果"

result, time_taken = another_function()
```

## 高级用法

### 链式调用
```python
elapsed = myTimer().start().elapsed_ms()
```

### 精确计时
```python
timer = myTimer()
timer.start()
for _ in range(1000000):
    pass
print(f"循环耗时: {timer.elapsed_ms()} 毫秒")
```

### 装饰器定制
```python
@measure_time(unit='ms', print_result=False)
def performance_critical():
    result = complex_calculation()
    return result

result, execution_time = performance_critical()
if execution_time > 1000:  # 超过1秒
    log_performance_issue(execution_time)
```

## 技术规格

1. 时间精度
   - 毫秒级精确度
   - 基于time.ticks_ms()实现
   - 支持长时间计时

2. 性能特性
   - 低开销实现
   - 支持嵌套使用
   - 线程安全设计

3. 装饰器特性
   - 保留原函数信息
   - 灵活的配置选项
   - 支持返回值处理

## 注意事项

1. 计时精度
   - 受系统时钟精度限制
   - 考虑测量开销
   - 适当选择时间单位

2. 装饰器使用
   - 注意返回值处理
   - 合理设置打印选项
   - 考虑异常处理

3. 性能考虑
   - 避免频繁创建实例
   - 合理使用reset()
   - 注意长时间计时溢出

4. 最佳实践
   - 使用with语句更安全
   - 装饰器适合固定函数
   - 直接实例适合动态计时