loki.bulk.item
Classes
|
Implementation of |
|
Implementation of |
|
Base class of a work item that represents a single source routine to be processed |
|
Implementation of |
|
Implementation of |
- 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 subclassesSubroutineItem
,ProcedureBindingItem
,GlobalVarImportItem
andGenericImportItem
.The
name
of aItem
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 viascope_name
andlocal_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>
. SeeProcedureBindingItem`
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 theTransformation
(eg. “kernel”)mode
: Transformation “mode” to pass to the transformationexpand
: Flag to generally enable/disable expansion under this itemstrict
: Flag controlling whether to strictly fail if source file cannot be parsedreplicated
: Flag indicating whether to mark item as “replicated” in call graphsdisable
: List of subroutines that are completely ignored and are not reported aschildren
. 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 thisItem
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 itemconfig (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 thisItem
Note that this property is cached, so that updating the name of an associated
Module
(eg. via theDependencyTransformation
) may not break the association with thisItem
.- Return type:
Module
or NoneType
- abstract property routine
Return the
Subroutine
object associated with thisItem
- Return type:
Subroutine
or NoneType
- abstract property imports
Return a tuple of all
Import
nodes relevant to thisItem
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 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()
.
- 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:
- 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:
- 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()
.
- class SubroutineItem(name, source, config=None)
Bases:
Item
Implementation of
Item
to represent a Fortran subroutine work item- property routine
Subroutine
object that thisItem
encapsulates for processingNote that this property is cached, so that updating the name of an associated
Subroutine
with (eg. via theDependencyTransformation
) may not break the association with thisItem
.- Return type:
- property members
Names of member routines contained in the subroutine corresponding to this item
- property imports
Return a tuple of all
Import
nodes relevant to thisItem
This includes imports in the corresponding
Subroutine
as well as the enclosingModule
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 parentModule
, via an explicit interface.
- class ProcedureBindingItem(name, source, config=None)
Bases:
Item
Implementation of
Item
to represent a Fortran procedure bindingThis 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 imports
Return modules imported in the parent scope
- property function_interfaces
Empty tuple as procedure bindings cannot include interface blocks
- Return type:
- 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 typeGlobalVarImportItem
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 function_interfaces
Empty tuple as global variable imports cannot include interface blocks
- Return type:
- 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 function_interfaces
Empty tuple as generic import items cannot include interface blocks
- Return type:
- property imports
Return modules imported in the parent scope
- property procedure_interface_members
The set of children unique to items of type
GenericImportItem
. Comprises exclusively of function calls bound to a procedure interface.