Stopwatch Manager

This page will show you how to use the Stopwatch Manager to host multiple Stopwatch instances.

Guide

When we use Stopwatch in some simple projects, we usually only create one Stopwatch instance.

demo_stopwatch: Stopwatch = Stopwatch()

But in some medium and large projects, we may need to use multiple Stopwatch instances and share them globally. At this point, the Stopwatch instance created directly above may not be easy to share and maintain globally. When multiple Stopwatch instances are required, the management and maintenance of instance objects becomes complicated.

In 0.1.3 or higher, we can use one or more Stopwatch managers to host these Stopwatch instances and share them globally, without the developer having to maintain them.

In the following, we will show you how to use the Stopwatch Manager with a few paragraphs of Python code.

Import module

Before using the Stopwatch Manager, we should import the StopwatchManager:

from stopwatch import StopwatchManager

If you don't need multiple Stopwatch Manager instances, you can use the default Stopwatch Manager directly and share it globally.

from stopwatch import default_manager

The symbol default_manager is a variable of data type StopwatchManager that is created when the package stopwatch is first imported. Therefore, you can import this variable globally to share the Stopwatch default manager instance globally.

Create manager

If the Stopwatch default manager is not sufficient to meet your needs, you can create additional Stopwatch manager instances.

demo_manager: StopwatchManager = StopwatchManager(
    max_stopwatch_count = None
)

The constructor method of class StopwatchManager has an optional parameter max_stopwatch_count of data type int that indicates how many Stopwatch instances can be hosted by the Stopwatch manager being created at the same time. If this parameter is not supplied or the value is None, the number of Stopwatch instances is not limited.

Add Stopwatch

At the beginning of this tutorial, we defined a variable called demo_stopwatch, which is a Stopwatch instance. Now we try to add demo_stopwatch to the Stopwatch manager instance demo_manager created above.

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

The method add has 2 parameters, which are:

Parameter	Type	Required	Description
stopwatch_name	str	True	The unique name of the Stopwatch instance.
stopwatch_instance	Stopwatch	True	The Stopwatch instance object that was added.

We strongly recommend that you name the Stopwatch instance unique name in the form of a namespace::name so that when multiple collaborative projects are in the same global scope, the Stopwatch instance unique name conflict is not raised and the Namespace can be the project name.

Note that the Stopwatch instance name must be unique within the current Stopwatch manager scope, otherwise a StopwatchNameError exception will be thrown.

If the number of Stopwatch instances that are currently hosted in the Stopwatch Manager equals or exceeds the limit of the max_stopwatch_count parameter, a MaxLimitError exception is thrown.

Create Stopwatch

In addition to adding an existing Stopwatch instance to the Stopwatch manager, we can also create a new Stopwatch instance with the default constructor method parameters directly in the Stopwatch manager.

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

The method create has a parameter stopwatch_name of data type str, which indicates the unique name of the newly created and added Stopwatch instance. When created and added, this method returns a Stopwatch instance object of data type Stopwatch.

We can also create and add a Stopwatch instance to make it start timing.

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

Remove Stopwatch

We can do this when we need to remove the Stopwatch instance with the specified unique name from the Stopwatch Manager.

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

If you need to remove all Stopwatch instances, you can use the clear method.

demo_manager.clear()

Note that if the specified Stopwatch instance unique name does not exist, a StopwatchNameError exception will be thrown.

Get Stopwatch

When we need to share a Stopwatch instance globally within the project, we don't need to maintain these Stopwatch instances, we use the unique name of the Stopwatch instance to get it from the Stopwatch manager.

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

If we need to determine if a Stopwatch instance exists, we can check it with the has method.

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

Manage Stopwatch

Get the number of instances

The get_count method can be used when we need to get the number of Stopwatch instances that the specified Stopwatch manager has hosted.

number_of_stopwatchs: int = demo_manager.get_count()

The method get_count has a return value of the int data type, which indicates the number of Stopwatch instances.

Make the instance start timing

The starts method can be used when we need to start specifying a batch or all of the Stopwatch instances.

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

The method starts has an optional parameter stopwatch_names with the data type list, which indicates a list of unique names for the Stopwatch instance that needs to be started. If this parameter is not supplied or the value is None, all Stopwatch instances are started.

This method returns a return value of data type int indicating the number of Stopwatch instances that actually started.

Note that if one or more instances have started timing, the method will skip instead of raising a StatusError exception.

Stop the instance timing

Similarly, we can also stop specifying a batch or all of the Stopwatch instances.

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

This method returns a return value of data type int indicating the number of Stopwatch instances that were actually stopped.

Note that if one or more instances have stopped timing, the method will skip instead of raising a StatusError exception.

Reset the instance

In addition to starting timing and stopping timing, we can also reset a specified batch or all of the Stopwatch instances.

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

Get the total duration of the instance

The get_watchs method can be used when we need to get the current total duration for a specified batch or all of the Stopwatch instances.

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

The method get_watchs has an optional parameter watch_precision with an extra data type of int relative to the other methods mentioned above, which indicates the precision of the total time (the number of decimal places). If this parameter is not supplied or the value is None, its behavior is consistent with the behavior of the watch_precision of the Stopwatch instance's get_watch method.

Example

Source code

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()

Result

1.0