HourGlass

Introduction

The HourGlass() is a class that functions as a countdown timer, allowing users to create a timer that can be configured, controlled, and used to perform specific actions after a certain period of time. Its main feature is the use of parallelism for uninterrupted counting.

Implementation and Initial Use

To implement the HourGlass class in your project, you should start by importing it from the PTymer module:

from PTymer import HourGlass

With the class imported, you can create an instance of HourGlass:

my_hg = HourGlass()

Before starting the countdown, you must pay attention to its parameters.

Parameters and Customization

The HourGlass class accepts a few parameters that allow customization according to the user's needs and preferences. The parameters are as follows:

• visibility: A boolean flag for the HourGlass, defines whether there will be visible output from the class steps. It is set to False by default.
• seconds: Can be int or float and defines the total time of the timer.
• target: Represents the function to be executed at the end of the countdown.
• args: If a function is to be executed at the end of the countdown, this parameter should contain a tuple with the arguments.

Example of use with these parameters:

my_hg = HourGlass(seconds=60, visibility=True, target=print, args=('Hello World!',), persist=True)

Parallelism

Don't forget to protect the execution of your code when dealing with the parallel processing of the multiprocessing:

def foo():
    print('foo')
if __name__ == '__main__':
    foo()
    # rest of your code here

You can read more about the effects of parallelism here.

Time Management and Exhibition Functions

The HourGlass class offers functions to start, stop, and mark specific times during execution:

• start(): Starts the HourGlass.
• stop(): Stops the HourGlass.
• wait(): Freezes the main process while waiting for the Alarm process to terminate.

Example usage of the functions:

my_hg = HourGlass(seconds=60, visibility=True)
my_hg.start()
# Code to be timed
# More code
my_hg.stop()  # Stops the HourGlass and returns the total time

Post-initialized Attributes

Once started, you can access these values:

• status: Returns a boolean value according to its status.
• remaining_time: Returns a timedelta object (HH:MM:SS.ms) of the remaining time.
• remaining_seconds: Returns an int or float with the remaining time converted to seconds.
• pid: Returns an int value related to the parallel process identifier.

Comparisons and Real-world Impact

The HourGlass class allows developers and project managers to monitor the duration of various operations, ensuring that each segment of work is completed within the allocated time frame. By providing a visual and programmable representation of time, it aids in optimizing workflows, enhancing productivity, and maintaining a disciplined schedule.

When should I use HourGlass?

You can use HourGlass in the following situations:

• Limiting the execution time of certain functions or processes
• Controlling session or user access time
• Setting wait intervals in API requests or other interactions

Practical Example with HourGlass

Let's take a look at a practical example of applying HourGlass:

import multiprocessing
import psutil
from ptymer import HourGlass

def process_large_data():
    # Simulate a long-running data processing task
    limit = 10**100
    total_sum = 0
    for i in range(1, limit + 1):
        total_sum += i**2
    print(f"The sum of squares up to {limit} is {total_sum}")

def timeout_data(pid):
    # Kills data process
    print('Timeout on data processing! Aborting...')
    process = psutil.Process(pid)
    process.terminate()

if __name__ == "__main__":
    # Start the data processing in a separate process
    data_process = multiprocessing.Process(target=process_large_data)
    data_process.start()
    
    # Get the PID of the data process
    data_process_pid = data_process.pid

    # Initialize the HourGlass with 30 seconds
    hourglass = HourGlass(seconds=30, target=timeout_data, args=(data_process_pid,))
    
    # Start the HourGlass timer
    hourglass.start()
    
    # Wait for the data process to complete or be terminated by the HourGlass
    data_process.join()

In this example, the HourGlass class is used to limit the execution time of the data processing function to 30 seconds and, upon exceeding this limit, terminate it.