The Runner class

Abstract class for derived [1] classes that run an algorithm.

Many of the classes in libsemigroups_pybind11 implementing the algorithms, that are the reason for the existence of this package, are derived from Runner. The Runner class exists to collect various common tasks required by such a derived class with a possibly long running run. These common tasks include:

running for a given amount of time (run_for)
running until a nullary predicate is true (run_until)
checking the status of the algorithm: has it started ? finished? been killed by another thread (dead)? has it timed out (timed_out)? has it stopped for any reason?
permit the function run to be killed from another thread (kill).

Because Runner is an abstract class it is not possible to create instances of Runner except via a derived class.

This class inherits from Reporter.

Important

The classes that we claim derive from Runner in this documentation have all the methods of the Runner class but, for boring technical reasons, are not formally subclasses of Runner. If thing is an instance of a class derived from Runner, then you can use thing as if it were an instance of Runner but isinstance(thing, Runner) will return False.

Footnotes

Contents

`Runner`	Abstract class for derived [1] classes that run an algorithm.
`Runner.current_state`(…)	Return the current state.
`Runner.dead`(…)	Check if the runner is dead.
`Runner.finished`(…)	Check if run has been run to completion or not.
`Runner.init`(…)	Initialize an existing Runner object.
`Runner.kill`(…)	Stop run from running (thread-safe).
`Runner.report_why_we_stopped`(…)	Report why run stopped.
`Runner.run`(…)	Run until finished.
`Runner.run_for`(…)	Run for a specified amount of time.
`Runner.run_until`(…)	Run until a nullary predicate returns true or finished.
`Runner.running`(…)	Check if currently running.
`Runner.running_for`(…)	Check if the runner is currently running for a particular length of time.
`Runner.running_until`(…)	Check if the runner is currently running until a nullary predicate returns true.
`Runner.started`(…)	Check if run has been called at least once before.
`Runner.stopped`(…)	Check if the runner is stopped.
`Runner.stopped_by_predicate`(…)	Check if the runner was stopped, or should stop, because of the argument last passed to run_until.
`Runner.success`(…)	Check if run has been run to completion successfully.
`Runner.timed_out`(…)	Check if the amount of time passed to run_for has elapsed.

Full API

class Runner

current_state(self: Runner) → Runner.state

Return the current state.

This function returns the current state of the Runner as given by state.

Returns:: A value of type state.
Return type:: Runner.state
Complexity:: Constant.

dead(self: Runner) → bool

Check if the runner is dead. This function can be used to check if we should terminate run() because it has been killed by another thread.

Returns:: A bool.
Return type:: bool

See also

kill()

finished(self: Runner) → bool

Check if run has been run to completion or not.

This function returns True if run() has been run to completion. For this to work, the implementation of run() in a derived class of Runner must implement a specialisation of finished_impl.

Returns:: A bool.
Return type:: bool

See also

started()

init(self: Runner) → Runner

Initialize an existing Runner object.

This function puts a Runner object back into the same state as if it had been newly default constructed.

Returns:: self.
Return type:: Runner

See also

Runner()

kill(self: Runner) → None: Stop run from running (thread-safe). This function can be used to terminate run() from another thread. After kill() has been called the Runner may no longer be in a valid state, but will return True from dead().

See also

finished()

report_why_we_stopped(self: Runner) → None: Report why run stopped. Reports whether run() was stopped because it is finished(), timed_out(), or dead().

run(self: Runner) → None: Run until finished. Run the main algorithm implemented by a derived class of Runner.

run_for(self: Runner, t: datetime.timedelta) → None

Run for a specified amount of time.

For this to work it is necessary to periodically check if timed_out() returns True, and to stop if it is, in the run() member function of any derived class of Runner.

Parameters:: t (datetime.timedelta) – the time to run for.

See also

run_for

run_until(self: Runner, func: collections.abc.Callable[[], bool]) → None

Run until a nullary predicate returns true or finished.

Parameters:: func (collections.abc.Callable[[], bool]) – a nullary function that will be used to determine when to stop running.

running(self: Runner) → bool

Check if currently running.

This function returns True if run() is in the process of running and False it is not.

Returns:: Whether or not the runner is running.
Return type:: bool

See also

finished()

running_for(self: Runner) → bool

Check if the runner is currently running for a particular length of time. If the Runner is currently running because its member function run_for has been invoked, then this function returns True. Otherwise, False is returned.

Returns:: A bool.
Return type:: bool
Complexity:: Constant.

running_until(self: Runner) → bool

Check if the runner is currently running until a nullary predicate returns true. If the Runner is currently running because its member function run_until has been invoked, then this function returns True. Otherwise, False is returned.

Returns:: A bool.
Return type:: bool
Complexity:: Constant.

started(self: Runner) → bool

Check if run has been called at least once before.

This function returns True if run() has started to run (it can be running or not).

Returns:: A bool.
Return type:: bool

See also

finished()

stopped(self: Runner) → bool

Check if the runner is stopped. This function can be used to check whether or not run() has been stopped for whatever reason. In other words, it checks if timed_out(), finished(), or dead().

Returns:: A bool.
Return type:: bool

stopped_by_predicate(self: Runner) → bool

Check if the runner was stopped, or should stop, because of the argument last passed to run_until. If self is running, then the nullary predicate is called and its return value is returned. If self is not running, then True is returned if and only if the last time self was running it was stopped by a call to the nullary predicate passed to run_until().

Returns:: A bool.
Return type:: bool
Complexity:: Constant.

success(self: Runner) → bool

Check if run has been run to completion successfully.

This function returns True if run() has been run to completion and it was successful.

Returns:: Whether or not run was successful or not.
Return type:: bool

See also

started()

timed_out(self: Runner) → bool

Check if the amount of time passed to run_for has elapsed.

Returns:: Whether or not run_for timed out.
Return type:: bool

See also

run_for.