loki.batch.configure

Classes

ItemConfig(config)	Item-specific configuration settings.
PipelineConfig(name[, transformations])	Configuration object for custom Pipeline instances that can be used to create pipelines from other transformations stored in the config.
SchedulerConfig(default, routines[, ...])	Configuration object for the Scheduler
TransformationConfig(name, module[, ...])	Configuration object for Transformation instances that can be used to create Transformation objects from dictionaries or a config file.

class SchedulerConfig(default, routines, disable=None, dimensions=None, transformation_configs=None, pipeline_configs=None, enable_imports=False, frontend_args=None)

Bases: object

Configuration object for the Scheduler

It encapsulates config options for scheduler behaviour, with default options and item-specific overrides, as well as transformation-specific parameterisations.

The SchedulerConfig can be created either from a raw dictionary or configuration file.

defaultdict

Default options for each item

routinesdict of dicts or list of dicts

Dicts with routine-specific options.

dimensionsdict of dicts or list of dicts

Dicts with options to define Dimension objects.

disablelist of str

Subroutine names that are entirely disabled and will not be added to either the callgraph that we traverse, nor the visualisation. These are intended for utility routines that pop up in many routines but can be ignored in terms of program control flow, like flush or abort.

enable_imports : bool

 Disable the inclusion of module imports as scheduler dependencies.

transformation_configsdict

Dicts with transformation-specific options

frontend_argsdict

Dicts with file-specific frontend options

classmethod from_dict(config)

classmethod from_file(path)

static match_item_keys(item_name, keys, use_pattern_matching=False, match_item_parents=False)

Helper routine to match an item name against config keys.

The item_name may be a fully-qualified name of an Item, which may include a scope, or only a partial, e.g., local name part. This is then compared against a provided list of keys as they may appear in a config property (for example an ignore or disable list).

By default, the fully qualified name and the local name are matched. Optionally, the matching can be be extended to parent scopes in the item name, which is particularly useful if, e.g., the item name of a module member is checked against an exclusion list, which lists the module name. This is enabled via match_item_parents.

The matching can take patterns in the keys into account, allowing for the pattern syntax supported by fnmatch. This requires enabling use_pattern_matching.

Parameters:

• item_name (str) – The item name to check for matches

• keys (list of str) – The config key values to check for matches

• use_pattern_matching (bool, optional) – Allow patterns in keys when matching (default False)

• match_item_parents (bool, optional) – Match also name parts of parent scopes in item_name

Returns:

The entries in keys that item_name matched

Return type:

tuple of str

create_item_config(name)

Create the bespoke config dict for an Item

The resulting config object contains the default values and any item-specific overwrites and additions.

create_frontend_args(path, default_args)

Create bespoke frontend_args to pass to the constructor or make_complete method for a file

The resulting dict contains overwrites that have been provided in the frontend_args of the config.

Parameters:

• path (str or pathlib.Path) – The file path for which to create the frontend arguments. This can be a fully-qualified path or include fnmatch-compatible patterns.

• default_args (dict) – The default options to use. Only keys that are explicitly overriden for the file in the scheduler config are updated.

Returns:

The frontend arguments, with file-specific overrides of default_args if specified in the Scheduler config.

Return type:

dict

is_disabled(name)

Check if the item with the given name is marked as disabled

class TransformationConfig(name, module, classname=None, path=None, options=None)

Bases: object

Configuration object for Transformation instances that can be used to create Transformation objects from dictionaries or a config file.

Parameters:

• name (str) – Name of the transformation object

• module (str) – Python module from which to load the transformation class

• classname (str, optional) – Name of the class to look for when instantiating the transformation. If not provided, name will be used instead.

• path (str or Path, optional) – Path to add to the sys.path before attempting to load the module

• options (dict) – Dicts of options that define the transformation behaviour. These options will be passed as constructor arguments using keyword-argument notation.

resolve_dimensions(dimensions)

Substitute Dimension objects for placeholder strings.

