Defined in runner.hpp

Many of the classes in libsemigroups implementing the algorithms that are the reason for the existence of this library, 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).

Inheritance diagram for Runner:

[legend]

Public Types
enum class	state { never_run = 0 , running_to_finish = 1 , running_for = 2 , running_until = 3 , timed_out = 4 , stopped_by_predicate = 6 , not_running = 7 , dead = 8 }
	Enum class for the state of the Runner. More...

Public Types inherited from Reporter
using	nanoseconds = std::chrono::nanoseconds
	Alias for std::chrono::nanoseconds.

using	time_point = std::chrono::high_resolution_clock::time_point
	Alias for std::chrono::high_resolution_clock::time_point.

Public Member Functions
	Runner ()
	Default constructor.

	Runner (Runner &&other)
	Move constructor.

	Runner (Runner const &other)
	Copy constructor.

state	current_state () const noexcept
	Return the current state.

bool	dead () const noexcept
	Check if the runner is dead.

bool	finished () const
	Check if run has been run to completion or not.

Runner &	init ()
	Initialize an existing Runner object.

void	kill () noexcept
	Stop run from running (thread-safe).

Runner &	operator= (Runner &&other)
	Move assignment operator.

Runner &	operator= (Runner const &other)
	Copy assignment operator.

void	report_why_we_stopped () const
	Report why run stopped.

void	run ()
	Run until finished.

void	run_for (std::chrono::nanoseconds t)
	Run for a specified amount of time.

template<typename Time>
void	run_for (Time t)
	Run for a specified amount of time.

void	run_until (bool(*func)())
	Run until a nullary predicate returns `true` or finished.

template<typename Func>
void	run_until (Func &&func)
	Run until a nullary predicate returns `true` or finished.

bool	running () const noexcept
	Check if currently running.

bool	running_for () const noexcept
	Check if the runner is currently running for a particular length of time.

bool	running_until () const noexcept
	Check if the runner is currently running until a nullary predicate returns `true`.

bool	started () const noexcept
	Check if run has been called at least once before.

bool	stopped () const
	Check if the runner is stopped.

bool	stopped_by_predicate () const
	Check if the runner was stopped, or should stop, because of the argument last passed to run_until.

virtual bool	success () const
	Check if run has been run to completion successfully.

bool	timed_out () const
	Check if the amount of time passed to run_for has elapsed.

Public Member Functions inherited from Reporter
	Reporter ()
	Default constructor.

	Reporter (Reporter &&that)
	Default move constructor.

	Reporter (Reporter const &that)
	Default copy constructor.

void	emit_divider ()

Reporter &	init ()
	Initialize an existing Reporter object.

time_point	last_report () const noexcept
	Get the time point of the last report.

Reporter &	operator= (Reporter &&that)
	Default move assignment operator.

Reporter &	operator= (Reporter const &that)
	Default copy assignment operator.

bool	report () const
	Check if it is time to report.

std::string const &	report_divider () const noexcept

Reporter &	report_divider (std::string const &val)

nanoseconds	report_every () const noexcept
	Get the minimum elapsed time between reports.

Reporter &	report_every (nanoseconds val) noexcept
	Set the minimum elapsed time between reports in nanoseconds.

template<typename Time>
Reporter &	report_every (Time t) noexcept
	Set the minimum elapsed time between reports in a unit of time other than nanoseconds.

std::string const &	report_prefix () const noexcept
	Get the current prefix string for reporting.

Reporter &	report_prefix (std::string const &val)
	Set the prefix string for reporting.

Reporter const &	reset_last_report () const
	Set the last report time point to now.

Reporter const &	reset_start_time () const
	Reset the start time (and last report) to now.

time_point	start_time () const noexcept
	Get the start time.

Additional Inherited Members
Related Symbols inherited from Reporter
static std::chrono::nanoseconds	delta (std::chrono::high_resolution_clock::time_point const &t)
	The time between a given point and now.

Member Enumeration Documentation

◆ state

enum class state

strong

Enumerator
never_run	Indicates that none of run, run_for, or run_until has been called since construction or the last call to init.
running_to_finish	Indicates that the Runner is currently running to the finish (via run).
running_for	Indicates that the Runner is currently running for a specific amount of time (via run_for).
running_until	Indicates that the Runner is currently running until some condition is met (via run_until).
timed_out	Indicates that the Runner was run via run_for for a specific amount of time and that time has elapsed.
stopped_by_predicate	Indicates that the Runner was run via run_until until the condition specified by the argument to run_until was met.
not_running	Indicates that the Runner is not in any of the previous states and is not currently running. This can occur when, for example, run throws an exception.
dead	Indicates that the Runner was killed (by another thread).

Constructor & Destructor Documentation

◆ Runner() [1/3]

Runner ( )

Returns a runner that is not started, not finished, not dead, not timed out, will run FOREVER if not instructed otherwise, that last reported at the time of construction.

◆ Runner() [2/3]

Runner ( Runner const & other )

