 |
ATLAS Offline Software
|
|
ATLAS Offline Software
|
a modified tool handle that allows its owner to configure new tools from the C++ side More...
#include <AnaToolHandle.h>
Public Member Functions | |
| void | testInvariant () const |
| test the invariant of this object More... | |
| AnaToolHandle (const std::string &val_name="", parentType_t *val_parent=nullptr) | |
| create a tool handle with the given name and parent More... | |
| AnaToolHandle (AnaToolHandle< T > &&that) | |
| move constructor More... | |
| AnaToolHandle (const AnaToolHandle< T > &that) | |
| copy constructor More... | |
| ~AnaToolHandle () noexcept | |
| standard destructor More... | |
| AnaToolHandle & | operator= (const AnaToolHandle< T > &that) |
| assignment operator More... | |
| AnaToolHandle< T > & | operator= (AnaToolHandle< T > &&that) |
| standard move assignment operator More... | |
| void | swap (AnaToolHandle< T > &that) noexcept |
| standard swap More... | |
| bool | empty () const |
| whether this ToolHandle is completely empty, i.e. More... | |
| bool | isPublic () const noexcept |
| whether this is a public tool (or tool handle) More... | |
| bool | isInitialized () const noexcept |
| whether initialize has been called successfully, i.e. More... | |
| template<typename T2 > | |
| void | declarePropertyFor (T2 *tool, const std::string &name, const std::string &description="") |
| declare as property on the given tool More... | |
| const ToolHandle< T > & | getHandle () const noexcept |
| the tool handle we wrap More... | |
| const std::string & | type () const noexcept |
| the type configured for this AnaToolHandle More... | |
| void | setType (std::string val_type) noexcept |
| set the value of type More... | |
| const std::string & | name () const noexcept |
| the name configured for this AnaToolHandle More... | |
| void | setName (std::string val_name) noexcept |
| set the value of name More... | |
| std::string | fullName () const |
| the full name of the tool to be used during tool initialization More... | |
| std::string | typeAndName () const |
| the value of type and name More... | |
| void | setTypeAndName (const std::string &val_typeAndName) |
| set the value of type and name More... | |
| void | setTypeAndName (std::string val_type, std::string val_name) noexcept |
| set the value of type and name More... | |
| StatusCode | initialize () |
| initialize the tool More... | |
| StatusCode | retrieve () |
| initialize the tool More... | |
| T * | operator-> () |
| access the tool More... | |
| const T * | operator-> () const |
| access the tool More... | |
| T & | operator* () |
| access the tool More... | |
| const T & | operator* () const |
| access the tool More... | |
| T * | get () |
| access the tool More... | |
| const T * | get () const |
| access the tool More... | |
| bool | isUserConfigured () const noexcept |
| whether this tool handle has been configured by the user More... | |
| detail::AnaToolHandleMode | mode () const |
| the detail::AnaToolHandleMode for this handle More... | |
| const AsgToolConfig & | config () const |
| the detail::AnaToolConfig for this handle More... | |
| bool | allowEmpty () const noexcept |
| whether the user is allowed to configure this with an empty tool handle More... | |
| void | setAllowEmpty (bool val_allowEmpty=true) noexcept |
| set the value of allowEmpty More... | |
| bool | isConfigurable () const |
| whether the tool can be configured by us, i.e. More... | |
| bool | inPremakeState () const noexcept |
| bool | inBrokenState () const noexcept |
| StatusCode | make () |
| StatusCode | make (const std::string &val_type) noexcept |
| template<class T2 > | |
| StatusCode | setProperty (const std::string &property, const T2 &value) |
| set the given property of the tool. More... | |
| template<class T2 > | |
| std::enable_if< std::is_base_of_v< parentType_t, T2 >, StatusCode >::type | setProperty (const std::string &property, const ToolHandle< T2 > &value) |
| template<class T2 > | |
| StatusCode | setProperty (const std::string &property, const AnaToolHandle< T2 > &value) |
| template<class T2 > | |
| std::enable_if< std::is_base_of_v< parentType_t, T2 >, StatusCode >::type | setProperty (const std::string &property, const ToolHandleArray< T2 > &value) |
Private Member Functions | |
| detail::AnaToolHandleMode | getMode (std::shared_ptr< detail::AnaToolShare > &sharedTool) const |
| get the mode with which this ToolHandle will be initialized More... | |
| detail::AnaToolHandleMode | getMode () const |
| get the mode with which this ToolHandle will be initialized More... | |
| StatusCode | makeToolRetrieve (T *&toolPtr, ToolHandle< T > &toolHandle) const |
| make a tool by retrieving the ToolHandle More... | |
Private Attributes | |
| std::vector< std::function< StatusCode()> > | m_extraInit |
| any extra initialization we need to do before creating the tool More... | |
| std::shared_ptr< void > | m_cleanup |
| any stuff we need to release as part of cleanup More... | |
| AsgToolConfig | m_config |
| the configuration for this tool More... | |
| std::string | m_name |
| the value of name More... | |
| parentType_t * | m_parentPtr = nullptr |
| the pointer to the parent More... | |
| std::shared_ptr< ToolHandle< T > > | m_handleUser |
| the ToolHandle exposed to the user More... | |
| std::string | m_originalTypeAndName |
| the typeAndName at time of creation More... | |
| std::atomic< bool > | m_isInitialized {false} |
| the value of isInitialized More... | |
| T * | m_toolPtr = nullptr |
| the pointer to the tool we use More... | |
| detail::AnaToolHandleMode | m_mode = detail::AnaToolHandleMode::EMPTY |
| the value of getMode cached when we initialize the tool More... | |
| bool | m_allowEmpty = false |
| the value of allowEmpty More... | |
| std::recursive_mutex | m_initializeMutex |
| a mutex to ensure that we don't call initialize twice concurrently More... | |
a modified tool handle that allows its owner to configure new tools from the C++ side
One of the main differences between RootCore and Athena is that RootCore lacks a configuration manager. This means that in RootCore we have to create and configure all tools on the spot, which is not (easily) possible in Athena. This particular tool handle provides a dual-use way of doing so, while introducing a number of important safety pre-cautions that are lacking on the RootCore side.
The primary (or at least original) purpose of this tool handle was to support dual-use analysis frameworks. For these the actual configuration of the CP tools is a critical component, and having to configure them separately in RootCore and Athena is a potential source of rather difficult to track down bugs. An unfortunate side-effect of this is that we can't use the Athena configuration mechanism. Once we have a dual-use configuration manager it will hopefully provide a more attractive option.
A secondary benefit is that this allows to create and configure tools on the Athena side without having to write configuration files. This is particularly beneficial when writing unit tests where you have to create a lot of rather short-lived tools and where separate configuration files would be impractical. It may also be beneficial for new users who can (at first) be turned off by the complexity of Athena configuration.
The basic interface is a mix between the ToolHandle interface for accessing the tool, and the AsgTool interface for configuring/initializing the tools. In addition it allows to set this ToolHandle as a property on another configurable, to allow configuring it via the standard configuration mechanisms.
If a parent tool is specified, the tool is private (and this tool handle is modeled after unique_ptr). If no parent tool is specified, the tool is public/shared (and this tool handle is modeled after shared_ptr). In public/shared mode, if you create and initialize one tool it is then available for use by other tool handles registered with the same name and type. The subsequent tool handles with that name will then automatically pick up the tool in the configuration set by the first tool handle. The user still has to call initialize() on the tool handle before using the tool. While it is allowed to call the setProperty method on those tool handles these calls will be effectively ignored. The net effect of that is that as a user of a handle for a shared tool you don't have to worry about whether you are the one creating the tool or just using it, you just initialize the tool handle in the same way.
The tool handle can also be declared as a property on the parent tool by using the ToolHandle provided via its handle member function. This allows the user to override the configuration done in the parent tool via the job options file in Athena or via setProperty in RootCore. Like for shared tools, initialize still has to be called and the calls to setProperty get ignored. This is so that inside the parent tool you don't have to write any special detection code to see whether the user configured the AnaToolHandle or if you need to do so yourself. Instead, you can just write your code as if the user didn't configure your tool handle and if the user does, the tool handle will automatically switch over.
There are a number of ways of how a tool can be created/accessed through an AnaToolHandle (in increasing order of precedence):
Definition at line 34 of file AnaToolHandle.h.
|
explicit |
create a tool handle with the given name and parent
The name can either be just a regular name or of the form type/name, in which case type indicates the type of the tool to be created. If you don't explicitly call make (or pass no type into it), you have to rely on this form.
| asg::AnaToolHandle< T >::AnaToolHandle | ( | AnaToolHandle< T > && | that | ) |
move constructor
| asg::AnaToolHandle< T >::AnaToolHandle | ( | const AnaToolHandle< T > & | that | ) |
copy constructor
This will copy the configuration if the argument has not been initialized yet, and it will create a shared tool handle if it has.
|
noexcept |
standard destructor
|
noexcept |
whether the user is allowed to configure this with an empty tool handle
This normally defaults to whether the developer initialized this to a valid ToolHandle to begin with, but depending on the situation it can be overridden.
| const AsgToolConfig& asg::AnaToolHandle< T >::config | ( | ) | const |
the detail::AnaToolConfig for this handle
This is mostly meant for internal use by the setProperty method, not for use by the end-user
| void asg::AnaToolHandle< T >::declarePropertyFor | ( | T2 * | tool, |
| const std::string & | name, | ||
| const std::string & | description = "" |
||
| ) |
declare as property on the given tool
| bool asg::AnaToolHandle< T >::empty | ( | ) | const |
whether this ToolHandle is completely empty, i.e.
it has been default constructed and was never assigned any content by the user
| std::string asg::AnaToolHandle< T >::fullName | ( | ) | const |
the full name of the tool to be used during tool initialization
| T* asg::AnaToolHandle< T >::get | ( | ) |
access the tool
| const T* asg::AnaToolHandle< T >::get | ( | ) | const |
access the tool
|
noexcept |
the tool handle we wrap
|
private |
get the mode with which this ToolHandle will be initialized
This exists in two modes, one passing back a shared tool pointer and one without it. as a rule of thumb, the version passing back the shared tool should be used by initialize, whereas all the places just wanting to check that will happen can/should call the version without.
|
private |
get the mode with which this ToolHandle will be initialized
This exists in two modes, one passing back a shared tool pointer and one without it. as a rule of thumb, the version passing back the shared tool should be used by initialize, whereas all the places just wanting to check that will happen can/should call the version without.
|
inlinenoexcept |
Definition at line 544 of file AnaToolHandle.h.
| StatusCode asg::AnaToolHandle< T >::initialize | ( | ) |
initialize the tool
|
inlinenoexcept |
Definition at line 539 of file AnaToolHandle.h.
| bool asg::AnaToolHandle< T >::isConfigurable | ( | ) | const |
whether the tool can be configured by us, i.e.
whether properties set via setProperty will be used for something
For the most part this is the reverse of isUserConfigured except some shared tools may register as not user configured and not configurable either. if the properties set are used to generate debugging output even a user configured tool may register as configurable.
|
noexcept |
whether initialize has been called successfully, i.e.
whether the tool is ready to be used
|
noexcept |
whether this is a public tool (or tool handle)
|
noexcept |
whether this tool handle has been configured by the user
i.e. somebody called declareProperty with our handle member, and then that got configured either from the job options file in Athena or via setProperty in RootCore
|
inline |
Definition at line 549 of file AnaToolHandle.h.
|
inlinenoexcept |
Definition at line 554 of file AnaToolHandle.h.
|
private |
make a tool by retrieving the ToolHandle
| detail::AnaToolHandleMode asg::AnaToolHandle< T >::mode | ( | ) | const |
the detail::AnaToolHandleMode for this handle
This is mostly meant for internal use by the setProperty method, not for use by the end-user
|
noexcept |
the name configured for this AnaToolHandle
| T& asg::AnaToolHandle< T >::operator* | ( | ) |
access the tool
| const T& asg::AnaToolHandle< T >::operator* | ( | ) | const |
access the tool
| T* asg::AnaToolHandle< T >::operator-> | ( | ) |
access the tool
| const T* asg::AnaToolHandle< T >::operator-> | ( | ) | const |
access the tool
| AnaToolHandle<T>& asg::AnaToolHandle< T >::operator= | ( | AnaToolHandle< T > && | that | ) |
standard move assignment operator
| AnaToolHandle& asg::AnaToolHandle< T >::operator= | ( | const AnaToolHandle< T > & | that | ) |
assignment operator
This will copy the configuration if the argument has not been initialized yet, and it will create a shared tool handle if it has.
| StatusCode asg::AnaToolHandle< T >::retrieve | ( | ) |
initialize the tool
|
noexcept |
|
noexcept |
| StatusCode asg::AnaToolHandle< T >::setProperty | ( | const std::string & | property, |
| const AnaToolHandle< T2 > & | value | ||
| ) |
| StatusCode asg::AnaToolHandle< T >::setProperty | ( | const std::string & | property, |
| const T2 & | value | ||
| ) |
set the given property of the tool.
this will make the tool is not already created.
if the tool is shared and has already been created, this call will be ignored.
this can also be used to set tool handle properties by passing in either a regular ToolHandle or an AnaToolHandle object.
| std::enable_if<std::is_base_of_v<parentType_t, T2>, StatusCode>::type asg::AnaToolHandle< T >::setProperty | ( | const std::string & | property, |
| const ToolHandle< T2 > & | value | ||
| ) |
| std::enable_if<std::is_base_of_v<parentType_t, T2>, StatusCode>::type asg::AnaToolHandle< T >::setProperty | ( | const std::string & | property, |
| const ToolHandleArray< T2 > & | value | ||
| ) |
|
noexcept |
set the value of type
| void asg::AnaToolHandle< T >::setTypeAndName | ( | const std::string & | val_typeAndName | ) |
set the value of type and name
|
noexcept |
|
noexcept |
standard swap
| void asg::AnaToolHandle< T >::testInvariant | ( | ) | const |
test the invariant of this object
|
noexcept |
the type configured for this AnaToolHandle
| std::string asg::AnaToolHandle< T >::typeAndName | ( | ) | const |
|
private |
the value of allowEmpty
Definition at line 666 of file AnaToolHandle.h.
|
private |
any stuff we need to release as part of cleanup
\warn This member has to come before m_handleUser
Definition at line 583 of file AnaToolHandle.h.
|
private |
the configuration for this tool
Definition at line 587 of file AnaToolHandle.h.
|
private |
any extra initialization we need to do before creating the tool
This is mostly/only for creating public tools the tool needs to use. This is not ideal for various reasons, but it is what it is, and this is legacy code.
\warn This member has to come before m_cleanup
Definition at line 577 of file AnaToolHandle.h.
|
private |
the ToolHandle exposed to the user
This primarily serves to allow the user to set this like a regular ToolHandle property. During initialize it is then updated to refer to the actually used tool.
This is done as a shared pointer, so that the include dependency is only pulled in for the source file that actually uses the AnaToolHandle. That in turn reduces the number of public dependencies an Athena package has to expose.
Definition at line 609 of file AnaToolHandle.h.
|
private |
a mutex to ensure that we don't call initialize twice concurrently
This is a recursive mutex so that we can lock both in initialize and get without conflict.
Definition at line 685 of file AnaToolHandle.h.
|
private |
the value of isInitialized
Definition at line 620 of file AnaToolHandle.h.
|
private |
the value of getMode cached when we initialize the tool
This is protected by m_isInitialized and should not be accessed until m_isInitialized is true.
Definition at line 640 of file AnaToolHandle.h.
|
private |
the value of name
Definition at line 591 of file AnaToolHandle.h.
|
private |
the typeAndName at time of creation
This is used to determine whether the user has been overriding the ToolHandle during configuration time.
Definition at line 616 of file AnaToolHandle.h.
|
private |
the pointer to the parent
Definition at line 595 of file AnaToolHandle.h.
|
private |
the pointer to the tool we use
This is used for actually accessing the tool, independent of who created it or how. Mostly this is a performance optimization to avoid going back to the ToolHandle every single time.
This is protected by m_isInitialized and should not be accessed until m_isInitialized is true.
Definition at line 632 of file AnaToolHandle.h.
1.8.18