loki.bulk.item

Classes

GenericImportItem(name, source[, config])

Implementation of Item to represent a catchall for any Fortran module import.

GlobalVarImportItem(name, source[, config])

Implementation of Item to represent a global variable import.

Item(name, source[, config])

Base class of a work item that represents a single source routine to be processed

ProcedureBindingItem(name, source[, config])

Implementation of Item to represent a Fortran procedure binding

SubroutineItem(name, source[, config])

Implementation of Item to represent a Fortran subroutine work item

class Item(name, source, config=None)

Bases: object

Base class of a work item that represents a single source routine to be processed

Each Item spawns new work items according to its own subroutine calls and can be configured to ignore individual sub-trees.

Depending of the nature of the work item, the implementation of Item is done in subclasses SubroutineItem, ProcedureBindingItem, GlobalVarImportItem and GenericImportItem.

The name of a Item refers to the routine or variable name using a fully-qualified name in the format <scope_name>#<local_name>. The <scope_name> corresponds to a Fortran module that a subroutine or variable is declared in, or can be empty if the subroutine is not enclosed in a module (i.e. exists in the global scope). This is to enable use of routines with the same name that are declared in different modules. The corresponding parts of the name can be accessed via scope_name and local_name.

For type-bound procedures, the local_name should take the format <type_name>%<binding_name>. This may also span across multiple derived types, e.g., to allow calls to type bound procedures of a derived type variable that in turn is a member of another derived type, e.g., <type_name>%<member_name>%<binding_name>. See ProcedureBindingItem` for more details.

Notes

Each work item may have its own configuration settings that primarily inherit values from the ‘default’, but can be specialised explicitly in the config file or dictionary.

Possible arguments are:

  • role: Role string to pass to the Transformation (eg. “kernel”)

  • mode: Transformation “mode” to pass to the transformation

  • expand: Flag to generally enable/disable expansion under this item

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

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

  • disable: List of subroutines that are completely ignored and are not reported as children. Useful to exclude entire call trees or utility routines.

  • block: List of subroutines that should should not be added to the scheduler tree. Note, these might still be shown in the graph visulisation.

  • ignore: Individual list of subroutine calls to “ignore” during expansion. Calls to these routines may be processed on the caller side but not the called subroutine itself. This facilitates processing across build targets, where caller and callee-side are transformed in different Loki passes.

  • enrich: List of subroutines that should still be looked up and used to “enrich” CallStatement nodes in this Item for inter-procedural transformation passes.

Parameters:
  • name (str) – Name to identify items in the schedulers graph

  • source (Sourcefile) – The underlying source file that contains the associated item

  • config (dict) – Dict of item-specific config markers

clear_cached_property(property_name)

Clear the cached value for a cached property

property scope_name

The name of this item’s scope

property local_name

The item name without the scope

property scope

Module object that is the enclosing scope of this Item

Note that this property is cached, so that updating the name of an associated Module (eg. via the DependencyTransformation) may not break the association with this Item.

Return type:

Module or NoneType

abstract property routine

Return the Subroutine object associated with this Item

Return type:

Subroutine or NoneType

abstract property imports

Return a tuple of all Import nodes relevant to this Item

Note that this includes also imports from the parent scope.

Return type:

list of Import

property qualified_imports

Return the mapping of named imports (i.e. explicitly qualified imports via a use-list or rename-list) to their fully qualified name

property unqualified_imports

Return names of imported modules without explicit ONLY list

abstract property members

The names of member routines contained in this Item

abstract property calls

The local name of all routines called from this Item

abstract property function_interfaces

All inline functions defined in this Item via an explicit interface

property path

The filepath of the associated source file

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 enable_imports

Configurable option to enable the addition of module imports as children.

property children

Set of all child routines that this work item has in the call tree

Note that this is not the set of active children that a traversal will apply a transformation over, but rather the set of nodes that defines the next level of the internal call tree.

This returns the local names of children which can be fully qualified via qualify_names().

Return type:

list of str

qualify_names(names, available_names=None)

Fully qualify names with their scope

This amends every entry in names with their scope name in the format <scope_name>#<local_name>. Entries that already have a scope name are unchanged.

The scope is derived using qualified imports and takes into account any renaming that may happen as part of that.

For names that cannot be unambiguously attributed to a scope, either because they stem from an unqualified import or because they refer to a subroutine declared in the global scope, a tuple of fully-qualified candidate names is returned. Of these, only one can be a possible match or the symbol would be non-uniquely defined. If available_names is provided, these candidate lists are resolved by picking the correct fully-qualified name out of these candidate lists.

Parameters:
  • names (list of str) – A list of local or fully-qualified names to process

  • available_names (list of str, optional) – A list of all available fully-qualified names, to be provided, e.g., by the Scheduler

Returns:

qualified_names – The fully-qualified names in the same order as names. For names that cannot be resolved unambiguously, a tuple of candidate names is returned.

Return type:

list of str

property targets

Set of “active” child routines that are part of the transformation traversal.

This defines all child routines of an item that will be traversed when applying a Transformation as well, after tree pruning rules are applied.

This returns the local names of children which can be fully qualified via qualify_names().

Return type:

list of str

class SubroutineItem(name, source, config=None)

Bases: Item

Implementation of Item to represent a Fortran subroutine work item

property routine

Subroutine object that this Item encapsulates for processing

Note that this property is cached, so that updating the name of an associated Subroutine with (eg. via the DependencyTransformation) may not break the association with this Item.

Return type:

Subroutine

property members

Names of member routines contained in the subroutine corresponding to this item

Return type:

tuple of str

property imports

Return a tuple of all Import nodes relevant to this Item

This includes imports in the corresponding Subroutine as well as the enclosing Module scope, if applicable.

Return type:

list of Import

property calls

The local name of all routines called from this Item

These are identified via CallStatement nodes within the associated routine’s IR.

property function_interfaces

Inline functions declared in the corresponding Subroutine, or its parent Module, via an explicit interface.

class ProcedureBindingItem(name, source, config=None)

Bases: Item

Implementation of Item to represent a Fortran procedure binding

This does not constitute a work item when applying transformations across the call tree in the Scheduler and is skipped during the processing phase. However, it is necessary to provide the dependency link from calls to type bound procedures to their implementation in a Fortran routine.

property routine

Always returns None as this is not associated with a Subroutine

property members

Empty tuple as procedure bindings have no member routines

Return type:

tuple

property imports

Return modules imported in the parent scope

property function_interfaces

Empty tuple as procedure bindings cannot include interface blocks

Return type:

tuple

property calls

The local names of the routines that are bound to the derived type under the name of the current Item

For procedure bindings that returns the local name of a subroutine. For an item representing a call to a type bound procedure in a derived type member, this returns the local name of the type bound procedure. For a generic binding, this returns all local names of type bound procedures that are combined under a generic binding.

class GlobalVarImportItem(name, source, config=None)

Bases: Item

Implementation of Item to represent a global variable import. These encapsulate variables that store data. Whilst such variables can clearly have dependencies, in the current implementation items of type GlobalVarImportItem do not have any children (mainly due to a lack of practical benefit).

property routine

Always returns None as this is not associated with a Subroutine

property members

Empty tuple as variable imports have no member routines

Return type:

tuple

property function_interfaces

Empty tuple as global variable imports cannot include interface blocks

Return type:

tuple

property imports

Return modules imported in the parent scope

property calls

Empty tuple as items of type GlobalVarImportItem cannot have any children.

class GenericImportItem(name, source, config=None)

Bases: Item

Implementation of Item to represent a catchall for any Fortran module import.

This does not constitute a work item when applying transformations across the call tree in the Scheduler and is skipped during the processing phase. It is needed when the type of the symbol being imported isn’t immediately obvious from the USE statement and more context is needed.

property routine

Always returns None as this is not associated with a Subroutine

property members

Empty tuple as generic imports have no member routines

Return type:

tuple

property function_interfaces

Empty tuple as generic import items cannot include interface blocks

Return type:

tuple

property imports

Return modules imported in the parent scope

property calls

The local name of all routines called from this Item

property procedure_interface_members

The set of children unique to items of type GenericImportItem. Comprises exclusively of function calls bound to a procedure interface.