Stopwatch 管理器

本页将指导您如何使用 Stopwatch 管理器来托管多个 Stopwatch 实例。

指导

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

demo_stopwatch: Stopwatch = Stopwatch()

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

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

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

导入模块

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

from stopwatch import StopwatchManager

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

from stopwatch import default_manager

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

创建管理器

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

demo_manager: StopwatchManager = StopwatchManager(
max_stopwatch_count = None
)

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

添加 Stopwatch

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

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 可以是项目名称。

请注意,Stopwatch 实例名称在当前 Stopwatch 管理器范围内必须是唯一的,否则将引发 StopwatchNameError 异常。

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

创建 Stopwatch

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

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

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

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

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

移除 Stopwatch

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

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

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

demo_manager.clear()

请注意,如果指定 Stopwatch 实例唯一名称不存在,将引发 StopwatchNameError 异常。

获得 Stopwatch

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

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

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

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

管理 Stopwatch

获取实例个数

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

number_of_stopwatchs: int = demo_manager.get_count()

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

使实例开始计时

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

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

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

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

请注意,如果有一个或多个实例已经开始计时,该方法将跳过而非引发 StatusError 异常。

使实例停止计时

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

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

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

请注意,如果有一个或多个实例已经停止计时,该方法将跳过而非引发 StatusError 异常。

使实例重置

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

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

获取实例总计时时长

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

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 的行为一致。

示例

源代码

quickstart.py
# 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()

运行结果

1.0