logger.inl

Go to the documentation of this file.

//==================================================================================================
/// \file
/// This header-file is part of module \alib_alox of the \aliblong.
///
/// \emoji :copyright: 2013-2025 A-Worx GmbH, Germany.
/// Published under #"mainpage_license".
//==================================================================================================
ALIB_EXPORT namespace alib { namespace lox {
//==================================================================================================
/// This is the C++ namespace for internal main classes and other things belonging to
/// the <em>%ALox Logging Library</em>.<p>
/// Types and interfaces found in this namespace are not designed for access by users of the
/// library. However, if extending \alox, e.g., by implementing new custom <em>loggers</em>, things
/// found here provide an important foundation.
///
/// Developed by A-Worx GmbH and published under Boost Software License.
//==================================================================================================
namespace detail
{
class ScopeInfo;
    
//==================================================================================================
/// This is a central class of the \alox logging implementation. It is **not** recommended to use this
/// class directly for logging. Instead, use the simple and convenient static interface class
/// Log or, for release logging and other more complex operations, use a Lox instance.
/// The class is abstract. To implement an own log stream, derive a new Logger class and implement
/// the abstract method #".Log".
///
/// ## Friends ##
/// class #"Lox"
//==================================================================================================
class Logger
#if !ALIB_SINGLE_THREADED
: public threads::RecursiveLock
#endif
{
    #if !DOXYGEN
    friend struct detail::LoxImpl;
    friend bool     LI::RemoveLogger(LoxImpl*, Logger*);
    friend Logger*  LI::RemoveLogger(LoxImpl*, const NString&);
    friend void     LI::SetVerbosity(LoxImpl*, Logger*, Verbosity, const NString&, Priority);
    #endif
 
  //################################################################################################
  // Internal fields
  //################################################################################################
  protected:
    /// The name of the \e Logger. Used as a reference to a logger. All loggers attached to a
    /// \b %Lox have to differ in their names.
    /// If no name is specified with the constructor, the name will by the same as #".TypeName".
    NString32                   Name;
 
    /// The type name of the \e Logger. This is set by the derived class similar to the class
    /// name.
    NString32                   TypeName;
 
  //################################################################################################
  // public fields
  //################################################################################################
  public:
    /// The number of logs actually performed so far. In a text logger this is similar to the
    /// line number, despite the fact that a single log call can produce more than one line.
    integer                     CntLogs                                                          =0;
 
    /// The creation time of the \e Logger.
    time::Ticks            TimeOfCreation;
 
    /// Timestamp of the last log operation.
    time::Ticks            TimeOfLastLog;
 
  //################################################################################################
  // Abstract methods
  //################################################################################################
  public:
    /// This is the central method that derived logger classes have to implement to log a
    /// message. When it is invoked the <em>%Log %Domain's %Verbosity</em> was already checked
    /// against parameter \p{verbosity}. The only action to take is to perform the log
    /// itself.<br>
    /// Parameter \p{logables} contains the objects provided with the log statement as well as
    /// other objects to log, for example,
    /// #"alib_mod_alox_prefix_logables_intro;Prefix Logables".
    ///
    /// @param dom       The <em>Log Domain</em>.
    /// @param verbosity The verbosity of the message.
    /// @param logables  The list of objects to log.
    /// @param scope     Information about the scope of the <em>Log Statement</em>..
    virtual void   Log( Domain& dom, Verbosity verbosity, BoxesMA& logables, ScopeInfo& scope)   =0;
 
  //################################################################################################
  // Constructor/Destructor
  //################################################################################################
  protected:
    /// Constructs a logger. This constructor is protected because this class is abstract.
    ///
    /// Note: This constructor is implemented in the header and annotated as inline.
    /// This way, the Log::InitALox call receives the size of classes from the compilation unit
    /// that invokes the constructor. If different compile options are set, we have a chance to
    /// detect them here.
    /// @param name     The name of the \e Logger. If empty, it defaults to the type name.
    ///                 Will be converted to upper case.
    /// @param typeName The type of the \e Logger.
    ///                 Will be converted to upper case.
    Logger( const NString& name, const NString& typeName )
    : Name(name)
    , TypeName(typeName)
    , TimeOfCreation ()
    , TimeOfLastLog  () {
        IF_ALIB_THREADS(  ALIB_DBG(Dbg.Name= "Logger";) )
        if ( Name.IsEmpty() )
             Name << typeName;
        Name    .ToUpper();
        TypeName.ToUpper();
    }
 
  public:
    #if ALIB_DEBUG_CRITICAL_SECTIONS
    /// Destructs a logger
    virtual  ~Logger()                                                                   override {}
    #else
        virtual  ~Logger()                                                                        {}
    #endif
 
  //################################################################################################
  // Registration with class Lox
  //################################################################################################
  protected:
    /// This method is invoked by class #"Lox" when a logger is added or removed from it.
    /// Note, that a logger might be added to multiple \b %Lox objects in parallel.
    ///
    /// The default implementation of this method is empty.
    ///
    /// @param lox     The \b %Lox to acknowledge insertion or removal.
    /// @param op      The operation. Either \b ContainerOp::Insert or \b ContainerOp::Remove.
    virtual void AcknowledgeLox( LoxImpl* lox,  lang::ContainerOp op )    { (void) lox; (void) op; }
 
  //################################################################################################
  // Interface
  //################################################################################################
  public:
    /// Returns the name of this logger. The name has to be unique for all \e %Loggers attached
    /// to a \b %Lox.
    /// @return The loggers name.
    const NString&  GetName()                                                 const { return Name; }
 
    /// Returns the constant type name of this logger. The type name is defined by the class
    /// and hence provides a sort of run-time type information.
    /// @return The loggers type name.
    const NString&  GetTypeName()                                         const { return TypeName; }
 
    /// If the variable is defined with a higher priority than the given one, nothing is done.
    /// Otherwise, sets the flag #"CVVerbosities::ExportAll" in configuration variable
    /// to the given value. In the case that parameter \p{value} equals \c true, also an internal
    /// flag is set, which causes the method #"Variable::IsWriteBack;*" to return
    /// \c true.
    /// @param lox      The \b %Lox that the logger is attached to.
    ///                 Note that a logger might be attached to more than one \b %Lox.
    /// @param value    The value to set.
    /// @param priority The priority of the setting. Passed to the method
    ///                 #"Variable::Define;*".
    /// @return \c true if the priority was equal or lower than the given one, \c false otherwise.
    ALIB_DLL
    bool            SetVerbosityExport(Lox* lox, bool value, Priority priority=Priority::Standard);
 
}; // class Logger
 
}} // namespace alib[::lox::detail]
 
/// Type alias in namespace \b alib.
using     Logger=       lox::detail::Logger;
 
}  // namespace [alib]
 
 
 
namespace alib {  namespace strings {
 
// Faking all template specializations of namespace strings for doxygen into namespace
// strings::APPENDABLES to keep the documentation of namespace string clean!
#if DOXYGEN
namespace APPENDABLES {
#endif
 
//==================================================================================================
/// Specialization of functor #"AppendableTraits" for type \b %Logger.
///
/// @tparam TChar      Character type of the target \b AString.
//==================================================================================================
template<typename TChar> struct AppendableTraits<lox::detail::Logger,TChar, lang::HeapAllocator>
{
    /// Writes the name of the logger. In case the type name is different, it will be appended
    /// in braces.
    /// @param  target The AString to append \p{src} to.
    /// @param  logger The logger to append information for.
    void operator()( TAString<TChar, lang::HeapAllocator>& target,
                     const lox::detail::Logger& logger )             {
        target << logger.GetName();
        if ( !logger.GetName().Equals<NC>( logger.GetTypeName() ) )
            target << " (" << logger.GetTypeName() << ")";
    }
};
 
#if DOXYGEN
}
#endif
 
}} // namespace [alib::lox::strings]
 
ALIB_BOXING_VTABLE_DECLARE( alib::lox::detail::Logger* , vt_lox_logger    )