task::Step Class Reference

Detailed Description

A step is the main building block of a sequence.

Each step consists of a label, a script, and various other attributes. Steps can be of different types (see Step::Type) - for instance, "action" steps hold a script that can simply be executed, "if" steps hold a script that can be evaluated to determine if a condition is fulfilled, "end" steps mark the closing of a block in a sequence.

#include <Step.h>

Public Types
enum	Type {   type_action , type_if , type_else , type_elseif ,   type_end , type_while , type_try , type_catch }
	An enum for differentiating the different types of step. More...

Public Member Functions
	Step (Type type=type_action)
	Construct a Step of a certain type. More...
bool	execute (Context &context, CommChannel *comm_channel=nullptr, OptionalStepIndex opt_step_index=gul14::nullopt, TimeoutTrigger *sequence_timeout=nullptr)
	Execute the step script within the given context, sending status information to a message queue. More...
const VariableNames &	get_used_context_variable_names () const
	Retrieve the names of the variables that should be im-/exported to and from the context. More...
short	get_indentation_level () const noexcept
	Return the indentation level of this step. More...
const std::string &	get_label () const
	Return the label of the step. More...
const std::string &	get_script () const
	Return the script. More...
TimePoint	get_time_of_last_execution () const
	Return the timestamp of the last execution of this step's script. More...
TimePoint	get_time_of_last_modification () const
	Return the timestamp of the last modification of this step's script or label. More...
Timeout	get_timeout () const
	Return the timeout duration for executing the script. More...
Type	get_type () const noexcept
	Return the type of this step. More...
bool	is_running () const noexcept
	Return whether this step is currently being executed. More...
bool	is_disabled () const noexcept
	Return whether this step is currently disabled. More...
Step &	set_disabled (bool disable)
	Set whether the step should be disabled (or possibly executed). More...
Step &	set_indentation_level (short level)
	Set the indentation level of this step. More...
Step &	set_label (const std::string &label)
	Set the label. More...
Step &	set_running (bool is_running)
	Set whether the step should be marked as "currently running". More...
Step &	set_script (const std::string &script)
	Set the script that should be executed when this step is run. More...
Step &	set_time_of_last_execution (TimePoint t)
	Set the timestamp of the last execution of this step's script. More...
Step &	set_time_of_last_modification (TimePoint t)
	Set the timestamp of the last modification of this step's script or label. More...
Step &	set_timeout (Timeout timeout)
	Set the timeout duration for executing the script. More...
Step &	set_type (Type type)
	Set the type of this step. More...
Step &	set_used_context_variable_names (const VariableNames &used_context_variable_names)
	Set the names of the variables that should be im-/exported from/to the script. More...
Step &	set_used_context_variable_names (VariableNames &&used_context_variable_names)

Static Public Attributes
static constexpr short	max_indentation_level { 20 }
	Maximum allowed level of indentation (or nesting of steps) More...

Private Member Functions
void	copy_used_variables_from_context_to_lua (const Context &context, sol::state &lua)
	Copy the variables listed in used_context_variable_names_ from the given Context into a Lua state. More...
void	copy_used_variables_from_lua_to_context (const sol::state &lua, Context &context)
	Copy the variables listed in used_context_variable_names_ from a Lua state into the given Context. More...
bool	execute_impl (Context &context, CommChannel *comm_channel, OptionalStepIndex index, TimeoutTrigger *sequence_timeout)
	Execute the Lua script, throwing an exception if anything goes wrong. More...

Private Attributes
std::string	label_
std::string	script_
VariableNames	used_context_variable_names_
TimePoint	time_of_last_modification_ { Clock::now() }
TimePoint	time_of_last_execution_
Timeout	timeout_
Type	type_ { type_action }
short	indentation_level_ { 0 }
bool	is_running_ { false }
bool	is_disabled_ { false }

Member Enumeration Documentation

Type

enum task::Step::Type

An enum for differentiating the different types of step.

Enumerator
type_action
type_if
type_else
type_elseif
type_end
type_while
type_try
type_catch

Constructor & Destructor Documentation

Step()

task::Step::Step ( Type  type = type_action )

inlineexplicit

Construct a Step of a certain type.

Member Function Documentation

copy_used_variables_from_context_to_lua()

void task::Step::copy_used_variables_from_context_to_lua ( const Context &  context, sol::state &  lua  )

private

Copy the variables listed in used_context_variable_names_ from the given Context into a Lua state.

References task::Context::variables.

copy_used_variables_from_lua_to_context()

