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 | |
| AnaToolHandle (const std::string &val_name="", parentType_t *val_parent=nullptr) | |
| create a tool handle with the given name and parent | |
| AnaToolHandle (AnaToolHandle< T > &&that) | |
| move constructor | |
| AnaToolHandle (const AnaToolHandle< T > &that) | |
| copy constructor | |
| ~AnaToolHandle () noexcept | |
| standard destructor | |
| AnaToolHandle & | operator= (const AnaToolHandle< T > &that) |
| assignment operator | |
| AnaToolHandle< T > & | operator= (AnaToolHandle< T > &&that) |
| standard move assignment operator | |
| void | swap (AnaToolHandle< T > &that) noexcept |
| standard swap | |
| bool | empty () const |
| whether this ToolHandle is completely empty, i.e. it has been default constructed and was never assigned any content by the user | |
| bool | isPublic () const noexcept |
| whether this is a public tool (or tool handle) | |
| bool | isInitialized () const noexcept |
| whether initialize has been called successfully, i.e. whether the tool is ready to be used | |
| template<typename T2 > | |
| void | declarePropertyFor (T2 *tool, const std::string &name, const std::string &description="") |
| declare as property on the given tool | |
| const ToolHandle< T > & | getHandle () const noexcept |
| the tool handle we wrap | |
| template<class T2 > | |
| StatusCode | setProperty (const std::string &property, const T2 &value) |
| set the given property of the tool. | |
| const std::string & | type () const noexcept |
| the type configured for this AnaToolHandle | |
| void | setType (std::string val_type) noexcept |
| set the value of type | |
| const std::string & | name () const noexcept |
| the name configured for this AnaToolHandle | |
| void | setName (std::string val_name) noexcept |
| set the value of name | |
| std::string | fullName () const |
| the full name of the tool to be used during tool initialization | |
| std::string | typeAndName () const |
| the value of type and name | |
| void | setTypeAndName (const std::string &val_typeAndName) |
| set the value of type and name | |
| void | setTypeAndName (std::string val_type, std::string val_name) noexcept |
| set the value of type and name | |
| StatusCode | initialize () |
| initialize the tool | |
| StatusCode | retrieve () |
| T * | operator-> () |
| access the tool | |
| const T * | operator-> () const |
| access the tool | |
| T & | operator* () |
| access the tool | |
| const T & | operator* () const |
| access the tool | |
| T * | get () |
| access the tool | |
| const T * | get () const |
| access the tool | |
| bool | isUserConfigured () const noexcept |
| whether this tool handle has been configured by the user | |
| detail::AnaToolHandleMode | mode () const |
| the detail::AnaToolHandleMode for this handle | |
| const detail::AnaToolConfig & | config () const |
| the detail::AnaToolConfig for this handle | |
| bool | allowEmpty () const noexcept |
| whether the user is allowed to configure this with an empty tool handle | |
| void | setAllowEmpty (bool val_allowEmpty=true) noexcept |
| set the value of allowEmpty | |
| bool | isConfigurable () const |
| whether the tool can be configured by us, i.e. whether properties set via setProperty will be used for something | |
| bool | inPremakeState () const noexcept |
| bool | inBrokenState () const noexcept |
| StatusCode | make () |
| ASG_DEPRECATED ("please use setType() or setTypeAndName() instead") StatusCode make(std | |
| MessagePrinterOverlay (IMessagePrinter *val_printer) noexcept | |
| overlay with the given message printer | |
| ~MessagePrinterOverlay () noexcept | |
| remove the currently overlaid printer | |
Static Public Member Functions | |
| static IMessagePrinter & | current () noexcept |
| get the current IMessagePrinter | |
a modified tool handle that allows its owner to configure new tools from the C++ side
an object to change the IMessagePrinter temporarily
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):
The idea is to use this in unit tests to replace the standard printer with a mock object. The idea is to place this on the stack and it will then replace the standard object for as long as it is on the stack.
Note that this is per se not thread-safe, but given the intended purpose that ought to be fine, i.e. there is only one MessagePrinter for all threads, so if it is replaced in a multi-threaded manner it will cause other problems.
| asg::final< T >::~AnaToolHandle | ( | ) |
standard destructor
| asg::final< T >::~MessagePrinterOverlay | ( | ) |
remove the currently overlaid printer
| bool asg::final< T >::allowEmpty | ( | ) | const |
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.
| asg::final< 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.
| asg::final< T >::AnaToolHandle | ( | AnaToolHandle< T > && | that | ) |
move constructor
| asg::final< T >::AnaToolHandle | ( | const std::string & | val_name = "", |
|
| parentType_t * | val_parent = nullptr | |||
| ) | [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.
| const detail::AnaToolConfig& asg::final< 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
| static IMessagePrinter& asg::final< T >::current | ( | ) | [static] |
get the current IMessagePrinter
| void asg::final< T >::declarePropertyFor | ( | T2 * | tool, | |
| const std::string & | name, | |||
| const std::string & | description = "" | |||
| ) | [inline] |
declare as property on the given tool
| bool asg::final< 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::final< T >::fullName | ( | ) | const |
the full name of the tool to be used during tool initialization
| const T* asg::final< T >::get | ( | ) | const |
access the tool
| T* asg::final< T >::get | ( | ) |
access the tool
| const ToolHandle<T>& asg::final< T >::getHandle | ( | ) | const |
the tool handle we wrap
| StatusCode asg::final< T >::initialize | ( | ) |
initialize the tool
| bool asg::final< 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.
| bool asg::final< T >::isInitialized | ( | ) | const |
whether initialize has been called successfully, i.e. whether the tool is ready to be used
| bool asg::final< T >::isPublic | ( | ) | const |
whether this is a public tool (or tool handle)
| bool asg::final< T >::isUserConfigured | ( | ) | const |
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
| asg::final< T >::MessagePrinterOverlay | ( | IMessagePrinter * | val_printer | ) |
overlay with the given message printer
| detail::AnaToolHandleMode asg::final< 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
| const std::string& asg::final< T >::name | ( | ) | const |
the name configured for this AnaToolHandle
| const T& asg::final< T >::operator* | ( | ) | const |
access the tool
| T& asg::final< T >::operator* | ( | ) |
access the tool
| const T* asg::final< T >::operator-> | ( | ) | const |
access the tool
| T* asg::final< T >::operator-> | ( | ) |
access the tool
| AnaToolHandle<T>& asg::final< T >::operator= | ( | AnaToolHandle< T > && | that | ) |
standard move assignment operator
| AnaToolHandle& asg::final< 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::final< T >::retrieve | ( | ) |
initialize the tool
| void asg::final< T >::setAllowEmpty | ( | bool | val_allowEmpty = true |
) |
| void asg::final< T >::setName | ( | std::string | val_name | ) |
| StatusCode asg::final< T >::setProperty | ( | const std::string & | property, | |
| const T2 & | value | |||
| ) | [inline] |
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.
| void asg::final< T >::setType | ( | std::string | val_type | ) |
| void asg::final< T >::setTypeAndName | ( | std::string | val_type, | |
| std::string | val_name | |||
| ) |
| void asg::final< T >::setTypeAndName | ( | const std::string & | val_typeAndName | ) |
| void asg::final< T >::swap | ( | AnaToolHandle< T > & | that | ) |
standard swap
| void asg::final< T >::testInvariant | ( | ) | const |
test the invariant of this object
| const std::string& asg::final< T >::type | ( | ) | const |
the type configured for this AnaToolHandle
| std::string asg::final< T >::typeAndName | ( | ) | const |
1.6.1