The format of the string replacement matches the TOML configuration. It will attempt to replace %dimensions.dim_name% with a Dimension found in dimensions:

Parameters:

dimensions (dict) – Dict matching string to pre-configured Dimension objects.

instantiate()

Creates instantiated Transformation object from stored config options.

class PipelineConfig(name, transformations=None)

Bases: object

Configuration object for custom Pipeline instances that can be used to create pipelines from other transformations stored in the config.

Parameters:

• name (str) – Name of the transformation object

• transformations (list of str) – List of transformation names for which to look when instnatiating thie pipeline.

instantiate(transformation_map=None)

Creates a custom Pipeline object from instantiated Transformation or Pipeline objects in the given map.

class ItemConfig(config)

Bases: object

Item-specific configuration settings.

This is filled by inheriting values from SchedulerConfig.default and applying explicit specialisations provided for an item in the config file or dictionary.

role

Role in the transformation chain, typically 'driver' or 'kernel'

Type:

str or None

mode

Transformation “mode” to pass to transformations applied to the item

Type:

str or None

expand

Flag to enable/disable expansion of children under this node

Type:

bool (default: False)

strict

Flag controlling whether to fail if dependency items cannot be found

Type:

bool (default: True)

replicate

Flag indicating whether to mark item as “replicated” in call graphs

Type:

bool (default: False)

disable

List of dependency names that are completely ignored and not reported as dependencies by the item. Useful to exclude entire call trees or utility routines.

Type:

tuple

block

List of dependency names that should not be added to the scheduler graph as dependencies and are not processed as targets. Note that these might still be shown in the graph visualisation.

Type:

tuple

ignore

List of dependency names that should not be added to the scheduler graph as dependencies (and are therefore not processed by transformations) but are treated in the current item as targets. This facilitates processing across build targets, where, e.g., caller and callee-side are transformed in separate Loki passes.

Type:

tuple

enrich

List of program units that should still be looked up and used to “enrich” IR nodes (e.g., ProcedureSymbol in CallStatement) in this item for inter-procedural transformation passes.

Type:

tuple

Parameters:

config (dict) – The config values for the Item. Typically generated by SchedulerConfig.create_item_config.

property role

Role in the transformation chain, for example 'driver' or 'kernel'

property mode

Transformation “mode” to pass to the transformation

property expand

Flag to trigger expansion of children under this node

property strict

Flag controlling whether to strictly fail if source file cannot be parsed

property replicate

Flag indicating whether to mark item as “replicated” in call graphs

property disable

List of sources to completely exclude from expansion and the source tree.

property block

List of sources to block from processing, but add to the source tree for visualisation.

property ignore

List of sources to expand but ignore during processing

property enrich

List of sources to to use for IPA enrichment

property is_ignored

Flag controlling whether the item is ignored during processing

classmethod match_symbol_or_name(symbol_or_name, keys, scope=None)

Match a TypedSymbol, MetaSymbol or name against a list of config values given as keys

This checks whether symbol_or_name matches any of the given entries, which would typically be something like the disable, ignore, or block config entries.

Optionally, scope provides the name of the scope in which symbol_or_name is defined. For derived type members, this takes care of resolving to the type name and matching that. This will also match successfully, if only parent components match, e.g., the scope name or the type name of the symbol. The use of simple patterns is allowed, see SchedulerConfig.match_item_keys for more information.

Parameters:

• symbol_or_name (TypedSymbol or MetaSymbol or str) – The symbol or name to match

• keys (list of str) – The list of candidate names to match against. This can be fully qualified names (e.g., 'my_scope#my_routine'), plain scope or routine names (e.g., 'my_scope' or 'my_routine'), or use simple patterns (e.g., 'my_*').

• scope (str, optional) – The name of the scope, in which symbol_or_name is defined, if available. Providing this allows to match a larger range of name combinations

Returns:

True if matched successfully, otherwise False

Return type:

bool