dbgasserters.hpp

Go to the documentation of this file.

//==================================================================================================
/// \file
/// This header-file is part of module \alib_threads of the \aliblong.
///
/// Copyright 2013-2026 A-Worx GmbH, Germany.
/// Published under #"mainpage_license".
//==================================================================================================
#if !ALIB_SINGLE_THREADED && ALIB_DEBUG
 
ALIB_EXPORT namespace alib::threads {
 
//==================================================================================================
/// This type is used for debugging and asserting \alib lock (mutex) types.
/// With debug compilations the non-shared lock types hold one member of this struct, which
/// aggregates all debug information.
//==================================================================================================
struct DbgLockAsserter {
    
    /// The name of this Lock.
    /// Set to <em> "<unnamed>"</em> by default.
    /// Used for debug-output.
    /// For automatic pruning of changes to this name, macro #"ALIB_DBG" should be used.
    const char* Name                                                                   ="<unnamed>";
    std::atomic<int> ActionCounter{1};   ///< Counter of the actions.
    std::atomic<int> CntAcquirements{0}; ///< The number of shared acquirements.
 
    /// Collects caller info and the sequence number of actions.
    struct ActionInfo {
        CallerInfo  CI;                  ///< The caller information.
        int         ActionNo = -1;       ///< The sequence number of the action.
    };
 
    ActionInfo  Acq ;                    ///< Source location of the most recent acquirement.
    ActionInfo  Rel ;                    ///< Source location of the most recent release.
 
    /// The format string used to write exceptions to the console.
    /// This string can be changed if the source information is not "clickable" in a user's
    /// development environment.<br>
    ///
    /// The default string is optimized for
    /// \https{JetBrains CLion,www.jetbrains.com/clion} and is defined as:
    /**  \verbatim
Multi-Threading {} in Lock \"{}\"
                Message: {}
   In (Member-)Function: {}
               Is Owned: {} ({})
 
              Called By: {}::{}
                     At: {}:{}
                 Thread: {}
 
  Latest Acquisition By: {}::{}
                     At: {}:{}
           Seq / Thread: {} / {}
      Latest Release By: {}:{}
                     At: {}:{}
           Seq / Thread: {} / {}
      \endverbatim
      <p>
      The placeholder fields that this format string refers to are set as follows:
      - \c 0: String "Assertion" or "Warning"
      - \c 1: Debug-name of the lock.
      - \c 2: Headline.
      - \c 3: Function name.
      - \c 4: Is acquired (true/false).
      - \c 5: number of acquirements.
      - \c 6-10:  #"CallerInfo" of caller.
      - \c 11-16: #"DbgLockAsserter::ActionInfo" of the latest acquisition.
      - \c 17-22: #"DbgLockAsserter::ActionInfo" of the latest release.
*/
    ALIB_DLL
    static const char* ASSERTION_FORMAT;
 
 
    /// This is a threshold that causes non-timed Acquire() methods to raise a \alib_warning in
    /// debug-builds in case a thread is blocked longer than the given duration.
    ///
    /// To disable warnings in cases that high block times are suitable, set this value to \c 0.
    /// The default value is two seconds.
    Ticks::Duration                WaitTimeLimit          = Ticks::Duration::FromAbsoluteSeconds(2);
 
    /// Limit of recursions. If the limit is reached or a multiple of it, an
    /// \alib_warning is raised.
    /// Defaults is \c 10. To disable, set to \c 0.<p>
    /// Available only in debug versions of \alib.
    int                            RecursionLimit                                               =10;
 
    /// Destructor.
    virtual ~DbgLockAsserter() {
        if( CntAcquirements.load() > 0 )
            DoAssert( 0, ALIB_CALLER, ALIB_CALLER, "Destructing acquired lock" );
    }
    
    /// Returns a pointer the owning thread.<p>
    /// Available only in debug-builds.
    /// @return Pointer to the owning thread, or \c nullptr if not owned.
    ALIB_DLL
    Thread*         GetOwner()                                                                const;
 
    /// Returns \c true if the current owner is the current thread.<p>
    /// Available only in debug-builds.
    /// @return \c true, if the lock is owned by this thread, \c false if it is owned by
    ///            another thread or not owned.
    bool            IsOwnedByCurrentThread()                                                   const
    { return CntAcquirements.load() > 0 &&  Acq.CI.ThreadID == std::this_thread::get_id(); }
 
    /// Returns \c true if this is a non-recursive lock or a recursive instance which is acquired
    /// exactly once.<br>
    /// Available only in debug-builds.
    ///
    /// \note
    ///   This method is not (and cannot) be synchronized. Consequently, a reliable result
    ///   is only guaranteed in case #".IsOwnedByCurrentThread" returns \c true before this method
    ///   is invoked.
    ///
    /// @return \c true if the next release will free this lock, \c false otherwise.
    bool            WillRelease()              const noexcept { return CntAcquirements.load()== 1; }
 
    /// Collects assertion info and #"alib_mod_assert;raises a warning or error".
    /// @see
    ///    Field #".ASSERTION_FORMAT" which allows changing the output format to achieve 'clickable'
    ///    assertion messages.
    /// @param type     0= assertion, 1= warning.
    /// @param assertCI Location where the assertion is placed.
    /// @param ci       Location of the call to the method that asserted.
    /// @param headline The message.
    ALIB_DLL
    virtual
    void DoAssert       (int type, const CallerInfo& assertCI, const CallerInfo& ci,
                         const char* headline );
 
    /// Asserts that #"CntAcquirements" is not \c 0
    /// @param assertCI Location where the assertion is placed.
    /// @param ci       Location of the call to the method that asserted.
    void AssertOwned    (const CallerInfo& assertCI, const CallerInfo& ci )
    {
        if( CntAcquirements.load() == 0 )
            DoAssert( 0, assertCI, ci, "Not acquired" );
    }
 
    /// Sets the given caller as the current owner. Asserts that #"CntAcquirements" is \c 0
    /// when called.
    /// @param assertCI Location where ownership was implemented (usually the lock).
    /// @param requestCI Location where ownership was requested (the caller of \p{assertCI})
    void SetOwner    (const CallerInfo& assertCI, const CallerInfo& requestCI ) {
        if( CntAcquirements.load() > 0 )
            DoAssert( 0, assertCI, requestCI, "Already (still) owned." );
        Acq.CI      = requestCI;
        Acq.ActionNo= ActionCounter.fetch_add(1);
        CntAcquirements.fetch_add(1);
    }
 
    /// Sets the given caller as the current owner. Asserts that either #"CntAcquirements" is \c 0
    /// or the current owner is the same as in parameter \p{requestCI}.
    /// @param assertCI Location where ownership was implemented (usually the lock).
    /// @param requestCI Location where ownership was requested (the caller of \p{assertCI})
    ALIB_DLL
    void SetRecursiveOwner (const CallerInfo& assertCI, const CallerInfo& requestCI );
 
    /// Asserts that this lock is owned by the thread in \p{ci}.
    /// @param assertCI Location where the release is implemented.
    /// @param requestCI Location where the release was requested (the caller of \p{assertCI})
    void Release   (const CallerInfo& assertCI, const CallerInfo& requestCI) {
        if( CntAcquirements.load() == 0 || requestCI.ThreadID != Acq.CI.ThreadID )
            DoAssert( 0, assertCI, requestCI, "Release without having ownership");
        Rel.CI      = requestCI;
        Rel.ActionNo= ActionCounter.fetch_add(1);
        CntAcquirements.fetch_sub(1);
    }
 
    /// Asserts that this lock is not owned by the thread in \p{ci}.
    /// @param assertCI Location where the assertion is placed.
    /// @param ci       Location of the call to the method that asserted.
    /// @param headline The message.
    void AssertNotOwning(const CallerInfo& assertCI, const CallerInfo& ci, const char* headline )
    {
        if( CntAcquirements.load() > 0 && ci.ThreadID == Acq.CI.ThreadID )
            DoAssert( 0, assertCI, ci, headline);
    }
}; // struct DbgLockAsserter
 
//==================================================================================================
/// This type is used for debugging and asserting \alib lock (mutex) types.
/// With debug compilations the shared lock types hold one member of this struct, which
/// aggregates all debug information.
//==================================================================================================
struct DbgSharedLockAsserter : DbgLockAsserter {
    ActionInfo       SAcq;                     ///< The most recent shared acquirement's caller.
    ActionInfo       SRel;                     ///< The most recent shared release caller.
    std::atomic<int> CntSharedAcquirements{0}; ///< The number of shared acquirements.
 
    /// The format string used to write exceptions to the console.
    /// This string can be changed if the source information is not "clickable" in a user's
    /// development environment.<br>
    ///
    /// The default string is optimized for
    /// \https{JetBrains CLion,www.jetbrains.com/clion} and is defined as:
    /**  \verbatim
Multi-Threading {} in Shared-Lock \"{}\"
                       Message: {}
          In (Member-)Function: {}
                      Is Owned: {} ({})
               Is Shared Owned: {} ({})
 
                     Called By: {}::{}
                            At: {}:{}
                        Thread: {}
 
         Latest Acquisition By: {}::{}
                            At: {}:{}
                  Seq / Thread: {} / {}
             Latest Release By: {}::{}
                            At: {}:{}
                  Seq / Thread: {} / {}
 
  Latest Shared Acquisition By: {}::{}
                            At: {}:{}
                  Seq / Thread: {} / {}
       Latest SharedRelease By: {}::{}
                            At: {}:{}
                  Seq / Thread: {} / {}
      \endverbatim
      <p>
      The placeholder fields that this format string refers to are set as follows:
 
      - \c 0: String "Assertion" or "Warning"
      - \c 1: Debug-name of the lock.
      - \c 2: Headline.
      - \c 3: Function name.
      - \c 4: Is acquired (true/false).
      - \c 5: number of acquirements.
      - \c 6: Is shared acquired (true/false).
      - \c 7: number of shared-acquirements.
      - \c 8-12:  #"CallerInfo" of caller.
      - \c 13-18: #"DbgLockAsserter::ActionInfo" of the latest acquisition.
      - \c 19-24: #"DbgLockAsserter::ActionInfo" of the latest release.
      - \c 25-30: #"DbgLockAsserter::ActionInfo" of the latest shared-acquisition.
      - \c 31-36: #"DbgLockAsserter::ActionInfo" of the latest shared-release.
 */
    ALIB_DLL
    static const char* ASSERTION_FORMAT_SHARED;
 
 
    /// Destructor.
    virtual ~DbgSharedLockAsserter()                                                     override {}
    
    /// Assembles assertion info and #"alib_mod_assert;raises a warning or an error".
    /// @see
    ///    Inherited field #"DbgLockAsserter::ASSERTION_FORMAT" which allows changing the output
    ///    format to achieve 'clickable' assertion messages.
    /// @param type     0= assertion, 1= warning.
    /// @param assertCI Location where the assertion is placed.
    /// @param ci       Location of the call to the method that asserted.
    /// @param headline The message.
    ALIB_DLL
    void DoAssert       (int type, const CallerInfo& assertCI, const CallerInfo& ci,
                         const char* headline )                                            override;
 
    /// Returns \c true if currently a reader is registered. This method is used to
    /// create assertions. of course, to detect assertions, it would be more efficient to check
    /// if shared ownership is with the current thread, but a check on this would cost
    /// a lot of overhead to realize. This way, at least assertions can be raised when no other
    /// thread acquired this lock in shared mode.<p>
    /// Available only in debug-builds.
    /// @return \c true, if the lock is owned by this thread, \c false if it is owned by
    ///         another thread or not owned.
    bool    IsSharedOwnedByAnyThread()            const { return CntSharedAcquirements.load() > 0; }
 
    /// Sets the given caller as the current owner. Asserts that #"CntAcquirements" is \c 0
    /// when called.
    /// @param assertCI Location where ownership was implemented (usually the lock).
    /// @param requestCI Location where ownership was requested (the caller of \p{assertCI})
    void SetOwner    (const CallerInfo& assertCI, const CallerInfo& requestCI ) {
        if( CntSharedAcquirements.load() > 0 )
            DoAssert( 0, assertCI, requestCI, "Already (still) shared-owned." );
        DbgLockAsserter::SetOwner( assertCI, requestCI );
    }
 
    /// Sets the given caller as a current shared-owner. Asserts that #"CntAcquirements" is \c 0
    /// when called.
    /// @param assertCI   Location where ownership was implemented (usually the lock).
    /// @param requestCI  Location where ownership was requested (the caller of \p{assertCI})
    /// @param warnLimit  If this number of shared acquisitions is exceeded, a warning is
    ///                  given.
    void SetSharedOwner    (const CallerInfo& assertCI, const CallerInfo& requestCI,
                            int warnLimit ) {
        if( CntAcquirements.load() > 0 )
            DoAssert( 0, assertCI, requestCI, "Already (still) owned." );
 
        if ( CntSharedAcquirements.fetch_add(1) >= warnLimit )
            DoAssert( 1, ALIB_CALLER, requestCI,
                "Too many parallel shared acquisitions detected. "
                "A reason might be that shared acquirers do not call ReleaseShared" );
 
        SAcq.CI      = requestCI;
        SAcq.ActionNo= ActionCounter.fetch_add(1);
    }
 
    /// Asserts that this lock is shared-owned by the thread in \p{ci}.
    /// @param assertCI Location where the release is implemented.
    /// @param requestCI Location where the release was requested (the caller of \p{assertCI})
    void ReleaseShared   (const CallerInfo& assertCI, const CallerInfo& requestCI) {
        auto prevCounter= CntSharedAcquirements.fetch_sub(1);
        if ( prevCounter <= 0 )
            DoAssert( 0,  assertCI, requestCI,
              "Too many invocations of ReleaseShared (from any thread) without prior acquisition" );
 
        SRel.CI      = requestCI;
        SRel.ActionNo= ActionCounter.fetch_add(1);
    }
 
}; // struct DbgSharedLockAsserter
 
 
//==================================================================================================
/// This type is used for debugging and asserting types #"TCondition".
/// With debug compilations that class holds one member of this struct, which aggregates all
/// debug information.
//==================================================================================================
struct DbgConditionAsserter {
    /// Collects caller info and the sequence number of actions.
    struct ActionInfo {
        CallerInfo  CI;            ///< The caller information.
        int         ActionNo = -1; ///< The sequence number of the action.
    };
 
    const character*  Name;                  ///< The name of this instance.
    std::atomic<int>  ActionCounter{1};      ///< Counter of the actions.
    Thread*           Owner{nullptr};        ///< Tracks the current owner.
    ActionInfo        Acq ;                  ///< Source location of the most recent acquirement.
    ActionInfo        Rel ;                  ///< Source location of the most recent release.
    ActionInfo        Wait;                  ///< The most recent call to
                                             ///< #"%WaitForNotification(ALIB_DBG_TAKE_CI)".
    ActionInfo        Notify;                ///< The most recent call to #"%ReleaseAndNotify".
    std::atomic<int>  CntWaiters{0};         ///< The number of currently waiting threads.
    std::thread::id   AssertExclusiveWaiter; ///< If set from outside, overloaded methods
                                             ///< #"TCondition::WaitForNotification(ALIB_DBG_TAKE_CI)"
                                             ///< will raise an assertion in the case they are
                                             ///< called from a different thread.
 
    /// The format string used to write exceptions to the console.
    /// This string can be changed if the source information is not "clickable" in a user's
    /// development environment.<br>
    ///
    /// The default string is optimized for
    /// \https{JetBrains CLion,www.jetbrains.com/clion} and is defined as:
    /**  \verbatim
Assertion failed in method TCondition::{}
                 Message: {}
                Instance: {}
 
               Called By: {}::{}
                      At: {}:{}
                  Thread: {}
 
           Current Owner: {}
             #Of Waiters: {}
        Exclusive Waiter: {}
 
   Latest Acquisition By: {}::{}
                      At: {}:{}
            Seq / Thread: {} / {}
       Latest Release By: {}::{}
                      At: {}:{}
            Seq / Thread: {} / {}
 
          Latest Wait By: {}::{}
                      At: {}:{}
            Seq / Thread: {} / {}
        Latest Notify By: {}::{}
                      At: {}:{}
            Seq / Thread: {} / {}
      \endverbatim
*/
    ALIB_DLL
    static const char* ASSERTION_FORMAT;
 
    /// Writes assertion info and calls #"ALIB_ASSERT".
    /// @see
    ///    Inherited field #"DbgLockAsserter::ASSERTION_FORMAT" which allows changing the output
    ///    format to achieve 'clickable' assertion messages.
    /// @param cond     The condition that is to be met.
    /// @param assertCI Location where the assertion is placed.
    /// @param ci       Location of the call to the method that asserted.
    /// @param headline The message.
    ALIB_DLL
    void Assert( bool cond, const CallerInfo& assertCI, const CallerInfo& ci,
                 const char* headline );
 
    /// Returns \c true if the current owner is the current thread.<p>
    /// Available only in debug-builds.
    /// @return \c true, if the lock is owned by this thread, \c false if it is owned by
    ///            another thread or not owned.
    bool            IsOwnedByCurrentThread()                                                   const
    { return Owner != nullptr &&  Owner == Thread::GetCurrent() ; }
 
}; // struct DbgConditionAsserter
 
} // namespace [alib::threads]
 
#endif // !ALIB_SINGLE_THREADED && ALIB_DEBUG