> For the complete documentation index, see [llms.txt](https://smallso.gitbook.io/stopwatch/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://smallso.gitbook.io/stopwatch/python/getting-started/stopwatch-manager.md).

# Stopwatch 管理器

## 指导 <a href="#guide" id="guide"></a>

当我们在一些简单的项目中使用 Stopwatch 时，通常仅创建一个 Stopwatch 实例。

```python
demo_stopwatch: Stopwatch = Stopwatch()
```

但在一些中、大型项目中，我们可能会需要使用多个 Stopwatch 实例并在项目全局共享。此时，上文中直接创建的 Stopwatch 实例可能不便于在全局范围内共享和维护。而当需要多个 Stopwatch 实例时，对实例对象的管理和维护将变得复杂。

在 0.1.3 或更高版本中，我们可以使用一个或多个 Stopwatch 管理器托管这些 Stopwatch 实例并在全局范围内共享，开发者也无需维护这些实例对象。

在下文中，我们将通过几段连续的 Python 代码向您演示如何使用 Stopwatch 管理器。

### 导入模块 <a href="#import-module" id="import-module"></a>

在使用 Stopwatch 管理器之前，我们应该导入 `StopwatchManager`：

```python
from stopwatch import StopwatchManager
```

如果您不需要多个 Stopwatch 管理器实例，可以直接使用默认的 Stopwatch 管理器并在全局范围内共享。

```python
from stopwatch import default_manager
```

符号 `default_manager` 是一个数据类型为 `StopwatchManager` 的变量，它在包 `stopwatch` 被首次导入时创建。因此，您可以在全局范围内导入此变量，以在全局范围内共享 Stopwatch 默认管理器实例。

### 创建管理器 <a href="#create-manager" id="create-manager"></a>

如果 Stopwatch 默认管理器不足以满足需求，您可以额外创建多个 Stopwatch 管理器实例。

```python
demo_manager: StopwatchManager = StopwatchManager(
    max_stopwatch_count = None
)
```

类 `StopwatchManager` 的构造器方法有一个数据类型为 `int` 的可选参数 `max_stopwatch_count`，该参数指示被创建的 Stopwatch 管理器最多可以同时托管多少个 Stopwatch 实例。如果未提供该参数或值为 `None`，则不限制 Stopwatch 实例个数。

### 添加 Stopwatch <a href="#add-stopwatch" id="add-stopwatch"></a>

我们在本篇指导文章的开头，定义了名为 `demo_stopwatch` 的变量，它是一个 Stopwatch 实例。现在我们尝试将 `demo_stopwatch` 添加到上文创建的 Stopwatch 管理器实例 `demo_manager` 中。

```python
demo_manager.add(
    stopwatch_name = 'guide::demo1', 
    stopwatch_instance = demo_stopwatch
)
```

方法 `add` 有 2 个参数，它们分别是：

| 参数名                 | 类型        | 必选   | 描述                   |
| ------------------- | --------- | ---- | -------------------- |
| stopwatch\_name     | str       | True | Stopwatch 实例唯一名称。    |
| stopwatch\_instance | Stopwatch | True | 被添加的 Stopwatch 实例对象。 |

我们强烈建议您使用 `namespace::name` 的形式命名 Stopwatch 实例唯一名称，这样当多个协作项目在同一全局范围内，不会引发 Stopwatch 实例唯一名称冲突，Namespace 可以是项目名称。

{% hint style="danger" %}
请注意，Stopwatch 实例名称在当前 Stopwatch 管理器范围内必须是唯一的，否则将引发 StopwatchNameError 异常。
{% endhint %}

如果当前 Stopwatch 管理器内已托管的 Stopwatch 实例个数等于或超过 `max_stopwatch_count` 参数的限制，将引发 `MaxLimitError` 异常。

### 创建 Stopwatch <a href="#create-stopwatch" id="create-stopwatch"></a>

除了向 Stopwatch 管理器添加已有 Stopwatch 实例外，我们也可以直接在 Stopwatch 管理器中创建一个具有默认构造器方法参数的新 Stopwatch 实例。

```python
new_stopwatch: Stopwatch = demo_manager.create(
    stopwatch_name = 'guide::demo2'
)
```

方法 `create` 具有 1 个数据类型为 `str` 的参数 `stopwatch_name`，该参数指示新创建并添加的 Stopwatch 实例唯一名称。创建并添加后，该方法返回数据类型为 Stopwatch 的 Stopwatch 实例对象。

我们还可以创建并添加一个 Stopwatch 实例后，使它开始计时。

```python
new_stopwatch: Stopwatch = demo_manager.create_and_start(
    stopwatch_name = 'guide::demo2'
)
```

### 移除 Stopwatch <a href="#remove-stopwatch" id="remove-stopwatch"></a>

当我们需要从 Stopwatch 管理器中移除指定唯一名称的 Stopwatch 实例时，我们可以这样做。

```python
demo_manager.remove(
    stopwatch_name = 'guide::demo2'
)
```

如果需要移除所有 Stopwatch 实例，可以使用 `clear` 方法。

```python
demo_manager.clear()
```

{% hint style="danger" %}
请注意，如果指定 Stopwatch 实例唯一名称不存在，将引发 StopwatchNameError 异常。
{% endhint %}

### 获得 Stopwatch <a href="#get-stopwatch" id="get-stopwatch"></a>

当我们需要在项目全局范围内共享 Stopwatch 实例时，无需维护这些 Stopwatch 实例，而是使用 Stopwatch 实例的唯一名称从 Stopwatch 管理器中获得它。

```python
demo_stopwatch: Stopwatch = demo_manager.get(
    stopwatch_name = 'guide::demo1'
)
```

如果我们需要确定一个 Stopwatch 实例是否存在，可以使用 `has` 方法检查。

```python
if not demo_manager.has(
    stopwatch_name = 'guide::demo2'
):
    print('no such stopwatch')
```

### 管理 Stopwatch <a href="#management-stopwatch" id="management-stopwatch"></a>

#### 获取实例个数 <a href="#get-count" id="get-count"></a>

当我们需要获取指定 Stopwatch 管理器已托管的 Stopwatch 实例个数时，可以使用 `get_count` 方法。

```python
number_of_stopwatchs: int = demo_manager.get_count()
```

方法 `get_count` 具有 `int` 数据类型的返回值，其指示 Stopwatch 实例个数。

#### 使实例开始计时 <a href="#starts" id="starts"></a>

当我们需要使指定一批或全部 Stopwatch 实例开始计时时，可以使用 `starts` 方法。

```python
demo_manager.starts(
    stopwatch_names = [
        'guide::demo1', 
        ...
    ]
)
```

方法 `starts` 有一个数据类型为 `list` 的可选参数 `stopwatch_names`，其指示需要开始的 Stopwatch 实例的唯一名称列表。如果未提供此参数或值为 `None`，则使所有 Stopwatch 实例开始计时。

该方法返回数据类型为 `int` 的返回值，指示实际开始的 Stopwatch 实例个数。

{% hint style="danger" %}
请注意，如果有一个或多个实例已经开始计时，该方法将跳过而非引发 StatusError 异常。
{% endhint %}

#### 使实例停止计时 <a href="#stops" id="stops"></a>

同样的，我们也可以使指定一批或全部 Stopwatch 实例停止计时。

```python
demo_manager.stops(
    stopwatch_names = [
        'guide::demo1', 
        ...
    ]
)
```

该方法返回数据类型为 `int` 的返回值，指示实际停止的 Stopwatch 实例个数。

{% hint style="danger" %}
请注意，如果有一个或多个实例已经停止计时，该方法将跳过而非引发 StatusError 异常。
{% endhint %}

#### 使实例重置 <a href="#resets" id="resets"></a>

除了开始计时、停止计时外，我们也可以使指定一批或全部 Stopwatch 实例重置。

```python
demo_manager.resets(
    stopwatch_names = [
        'guide::demo1', 
        ...
    ]
)
```

#### 获取实例总计时时长 <a href="#get-watchs" id="get-watchs"></a>

当我们需要获取指定一批或全部 Stopwatch 实例的当前总计时时长时，可以使用 `get_watchs` 方法。

```python
total_of_watch: float = demo_manager.get_watchs(
    stopwatch_names = [
        'guide::demo1', 
        ...
    ], 
    watch_precision = 3
)
```

方法 `get_watchs` 相对于上文所提及的其他方法有一个额外数据类型为 `int` 的可选参数 `watch_precision`，其指示获取总计时时长的精度（小数点位数）。如果未提供此参数或值为 `None`，其行为与 Stopwatch 实例的 `get_watch` 方法对参数 `watch_precision` 的行为一致。

## 示例 <a href="#example" id="example"></a>

### 源代码 <a href="#source-code" id="source-code"></a>

{% code title="quickstart.py" %}

```python
# quickstart.py is python-3.7.4 source file

import time

from stopwatch import Stopwatch
from stopwatch import StopwatchManager


# define main function

def main():

    # create a stopwatch manager
    
    demo_manager: StopwatchManager = StopwatchManager(
        max_stopwatch_count = 64
    )
    
    # Start timing after creating and adding a stopwatch instance to the manager
    
    demo_manager.create('guide::demo1').start()
    
    # simulated program time-consuming operation
    
    time.sleep(1)
    
    # get the stopwatch instance from the manager and stop timing.
    
    demo_manager.get('guide::demo1').stop()
    
    # total time duration after getting a stopwatch instance from the manager
    
    print(demo_manager.get('guide::demo1').get_watch())
    
    # remove the stopwatch instance from the manager.
    
    demo_manager.remove('guide::demo1')


# define virtual main function

if __name__ == '__main__':
    main()
```

{% endcode %}

### 运行结果 <a href="#result" id="result"></a>

```
1.0
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://smallso.gitbook.io/stopwatch/python/getting-started/stopwatch-manager.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.