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 实例个数。我们在本篇指导文章的开头,定义了名为
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 实例。
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 实例时,我们可以这样做。
demo_manager.remove(
stopwatch_name = 'guide::demo2'
)
如果需要移除所有 Stopwatch 实例,可以使用
clear
方法。demo_manager.clear()
请注意,如果指定 Stopwatch 实例唯一名称不存在,将引发 StopwatchNameError 异常。
当我们需要在项目全局范围内共享 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 实例个数时,可以使用
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
Last modified 3yr ago