dbgasserters.inl

Go to the documentation of this file.

//==================================================================================================
/// \file
/// This header-file is part of module \alib_threads of the \aliblong.
///
/// \emoji :copyright: 2013-2025 A-Worx GmbH, Germany.
/// Published under \ref mainpage_license "Boost Software 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 \ref ALIB_DBG should be used.
    const char* Name                                                                   ="<unnamed>";
    CallerInfo  AcqCI ;                  ///< Source location of the most recent acquirement.
    CallerInfo  RelCI ;                  ///< Source location of the most recent release.
 
    std::atomic<int> CntAcquirements{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 Lock \"{}\"
                Message: {}
   In (Member-)Function: {}
               Is Owned: {} ({})
 
              Called By: {}::{}
                     At: {}:{}
                 Thread: {}
 
  Latest Acquisition By: {}::{}
                     At: {}:{}
                 Thread: {}
      Latest Release By: {}:{}
                     At: {}:{}
                 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: \b %CallerInfo of caller.
      - \c 11-15: \b %CallerInfo of the latest acquisition.
      - \c 16-20: \b %CallerInfo 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 &&  AcqCI.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 \ref 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." );
        AcqCI= requestCI;
        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 != AcqCI.ThreadID )
            DoAssert( 0, assertCI, requestCI, "Release without having ownership");
        RelCI = requestCI;
        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 == AcqCI.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
{
    CallerInfo       SAcqCI;                   ///< The most recent shared acquirement's caller.
    CallerInfo       SRelCI;                   ///< 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: {}:{}
                        Thread: {}
             Latest Release By: {}::{}
                            At: {}:{}
                        Thread: {}
 
  Latest Shared Acquisition By: {}::{}
                            At: {}:{}
                        Thread: {}
       Latest SharedRelease By: {}::{}
                            At: {}:{}
                        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:  \b %CallerInfo of caller.
      - \c 13-17: \b %CallerInfo of the latest acquisition.
      - \c 18-22: \b %CallerInfo of the latest release.
      - \c 23-27: \b %CallerInfo of the latest shared-acquisition.
      - \c 32-36: \b %CallerInfo of the latest shared-release.
 */
    ALIB_DLL
    static const char* ASSERTION_FORMAT_SHARED;
 
 
    /// Destructor.
    virtual ~DbgSharedLockAsserter()                                                     override {}
    
    /// Assembles assertion info and \ref alib_mod_assert "raises a warning or an 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
    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( CntAcquirements.load() > 0 )
            DoAssert( 0, assertCI, requestCI, "Already (still) owned." );
        if( CntSharedAcquirements.load() > 0 )
            DoAssert( 0, assertCI, requestCI, "Already (still) shared-owned." );
        AcqCI= requestCI;
        CntAcquirements.fetch_add(1);
    }
 
    /// 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" );
 
        SAcqCI= requestCI;
    }
 
    /// 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" );
 
        SRelCI= requestCI;
    }
 
 
}; // struct DbgSharedLockAsserter
 
 
//==================================================================================================
/// This type is used for debugging and asserting types \alib{threads;TCondition}.
/// With debug compilations that class holds one member of this struct, which aggregates all
/// debug information.
//==================================================================================================
struct DbgConditionAsserter
{
    const character*  Name;                  ///< The name of this instance.
    Thread*           Owner{nullptr};        ///< Tracks the current owner.
    CallerInfo        AcqCI ;                ///< Source location of the most recent acquirement.
    CallerInfo        RelCI ;                ///< Source location of the most recent release.
    CallerInfo        WaitCI;                ///< The most recent call to \b WaitForNotification.
    CallerInfo        NotifyCI;              ///< The most recent call to \b ReleaseAndNotify or
    std::atomic<int>  CntWaiters{0};         ///< The number of currently waiting threads.
    std::thread::id   AssertExclusiveWaiter; ///< If set from outside, methods \b WaitForNotification
                                             ///< 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: {}:{}
                  Thread: {}
       Latest Release By: {}::{}
                      At: {}:{}
                  Thread: {}
 
          Latest Wait By: {}::{}
                      At: {}:{}
                  Thread: {}
        Latest Notify By: {}::{}
                      At: {}:{}
                  Thread: {}
      \endverbatim
*/
    ALIB_DLL
    static const char* ASSERTION_FORMAT;
 
    /// Writes assertion info and calls \ref ALIB_ASSERT.
    /// @see
    ///    Field #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