benchbuild.utils.wrapping module

Wrapper utilities for benchbuild.

This module provides methods to wrap binaries with extensions that are pickled alongside the original binary. In place of the original binary a new python module is generated that loads the pickle and redirects the program call with all its arguments to it. This allows interception of arbitrary programs for experimentation.

Examples

TODO

Compiler Wrappers:

The compiler wrappers substitute the compiler call with a script that produces the expected output from the original compiler call first. Afterwards the pickle is loaded and the original call is forwarded to the pickle. This way the user is not obligated to produce valid output during his own experiment.

Runtime Wrappers:

These directly forward the binary call to the pickle without any execution of the binary. We cannot guarantee that repeated execution is valid, therefore, we let the user decide what the program should do.

benchbuild.utils.wrapping.load(filename)

Load a pickled obj from the filesystem.

You better know what you expect from the given pickle, because we don’t check it.

Parameters:filename (str) – The filename we load the object from. Returns:The object we were able to unpickle, else None.

benchbuild.utils.wrapping.persist(id_obj, filename=None, suffix=None)

Persist an object in the filesystem.

This will generate a pickled version of the given obj in the filename path. Objects shall provide an id() method to be able to use this persistence API. If not, we will use the id() builtin of python to generate an identifier for you.

The file will be created, if it does not exist. If the file already exists, we will overwrite it.

Parameters:id_obj (Any) – An identifiable object you want to persist in the filesystem.

benchbuild.utils.wrapping.strip_path_prefix(ipath, prefix)

Strip prefix from path.

Parameters:

• ipath – input path
• prefix – the prefix to remove, if it is found in :ipath:

Examples

>>> strip_path_prefix("/foo/bar", "/bar")
'/foo/bar'
>>> strip_path_prefix("/foo/bar", "/")
'foo/bar'
>>> strip_path_prefix("/foo/bar", "/foo")
'/bar'
>>> strip_path_prefix("/foo/bar", "None")
'/foo/bar'

benchbuild.utils.wrapping.unpickle(pickle_file)

Unpickle a python object from the given path.

benchbuild.utils.wrapping.wrap(name, project, sprefix=None, python='/home/docs/checkouts/readthedocs.org/user_builds/pprof-study/envs/latest/bin/python')

Wrap the binary :name: with the runtime extension of the project.

This module generates a python tool that replaces :name: The function in runner only accepts the replaced binaries name as argument. We use the cloudpickle package to perform the serialization, make sure :runner: can be serialized with it and you’re fine.

Parameters:

• name – Binary we want to wrap
• project – The project that contains the runtime_extension we want to run instead of the binary.

Returns:

A plumbum command, ready to launch.

benchbuild.utils.wrapping.wrap_cc(filepath, compiler, project, python='/home/docs/checkouts/readthedocs.org/user_builds/pprof-study/envs/latest/bin/python', detect_project=False)

Substitute a compiler with a script that hides CFLAGS & LDFLAGS.

This will generate a wrapper script in the current directory and return a complete plumbum command to it.

Parameters:

• filepath (str) – Path to the wrapper script.
• compiler (benchbuild.utils.cmd) – Real compiler command we should call in the script.
• project (benchbuild.project.Project) – The project this compiler will be for.
• python (str) – Path to the python interpreter we should use.
• detect_project – Should we enable project detection or not.

Returns (benchbuild.utils.cmd):

Command of the new compiler we can call.

benchbuild.utils.wrapping.wrap_dynamic(project, name, sprefix=None, python='/home/docs/checkouts/readthedocs.org/user_builds/pprof-study/envs/latest/bin/python', name_filters=None)

Wrap the binary :name with the function :runner.

This module generates a python tool :name: that can replace a yet unspecified binary. It behaves similar to the :wrap: function. However, the first argument is the actual binary name.

Parameters:

• name – name of the python module
• runner – Function that should run the real binary
• sprefix – Prefix that should be used for commands.
• python – The python executable that should be used.
• name_filters –

  List of regex expressions that are used to filter the real project name. Make sure to include a match group named ‘name’ in the regex, e.g., [

  r’foo(?P<name>.)-flt’

  ]

Returns: plumbum command, readty to launch.