include/GaudiKernel/IAuditor.h

0001 /***********************************************************************************\
0002 * (c) Copyright 1998-2024 CERN for the benefit of the LHCb and ATLAS collaborations *
0003 *                                                                                   *
0004 * This software is distributed under the terms of the Apache version 2 licence,     *
0005 * copied verbatim in the file "LICENSE".                                            *
0006 *                                                                                   *
0007 * In applying this licence, CERN does not waive the privileges and immunities       *
0008 * granted to it by virtue of its status as an Intergovernmental Organization        *
0009 * or submit itself to any jurisdiction.                                             *
0010 \***********************************************************************************/
0011 #ifndef GAUDI_IAUDITOR_H
0012 #define GAUDI_IAUDITOR_H
0013
0014 // Include files
0015 #include <GaudiKernel/INamedInterface.h>
0016 #include <array>
0017 #include <string>
0018
0019 /** @class IAuditor IAuditor.h GaudiKernel/IAuditor.h
0020
0021     The IAuditor is the interface implmented by the AlgAuditor base class.
0022     Concrete auditors, derived from the AlgAuditor base class are controlled
0023     via this interface.
0024
0025     @author Marjorie Shapiro, LBNL
0026     @author Marco Clemencic <marco.clemencic@cern.ch>
0027 */
0028 class GAUDI_API IAuditor : virtual public INamedInterface {
0029 public:
0030   /// InterfaceID
0031   DeclareInterfaceID( IAuditor, 3, 0 );
0032
0033   /// Defines the standard (= used by the framework) auditable event types.
0034   enum StandardEventType { Initialize, ReInitialize, Execute, Finalize, Start, Stop, ReStart };
0035   /// Simple mapping function from IAuditor::StandardEventType to string.
0036   friend const char* toStr( IAuditor::StandardEventType e ) {
0037     constexpr std::array<const char*, IAuditor::StandardEventType::ReStart + 1> s_tbl = {
0038         { "Initialize", "ReInitialize", "Execute", "Finalize", "Start", "Stop", "ReStart" } };
0039     return e <= IAuditor::StandardEventType::ReStart ? s_tbl[e] : nullptr;
0040   }
0041   friend std::ostream& operator<<( std::ostream& s, IAuditor::StandardEventType e ) { return s << toStr( e ); }
0042
0043   /// Type used to allow users to specify a custom event to be audit.
0044   /// Examples of custom events are callbacks (see
0045   /// <a href="https://savannah.cern.ch/patch/index.php?1725">patch #1725</a>).
0046   typedef std::string CustomEventType;
0047   /// Used in function calls for optimization purposes.
0048   typedef const CustomEventType& CustomEventTypeRef;
0049
0050   /// Audit the start of a standard "event".
0051   virtual void before( StandardEventType, INamedInterface* ) = 0;
0052   /// Audit the start of a standard "event" for callers that do not implement INamedInterface.
0053   virtual void before( StandardEventType, const std::string& ) = 0;
0054
0055   /// Audit the start of a custom "event".
0056   virtual void before( CustomEventTypeRef, INamedInterface* ) = 0;
0057   /// Audit the start of a custom "event" for callers that do not implement INamedInterface.
0058   virtual void before( CustomEventTypeRef, const std::string& ) = 0;
0059
0060   /// Audit the end of a standard "event".
0061   virtual void after( StandardEventType, INamedInterface*, const StatusCode& sc = StatusCode::SUCCESS ) = 0;
0062   /// Audit the end of a standard "event" for callers that do not implement INamedInterface.
0063   virtual void after( StandardEventType, const std::string&, const StatusCode& sc = StatusCode::SUCCESS ) = 0;
0064
0065   /// Audit the end of a custom "event".
0066   virtual void after( CustomEventTypeRef, INamedInterface*, const StatusCode& sc = StatusCode::SUCCESS ) = 0;
0067   /// Audit the end of a custom "event" for callers that do not implement INamedInterface.
0068   virtual void after( CustomEventTypeRef, const std::string&, const StatusCode& sc = StatusCode::SUCCESS ) = 0;
0069
0070   /// Tell if the auditor is enabled or not.
0071   virtual bool isEnabled() const = 0;
0072
0073   // ------- Obsolete interface ------
0074   /// \deprecated use before
0075   virtual void beforeInitialize( INamedInterface* ) = 0;
0076   /// \deprecated use after
0077   virtual void afterInitialize( INamedInterface* ) = 0;
0078
0079   /// \deprecated use before
0080   virtual void beforeReinitialize( INamedInterface* ) = 0;
0081   /// \deprecated use after
0082   virtual void afterReinitialize( INamedInterface* ) = 0;
0083
0084   /// \deprecated use before
0085   virtual void beforeExecute( INamedInterface* ) = 0;
0086   /// \deprecated use after
0087   virtual void afterExecute( INamedInterface*, const StatusCode& ) = 0;
0088
0089   /// \deprecated use before
0090   virtual void beforeFinalize( INamedInterface* ) = 0;
0091   /// \deprecated use after
0092   virtual void afterFinalize( INamedInterface* ) = 0;
0093
0094   /// Used by AuditorSvc.
0095   virtual StatusCode sysInitialize() = 0;
0096
0097   /// Used by AuditorSvc.
0098   virtual StatusCode sysFinalize() = 0;
0099 };
0100
0101 #endif // GAUDIKERNEL_IAUDITOR_H