Actions

Actions are used to declare the workflow of an experiment. BenchBuild provides a set of default actions that should suit most experiments. A new experiment can define a new set of actions that should be used per project, or use those defaults.

Customize actions

Whenever you define a new expeirment, you have to provide an implementation for def actions_for_project(self, project: 'Project'). This implementation usually configures extensions on the project and returns a set of actions that should be run during execution.

Example:

This takes care of compiling, running and cleanup during experiment execution.

Available Actions

The following actions are available out of the box. You can define your own actions at any time

Step (Base)

Clean

MakeBuildDir

Compile

Run

Echo

Any (Group)

Experiment (Any, Group)

RequireAll (Group)

CleanExtra

ProjectEnvironment

SetProjectVersion

This action provides you with a way to change the source version used inside the build directory of this project. During initialization, each project is assigned a variant that determines the source versions that will be checked out into the build directory.

Sometimes it can be useful to do comparisons of different source revisions inside a single experiment run. This can be achieved using SetProjectVersion.

Usage:

The match is done on all(!) sources of the project. If you happen to find a revision string twice in different souces, both will be checked out in the build directory.

The match is done exact and matches agains the source.versions() output of a source. Only sources that are marked as expandable (source.is_expandable) will be checked.

# Actions

Actions are enhanced callables that are used by Experiments to define the order of operations a project is put through when the experiment executes.

## Example

TODO `python `

class benchbuild.utils.actions.Any(actions=None)

Bases: MultiStep

DESCRIPTION: ClassVar[str] = 'Just run all actions, no questions asked.'

NAME: ClassVar[str] = 'ANY'

class benchbuild.utils.actions.Clean(project, check_empty=False)

Bases: ProjectStep

DESCRIPTION: tp.ClassVar[str] = 'Cleans the build directory'

NAME: tp.ClassVar[str] = 'CLEAN'

static clean_mountpoints(root)

Unmount any remaining mountpoints under :root.

Parameters:

root (str) – All UnionFS-mountpoints under this directory will be unmounted.

Return type:

None

class benchbuild.utils.actions.CleanExtra

Bases: Step

DESCRIPTION: ClassVar[str] = 'Cleans the extra directories.'

NAME: ClassVar[str] = 'CLEAN EXTRA'

class benchbuild.utils.actions.Compile(project)

Bases: ProjectStep

DESCRIPTION: tp.ClassVar[str] = 'Compile the project'

NAME: tp.ClassVar[str] = 'COMPILE'

class benchbuild.utils.actions.Echo(message='')

Bases: Step

DESCRIPTION: ClassVar[str] = 'Print a message.'

NAME: ClassVar[str] = 'ECHO'

message: str

class benchbuild.utils.actions.Experiment(experiment, actions)

Bases: Any

DESCRIPTION: tp.ClassVar[str] = 'Run a experiment, wrapped in a db transaction'

NAME: tp.ClassVar[str] = 'EXPERIMENT'

begin_transaction()

Return type:

tp.Tuple[‘benchbuild.utils.schema.Experiment’, tp.Any]

static end_transaction(experiment, session)

Return type:

None

experiment: benchbuild.experiment.Experiment

class benchbuild.utils.actions.MakeBuildDir(project)

Bases: ProjectStep

DESCRIPTION: tp.ClassVar[str] = 'Create the build directory'

NAME: tp.ClassVar[str] = 'MKDIR'

class benchbuild.utils.actions.MultiStep(actions=None)

Bases: Step, Generic[StepTy_co]

Group multiple actions into one step.

Usually used to define behavior on error, e.g., execute everything regardless of any errors, or fail everything upon first error.

DESCRIPTION: ClassVar[str] = ''

NAME: ClassVar[str] = ''

actions: MutableSequence[TypeVar(StepTy_co, bound= Step, covariant=True)]

onerror()

Default implementation does nothing.

Return type:

None

class benchbuild.utils.actions.ProjectEnvironment(project)

Bases: ProjectStep

DESCRIPTION: tp.ClassVar[str] = 'Prepare the project environment.'

NAME: tp.ClassVar[str] = 'ENV'

class benchbuild.utils.actions.ProjectStep(project)

Bases: Step

Base class of a project step.

Adds a project attribute to the Step base class and some defaults.

Raises:

StopIteration – If we do not encapsulate more substeps.

DESCRIPTION: tp.ClassVar[str] = ''

NAME: tp.ClassVar[str] = ''

onerror()

Default implementation does nothing.

Return type:

None

project: benchbuild.project.Project

class benchbuild.utils.actions.RequireAll(actions=None)

Bases: MultiStep

DESCRIPTION: ClassVar[str] = 'All child steps need to succeed'

NAME: ClassVar[str] = 'REQUIRE ALL'

class benchbuild.utils.actions.Run(project, experiment)

Bases: ProjectStep

DESCRIPTION: tp.ClassVar[str] = 'Execute the run action'

NAME: tp.ClassVar[str] = 'RUN'

experiment: benchbuild.experiment.Experiment

class benchbuild.utils.actions.RunWorkload(project, workload=None)

Bases: ProjectStep

DESCRIPTION: tp.ClassVar[str] = "Run a project's workload"

NAME: tp.ClassVar[str] = 'RUN WORKLOAD'

property workload_ref: Callable[[], Any]

class benchbuild.utils.actions.RunWorkloads(project, experiment, run_only=None)

Bases: MultiStep

DESCRIPTION: tp.ClassVar[str] = 'Generic run all project workloads'

NAME: tp.ClassVar[str] = 'RUN WORKLOADS'

experiment: benchbuild.experiment.Experiment

project: benchbuild.project.Project

class benchbuild.utils.actions.SetProjectVersion(project, *revision_strings)

Bases: ProjectStep

DESCRIPTION: tp.ClassVar[str] = 'Checkout a project version'

NAME: tp.ClassVar[str] = 'SET PROJECT VERSION'

revision: source.Revision

class benchbuild.utils.actions.Step(status)

Bases: object

Base class of a step.

Raises:

StopIteration – If we do not encapsulate more substeps.

DESCRIPTION: ClassVar[str] = ''

NAME: ClassVar[str] = ''

onerror()

Default implementation does nothing.

Return type:

None

status: StepResult

class benchbuild.utils.actions.StepResult(value)

Bases: IntEnum

Result type for action results.

CAN_CONTINUE = 2

ERROR = 3

OK = 1

UNSET = 0

benchbuild.utils.actions.log_before_after(name, desc)

Log customized string before & after running func.

Return type:

Callable[[Callable[..., StepResult]], Callable[..., StepResult]]

benchbuild.utils.actions.prepend_status(func)

Prepends the output of func with the status.

Return type:

Callable[..., str]

benchbuild.utils.actions.run_any_child(child)

Execute child step.

Parameters:

child (Step) – The child step.

Return type:

StepResult

benchbuild.utils.actions.step_has_failed(result, error_status=None)

Return type:

bool