void task::Step::copy_used_variables_from_lua_to_context ( const sol::state &  lua, Context &  context  )

private

Copy the variables listed in used_context_variable_names_ from a Lua state into the given Context.

References task::Context::variables.

execute()

bool task::Step::execute	(	Context &	context,
		CommChannel *	comm_channel = nullptr,
		OptionalStepIndex	opt_step_index = gul14::nullopt,
		TimeoutTrigger *	sequence_timeout = nullptr
	)

Execute the step script within the given context, sending status information to a message queue.

This function performs the following steps:

1. A fresh script runtime environment is prepared and safe library components are loaded into it.
2. The step_setup_function from the context is run if it is defined (non-null).
3. The step setup script is run.
4. Selected variables are imported from the context into the runtime environment.
5. The script from the step is loaded into the runtime environment and executed.
6. Selected variables are exported from the runtime environment back into the context.

Certain step types (IF, ELSEIF, WHILE) require the script to return a boolean value. Not returning a value or returning a different type is considered an error. Conversely, the other step types (ACTION etc.) do not allow returning values from the script, with the exception of nil.

Parameters

context	The context to be used for executing the step
comm_channel	Pointer to a communication channel; If this is null, messaging is disabled and there is no way to stop the execution. Otherwise, termination requests are honored and the queue receives the following messages: A message of type step_started when the step is started A message of type step_stopped when the step has finished successfully A message of type step_stopped_with_error when the step has been stopped due to an error condition
opt_step_index	Optional index of the step in its parent Sequence (to be used in exceptions and messages)
sequence_timeout	Pointer to a sequence timeout to determine a timeout during executing a step. If this is null the corresponding check for timeout is omitted.

Returns

If the step type requires a boolean return value (IF, ELSEIF, WHILE), this function returns the return value of the script. For other step types (ACTION etc.), it returns false.

Exceptions

Error

is thrown if the script cannot be started, if there is a Lua error during execution, if the script has an inappropriate return value for the step type (see above), if a timeout is encountered, or if termination has been requested via the communication channel or explicitly by the script.

See also

For more information about step setup scripts see at Sequence.

References task::remove_abort_markers(), task::requires_bool_return_value(), and task::send_message().

execute_impl()

bool task::Step::execute_impl ( Context &  context, CommChannel *  comm_channel, OptionalStepIndex  index, TimeoutTrigger *  sequence_timeout  )

private

Execute the Lua script, throwing an exception if anything goes wrong.

See also

execute(Context&, CommChannel*, OptionalStepIndex, TimeoutTrigger*)

References task::execute_lua_script(), task::executes_script(), task::install_custom_commands(), task::install_timeout_and_termination_request_hook(), task::open_safe_library_subset(), task::requires_bool_return_value(), task::Context::step_setup_function, task::Context::step_setup_script, and task::to_string().

get_indentation_level()

short task::Step::get_indentation_level ( ) const

inlinenoexcept

Return the indentation level of this step.

Zero indicates a top-level step and each additional level stands for one level of nesting inside a block statement such as IF, WHILE, CATCH, and so on.

References indentation_level_.

Referenced by task::Sequence::enforce_consistency_of_disabled_flags().

get_label()

const std::string& task::Step::get_label ( ) const

inline

Return the label of the step.

Note

This function returns a reference to an internal member variable, so be aware of lifetime implications.

References label_.

Referenced by task::operator<<().

get_script()

const std::string& task::Step::get_script ( ) const

inline

Return the script.

Note

This function returns a reference to an internal member variable, so be aware of lifetime implications:

Step my_step;
 
// Safe, string is copied
std::string str = my_step.get_script();
 
// Fast, but str_ref will dangle if my_step goes out of scope
const std::string& str_ref = my_step.get_script();

References script_.

Referenced by task::operator<<().

get_time_of_last_execution()

TimePoint task::Step::get_time_of_last_execution ( ) const

inline

Return the timestamp of the last execution of this step's script.

A default-constructed TimePoint{} is returned to indicate that the object was never executed since its creation.

References time_of_last_execution_.

Referenced by task::operator<<().

get_time_of_last_modification()

TimePoint task::Step::get_time_of_last_modification ( ) const

inline

Return the timestamp of the last modification of this step's script or label.

A default-constructed TimePoint{} is returned to indicate that the object was never modified since its creation.

References time_of_last_modification_.

Referenced by task::operator<<().

get_timeout()

Timeout task::Step::get_timeout ( ) const

