asg::final< T > Class Template Reference

a modified tool handle that allows its owner to configure new tools from the C++ side More...

#include <AnaToolHandle.h>

List of all members.

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 ()
Toperator-> ()
 access the tool
const Toperator-> () const
 access the tool
Toperator* ()
 access the tool
const Toperator* () const
 access the tool
Tget ()
 access the tool
const Tget () 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::AnaToolConfigconfig () 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

Detailed Description

template<class T>
class asg::final< T >

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.


Constructor & Destructor Documentation

template<class T >
asg::final< T >::~AnaToolHandle (  ) 

standard destructor

Guarantee
no-fail
template<class T >
asg::final< T >::~MessagePrinterOverlay (  ) 

remove the currently overlaid printer

Guarantee
no-fail

Member Function Documentation

template<class T >
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.

Guarantee
no-fail
template<class T >
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.

Guarantee
strong
Failures
out of memory II
template<class T >
asg::final< T >::AnaToolHandle ( AnaToolHandle< T > &&  that  ) 

move constructor

Guarantee
no-fail
template<class T >
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.

Guarantee
strong
Failures
out of memory II
template<class T >
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

Guarantee
strong
Failures
out of memory II
template<class T >
static IMessagePrinter& asg::final< T >::current (  )  [static]

get the current IMessagePrinter

Guarantee
no-fail
template<class T >
template<typename T2 >
void asg::final< T >::declarePropertyFor ( T2 *  tool,
const std::string &  name,
const std::string &  description = "" 
) [inline]

declare as property on the given tool

Guarantee
basic
Failures
out of memory II
property declaration failures
tool already made
template<class T >
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

Guarantee
strong
Failures
out of memory II
template<class T >
std::string asg::final< T >::fullName (  )  const

the full name of the tool to be used during tool initialization

Guarantee
strong
Failures
out of memory II
template<class T >
const T* asg::final< T >::get (  )  const

access the tool

Guarantee
strong
Failures
tool creation failures
Postcondition:
result != nullptr
template<class T >
T* asg::final< T >::get (  ) 

access the tool

Guarantee
strong
Failures
tool creation failures
Postcondition:
result != nullptr
template<class T >
const ToolHandle<T>& asg::final< T >::getHandle (  )  const

the tool handle we wrap

Guarantee
no-fail
template<class T >
StatusCode asg::final< T >::initialize (  ) 

initialize the tool

Guarantee
strong
Failures
tool initialization failures
Precondition:
!isInitialized()
template<class T >
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.

Guarantee
no-fail this may go away at some point as we may be using the properties for more and more things (e.g. info printouts)
template<class T >
bool asg::final< T >::isInitialized (  )  const

whether initialize has been called successfully, i.e. whether the tool is ready to be used

Guarantee
no-fail
template<class T >
bool asg::final< T >::isPublic (  )  const

whether this is a public tool (or tool handle)

Guarantee
no-fail
template<class T >
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

Guarantee
no-fail
template<class T >
asg::final< T >::MessagePrinterOverlay ( IMessagePrinter *  val_printer  ) 

overlay with the given message printer

Guarantee
no-fail
Precondition:
val_printer != nullptr
template<class T >
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

Guarantee
strong
Failures
out of memory II
template<class T >
const std::string& asg::final< T >::name (  )  const

the name configured for this AnaToolHandle

Guarantee
no-fail
template<class T >
const T& asg::final< T >::operator* (  )  const

access the tool

Guarantee
strong
Failures
tool creation failures
template<class T >
T& asg::final< T >::operator* (  ) 

access the tool

Guarantee
strong
Failures
tool creation failures
template<class T >
const T* asg::final< T >::operator-> (  )  const

access the tool

Guarantee
strong
Failures
tool creation failures
Postcondition:
result != nullptr
template<class T >
T* asg::final< T >::operator-> (  ) 

access the tool

Guarantee
strong
Failures
tool creation failures
Postcondition:
result != nullptr
template<class T >
AnaToolHandle<T>& asg::final< T >::operator= ( AnaToolHandle< T > &&  that  ) 

standard move assignment operator

Guarantee
no-fail
template<class T >
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.

Guarantee
strong
Failures
out of memory II
template<class T >
StatusCode asg::final< T >::retrieve (  ) 

initialize the tool

Guarantee
strong
Failures
tool initialization failures
Precondition:
!isInitialized()

template<class T >
void asg::final< T >::setAllowEmpty ( bool  val_allowEmpty = true  ) 

set the value of allowEmpty

Guarantee
no-fail
Precondition:
!isInitialized()
template<class T >
void asg::final< T >::setName ( std::string  val_name  ) 

set the value of name

Guarantee
no-fail
Precondition:
!isInitialized()
template<class T >
template<class T2 >
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.

Guarantee
basic
Failures
property setting failures
Precondition:
!isInitialized()
template<class T >
void asg::final< T >::setType ( std::string  val_type  ) 

set the value of type

Guarantee
no-fail
Precondition:
!isInitialized()
template<class T >
void asg::final< T >::setTypeAndName ( std::string  val_type,
std::string  val_name 
)

set the value of type and name

Guarantee
no-fail
Precondition:
!isInitialized()
template<class T >
void asg::final< T >::setTypeAndName ( const std::string &  val_typeAndName  ) 

set the value of type and name

Guarantee
strong
Failures
out of memory II
Precondition:
!isInitialized()
template<class T >
void asg::final< T >::swap ( AnaToolHandle< T > &  that  ) 

standard swap

Guarantee
no-fail
template<class T >
void asg::final< T >::testInvariant (  )  const

test the invariant of this object

Guarantee
no-fail
template<class T >
const std::string& asg::final< T >::type (  )  const

the type configured for this AnaToolHandle

Guarantee
no-fail
template<class T >
std::string asg::final< T >::typeAndName (  )  const

the value of type and name

Guarantee
strong
Failures
out of memory II

The documentation for this class was generated from the following files:
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on 1 Dec 2017 for RootCore Packages by  doxygen 1.6.1