utils.timing_util module

class utils.timing_util.TimestampManager

Bases: object

Service class that collects and manages timestamps and time measurements for several clients.

Clients are identified by IDs. A client can set timestamps and start or stop time measurements. Each timestamp or measurement can store a message string containing information about its purpose.

The class also provides functionality for formatted output of the collected data or computing basic statistics.

timestamp(client_id, msg='', set_duration=False)

Creates and stores a new timestamp for a client with a given ID.

If no client with the provided ID exists, a new collector is created for the ID. All timestamps and measurements with this ID will thereafter be collected by that collector.

The timestamp can optionally contain a duration value, which will be computed as the time difference to the most previous timestamp. This will not work if there is no previous timestamp.

Parameters:
  • client_id (str) – The ID of the client.
  • msg (str, optional) – The message to be stored in the timestamp. Default value is “”.
  • set_duration (bool, optional) – Set duration of timestamp to the time difference to the previous timestamp. Default is False.
tic(client_id, msg=None)

Creates a new single-use time measurement starting point for a client with the given ID.

Single-use measurement points will be stacked to allow for nested time measurements. The first point ever created for a client will persist however and behave much like a permanent measurement point without an ID.

Example

The indentation levels in this scheme mark the measurement point associations:

tic()
    tic()
    ...
    toc()
toc()
toc()

If no collector for the given client_id exists, a new collector will be assigned to the ID. A message string can be specified to simultaneously create a new timestamp for the client.

Parameters:
  • client_id (str) – The ID of the client.
  • msg (str, optional) – The message text of the optional timestamp. If no message is specified, no timestamp will be created. Default value is None.
toc(client_id, msg='')

Creates a new timestamp representing a measurement corresponding to the last single-use measurement point.

If this measurement point is not the very first of the client’s collector, it is removed from the stack. The duration of the timestamp will be set to None if there is no single-use measurement point.

Parameters:
  • client_id (str) – The ID of the client.
  • msg (str, optional) – The message text of the timestamp. Default value is “”.
Raises:

KeyError – If no collector for the specified client_id exists.
clearTics(client_id)

Removes all single-use time measurement points from the collector of the client with the given ID.

Parameters:client_id (str) – The ID of the client.
Raises:KeyError – If no collector for the specified client_id exists
setTimerStart(client_id, measurement_id=None, msg=None)

Creates a permanent time measurement point for the client with the given ID.

Each time measurement point has a unique ID. If the specified measurement_id is already present in the client’s collector, it will be replaced by a new one.

If the optional msg parameter is set, a timestamp will be created aswell. If no collector for the given client_id exists, a new collector will be assigned to the ID.

Parameters:
  • client_id (str) – The ID of the client.
  • measurement_id (str, optional) – Unique identifier for the measurement point. Default value is None.
  • msg (str, optional) – The message text of the optional timestamp. If no message is specified, no timestamp will be created. Default value is None.
measureTime(client_id, measurement_id=None, msg='')

Creates a new timestamp for the client with the given client_id that represents a time measurement.

Parameters:
  • client_id (str) – The ID of the client.
  • measurement_id (str, optional) – The ID of the measurement point. Default value is None.
  • msg (str, optional) – The message text of the timestamp. Default value is “”.
Raises:

KeyError – If there is no collector for the client with the given client_id or the collector has no permanent measurement point with the given measurement_id.
getTimestamps(client_id, pattern='')

Returns a list of all timestamps belonging to the given client with messages that match the given pattern. The pattern can be left empty to include all timestamps.

Parameters:
  • client_id (str) – The ID of the client.
  • pattern (str, optional) – Pattern to match in timestamp messages. Is not used if empty. Default value is "".
Returns:

A list of Timestamps with messages matching pattern.
Return type:

list of Timestamp
Raises:
  • KeyError – If ther is no collector for the client with the given
  • client_id.
class utils.timing_util.TimestampCollector(client_id)

Bases: object

Container class for timestamps of a single client.

Parameters:client_id (str) – ID of the client associated to this TimestampCollector.
timestamp(t, msg, set_duration)

Creates and collects a new timestamp.

Parameters:
  • t (float) – The time for which to create the timestamp.
  • msg (str) – The message to store in the timestamp.
  • set_duration (bool) – Try to set duration to time difference to previous timestamp if True, otherwise set duration to None.
tic(t)

Pushes a new time measurement point on the tic stack.

Parameters:t (float) – The time of the measurement point.
toc(t, msg)

Creates a new time measurement timestamp using the tic stack as measurement point provider.

The top measurement point of the stack will be used as reference point and deleted if it is not the only element on the stack.

Parameters:
  • t (float) – The second time of the time measurement.
  • msg (str) – The message to store in the timestamp.
clearTics()

Resets the tic stack.

setTimerStart(t, client_id)

Sets the permanent time measurement point with the given client_id to the given time t.

measureTime(t, client_id, msg)

Creates a new timestamp representing a time measurement starting at a permanent measurement point.

The duration attribute of the timestamp is computed as the difference between the current time t and the time of the measurement point with the specified client_id.

Parameters:
  • t (float) – The current time.
  • client_id (str) – The ID of the time measurement point.
  • msg (str) – The message to store in the timestamp.
Raises:

KeyError – If there is no permanent time measurement point with the specified client_id.
timestamps