Returns a runner that is a copy of other. The state of the new runner is the same as other, except that the function passed as an argument to run_until (if any) is not copied.

Parameters

other the Runner to copy.

◆ Runner() [3/3]

Runner ( Runner && other )

Returns a runner that is initialised from other. The state of the new runner is the same as copy, except that the function passed as an argument to run_until (if any) is not copied.

Parameters

other the Runner to move from.

Member Function Documentation

◆ current_state()

state current_state ( ) const

inlinenodiscardnoexcept

Returns the current state of the Runner as given by state.

Returns: A value of type state.

Exceptions: This function is noexcept and is guaranteed never to throw.

Complexity: Constant.

◆ dead()

bool dead ( ) const

inlinenodiscardnoexcept

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

Returns: A bool.

Exceptions: This function is noexcept and is guaranteed never to throw.

See also: kill()

◆ finished()

bool finished ( ) const

nodiscard

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.

See also: started()

◆ init()

Runner & init ( )

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

Returns: A reference to *this.

Note: This function is not thread-safe.

See also: Runner()

◆ kill()

void kill ( )

inlinenoexcept

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

Exceptions: This function is noexcept and is guaranteed never to throw.

See also: finished()

◆ operator=() [1/2]

Runner & operator= ( Runner && other )

Returns a runner that is initialised from other. The state of the new runner is the same as copy, except that the function passed as an argument to run_until (if any) is not copied.

Parameters

other the Runner to move from.

◆ operator=() [2/2]

Runner & operator= ( Runner const & other )

Returns a runner that is initialised from other. The state of the new runner is the same as copy, except that the function passed as an argument to run_until (if any) is not copied.

Parameters

other the Runner to move from.

◆ report_why_we_stopped()

void report_why_we_stopped ( ) const

Reports whether run() was stopped because it is finished(), timed_out(), or dead().

◆ run()

void run ( )

Run the main algorithm implemented by a derived class of Runner.

◆ run_for() [1/2]

void run_for ( std::chrono::nanoseconds t )

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	the time in nanoseconds to run for.

See also: run_for(Time)

◆ run_for() [2/2]

template<typename Time>

void run_for ( Time t )

inline

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.

Template Parameters

Time	unit of time.

Parameters

t	the time to run for (in `Time`).

See also: run_for(std::chrono::nanoseconds)

◆ run_until() [1/2]

void run_until ( bool(* func )() )

inline

Parameters

func	a function pointer.

◆ run_until() [2/2]

template<typename Func>

void run_until ( Func && func )

Template Parameters

Func	the type of the argument.

Parameters

func	a callable type that will exist for at least until this function returns, or a function pointer.

◆ running()

bool running ( ) const

inlinenodiscardnoexcept

Returns true if run() is in the process of running and false it is not.

Returns: A bool.

Exceptions: This function is noexcept and is guaranteed never to throw.

See also: finished()

◆ running_for()

bool running_for ( ) const

inlinenodiscardnoexcept

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.

Exceptions: This function is noexcept and is guaranteed never to throw.

Complexity: Constant.

◆ running_until()

bool running_until ( ) const

inlinenodiscardnoexcept

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.

Exceptions: This function is noexcept and is guaranteed never to throw.

Complexity: Constant.

◆ started()

bool started ( ) const

inlinenodiscardnoexcept

Returns true if run() has started to run (it can be running or not).

Returns: A bool.

Exceptions: This function is noexcept and is guaranteed never to throw.

See also: finished()

◆ stopped()

bool stopped ( ) const

inlinenodiscard

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.

◆ stopped_by_predicate()

bool stopped_by_predicate ( ) const

inlinenodiscard

If this is running, then the nullary predicate is called and its return value is returned. If this is not running, then true is returned if and only if the last time this was running it was stopped by a call to the nullary predicate passed to run_until().

Returns: A bool.

Exceptions: This function guarantees not to throw a LibsemigroupsException.

Complexity: Constant.

◆ success()

virtual bool success ( ) const

inlinenodiscardvirtual

Returns true if run has been run to completion and it was successful. The default implementation is to just call finished.

Returns: A bool.

◆ timed_out()

bool timed_out ( ) const

inlinenodiscard

Returns: A bool

See also: run_for(std::chrono::nanoseconds) and run_for(Time).

The documentation for this class was generated from the following file:

/Users/jdm/libsemigroups/include/libsemigroups/runner.hpp

Public Types

Public Member Functions

Additional Inherited Members

Member Enumeration Documentation

◆ state

Constructor & Destructor Documentation

◆ Runner() [1/3]

◆ Runner() [2/3]

◆ Runner() [3/3]

Member Function Documentation

◆ current_state()

◆ dead()

◆ finished()

◆ init()

◆ kill()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ report_why_we_stopped()

◆ run()

◆ run_for() [1/2]

◆ run_for() [2/2]

◆ run_until() [1/2]

◆ run_until() [2/2]

◆ running()

◆ running_for()

◆ running_until()

◆ started()

◆ stopped()

◆ stopped_by_predicate()

◆ success()

◆ timed_out()