From 908c89e04b6019bdb08bb5f1c861af42046db623 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Don=C3=A1t=20Nagy?= Date: Mon, 12 Aug 2024 11:48:13 +0200 Subject: [PATCH] [analyzer][NFC] Improve documentation of `invalidateRegion` methods (#102477) ... within the classes `StoreManager` and `ProgramState` and describe the connection between the two methods. --- .../Core/PathSensitive/ProgramState.h | 25 +++++++++++-------- .../StaticAnalyzer/Core/PathSensitive/Store.h | 11 ++++++-- 2 files changed, 23 insertions(+), 13 deletions(-) diff --git a/clang/include/clang/StaticAnalyzer/Core/PathSensitive/ProgramState.h b/clang/include/clang/StaticAnalyzer/Core/PathSensitive/ProgramState.h index 9889d2604a890e..2f6cd481fd6362 100644 --- a/clang/include/clang/StaticAnalyzer/Core/PathSensitive/ProgramState.h +++ b/clang/include/clang/StaticAnalyzer/Core/PathSensitive/ProgramState.h @@ -304,24 +304,27 @@ class ProgramState : public llvm::FoldingSetNode { [[nodiscard]] ProgramStateRef killBinding(Loc LV) const; - /// Returns the state with bindings for the given regions - /// cleared from the store. + /// Returns the state with bindings for the given regions cleared from the + /// store. If \p Call is non-null, also invalidates global regions (but if + /// \p Call is from a system header, then this is limited to globals declared + /// in system headers). /// - /// Optionally invalidates global regions as well. + /// This calls the lower-level method \c StoreManager::invalidateRegions to + /// do the actual invalidation, then calls the checker callbacks which should + /// be triggered by this event. /// /// \param Regions the set of regions to be invalidated. /// \param E the expression that caused the invalidation. /// \param BlockCount The number of times the current basic block has been - // visited. - /// \param CausesPointerEscape the flag is set to true when - /// the invalidation entails escape of a symbol (representing a - /// pointer). For example, due to it being passed as an argument in a - /// call. + /// visited. + /// \param CausesPointerEscape the flag is set to true when the invalidation + /// entails escape of a symbol (representing a pointer). For example, + /// due to it being passed as an argument in a call. /// \param IS the set of invalidated symbols. /// \param Call if non-null, the invalidated regions represent parameters to /// the call and should be considered directly invalidated. - /// \param ITraits information about special handling for a particular - /// region/symbol. + /// \param ITraits information about special handling for particular regions + /// or symbols. [[nodiscard]] ProgramStateRef invalidateRegions(ArrayRef Regions, const Expr *E, unsigned BlockCount, const LocationContext *LCtx, @@ -330,7 +333,7 @@ class ProgramState : public llvm::FoldingSetNode { RegionAndSymbolInvalidationTraits *ITraits = nullptr) const; [[nodiscard]] ProgramStateRef - invalidateRegions(ArrayRef Regions, const Expr *E, unsigned BlockCount, + invalidateRegions(ArrayRef Values, const Expr *E, unsigned BlockCount, const LocationContext *LCtx, bool CausesPointerEscape, InvalidatedSymbols *IS = nullptr, const CallEvent *Call = nullptr, diff --git a/clang/include/clang/StaticAnalyzer/Core/PathSensitive/Store.h b/clang/include/clang/StaticAnalyzer/Core/PathSensitive/Store.h index ef23b160a3c032..e08d5e104e9c0a 100644 --- a/clang/include/clang/StaticAnalyzer/Core/PathSensitive/Store.h +++ b/clang/include/clang/StaticAnalyzer/Core/PathSensitive/Store.h @@ -205,8 +205,15 @@ class StoreManager { /// invalidateRegions - Clears out the specified regions from the store, /// marking their values as unknown. Depending on the store, this may also /// invalidate additional regions that may have changed based on accessing - /// the given regions. Optionally, invalidates non-static globals as well. - /// \param[in] store The initial store + /// the given regions. If \p Call is non-null, then this also invalidates + /// non-static globals (but if \p Call is from a system header, then this is + /// limited to globals declared in system headers). + /// + /// Instead of calling this method directly, you should probably use + /// \c ProgramState::invalidateRegions, which calls this and then ensures that + /// the relevant checker callbacks are triggered. + /// + /// \param[in] store The initial store. /// \param[in] Values The values to invalidate. /// \param[in] E The current statement being evaluated. Used to conjure /// symbols to mark the values of invalidated regions.