pysys.utils.threadutils

Contains the BackgroundThread class and other utilities for working with threads.

BackgroundThread

class pysys.utils.threadutils.BackgroundThread(owner, name, target, kwargsForTarget)[source]

Bases: object

PySys wrapper for a background thread that can receive requests to stop, and can send log output to the same place as the test’s logging.

To create a background thread in your test, use pysys.basetest.BaseTest.startBackgroundThread.

Variables

  • ~.name (str) – The name specified for this thread when it was created.

  • ~.joinTimeoutSecs (int) – The default timeout that will be used for joining this thread. If not explicitly set this will be TIMEOUTS['WaitForProcessStop'].

  • ~.exception (Exception) – The exception object raised by the thread if it has terminated with an error, or None if not.

isAlive()[source]
Returns

True if this thread is still running.

Return type

bool

stop()[source]

Requests the thread to stop by setting the stopping event which the thread ought to be checking regularly.

This method returns immediately; if you wish to wait for the thread to terminate, call join afterwards. Calling this repeatedly has no effect.

Returns

This instance, in case you wish to do fluent method chaining.

Return type

BackgroundThread

join(timeout=None, abortOnError=False)[source]

Wait until this thread terminates, and adds a TIMEDOUT or BLOCKED outcome to the owner test if it times out or raises an exception.

If you wish to request the thread to terminate rather than waiting for it to reach the end of its target function on its own, call stop before joining the thread.

If a join times out, the thread is automatically requested to stop as soon as possible.

Note that if the thread raises an Exception after it was requested to stop this is logged but does not result in a failure outcome, since failures during cleanup are usually to be expected.

Parameters

  • timeout – The time in seconds to wait. Usually this should be left at the default value of None which uses a default timeout of constants.TIMEOUTS['WaitForProcessStop']. Note that unlike Python’s Thread.join method, infinite timeouts are not supported.

  • abortOnError – Set to True if you wish this method to immediately abort with an exception if the background thread times out or raises an Exception. The default is False, which adds the failure outcome but does not raise an exception.

createThreadInitializer

pysys.utils.threadutils.createThreadInitializer(owner)[source]

Creates a no-args initializer function that should be called at the start of a new thread created outside the PySys framework to configure logging and thread name for the specified test/runner owner.

This function is needed because if a new thread is created without PySys helper methods (such as pysys.basetest.BaseTest.startBackgroundThread) then logging from that thread will not go to the test’s run.log output file which can make debugging quite difficult.

New in version 2.2.