inline

Return the timeout duration for executing the script.

References timeout_.

Referenced by task::operator<<().

get_type()

Type task::Step::get_type ( ) const

inlinenoexcept

Return the type of this step.

References type_.

Referenced by task::operator<<().

get_used_context_variable_names()

const VariableNames& task::Step::get_used_context_variable_names ( ) const

inline

Retrieve the names of the variables that should be im-/exported to and from the context.

The variables with the listed names are imported from the context into the script environment before running the script and are afterwards exported back into it.

Note

This function returns a reference to an internal member variable, so be aware of lifetime implications.

References used_context_variable_names_.

Referenced by task::operator<<().

is_disabled()

bool task::Step::is_disabled ( ) const

inlinenoexcept

Return whether this step is currently disabled.

References is_disabled_.

Referenced by task::operator<<().

is_running()

bool task::Step::is_running ( ) const

inlinenoexcept

Return whether this step is currently being executed.

This flag is normally set by an Executor.

References is_running_.

set_disabled()

Step & task::Step::set_disabled

(

bool

disable

)

Set whether the step should be disabled (or possibly executed).

Referenced by task::Sequence::enforce_consistency_of_disabled_flags().

set_indentation_level()

Step & task::Step::set_indentation_level

(

short

level

)

Set the indentation level of this step.

Parameters

level

New indentation level; Zero indicates a top-level step and each additional level stands for one level of nesting inside a block statement such as IF, WHILE, CATCH, and so on.

Exceptions

Error

is thrown if level < 0 or level > max_indentation_level.

set_label()

Step & task::Step::set_label

(

const std::string &

label

)

Set the label.

This call also updates the time of last modification to the current system time.

Labels must not start or end with whitespace; existing whitespace is silently removed.

set_running()

Step & task::Step::set_running

(

bool

is_running

)

Set whether the step should be marked as "currently running".

This is normally done by an Executor.

Referenced by task::Executor::update().

set_script()

Step & task::Step::set_script

(

const std::string &

script

)

Set the script that should be executed when this step is run.

Syntax or semantics of the script are not checked.

Referenced by task::operator>>().

set_time_of_last_execution()

Step & task::Step::set_time_of_last_execution

(

TimePoint

t

)

Set the timestamp of the last execution of this step's script.

This function should be called when an external execution engine starts the embedded script or when the Step has been restored from serialized form.

set_time_of_last_modification()

Step & task::Step::set_time_of_last_modification

(

TimePoint

t

)

Set the timestamp of the last modification of this step's script or label.

This function is only useful to restore a step from some serialized form, e.g. from a file.

Referenced by task::operator>>().

set_timeout()

Step & task::Step::set_timeout

(

Timeout

timeout

)

Set the timeout duration for executing the script.

Referenced by task::operator>>().

set_type()

Step & task::Step::set_type

(

Type

type

)

Set the type of this step.

This call also updates the time of last modification to the current system time.

set_used_context_variable_names() [1/2]

Step & task::Step::set_used_context_variable_names

(

const VariableNames &

used_context_variable_names

)

Set the names of the variables that should be im-/exported from/to the script.

set_used_context_variable_names() [2/2]

Step & task::Step::set_used_context_variable_names

(

VariableNames &&

used_context_variable_names

)

Member Data Documentation

indentation_level_

short task::Step::indentation_level_ { 0 }

private

Referenced by get_indentation_level().

is_disabled_

bool task::Step::is_disabled_ { false }

private

Referenced by is_disabled().

is_running_

bool task::Step::is_running_ { false }

private

Referenced by is_running().

label_

std::string task::Step::label_

private

Referenced by get_label().

max_indentation_level

constexpr short task::Step::max_indentation_level { 20 }

staticconstexpr

Maximum allowed level of indentation (or nesting of steps)

Referenced by task::Sequence::indent().

script_

std::string task::Step::script_

private

Referenced by get_script().

time_of_last_execution_

TimePoint task::Step::time_of_last_execution_

private

Referenced by get_time_of_last_execution().

time_of_last_modification_

TimePoint task::Step::time_of_last_modification_ { Clock::now() }

private

Referenced by get_time_of_last_modification().

timeout_

Timeout task::Step::timeout_

private

Referenced by get_timeout().

type_

Type task::Step::type_ { type_action }

private

Referenced by get_type().

used_context_variable_names_

VariableNames task::Step::used_context_variable_names_

private

Referenced by get_used_context_variable_names().

---

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

• Step.h
• Step.cc