| // Copyright 2018 The Abseil Authors. | |
| // | |
| // Licensed under the Apache License, Version 2.0 (the "License"); | |
| // you may not use this file except in compliance with the License. | |
| // You may obtain a copy of the License at | |
| // | |
| // https://www.apache.org/licenses/LICENSE-2.0 | |
| // | |
| // Unless required by applicable law or agreed to in writing, software | |
| // distributed under the License is distributed on an "AS IS" BASIS, | |
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. | |
| // See the License for the specific language governing permissions and | |
| // limitations under the License. | |
| // | |
| // ----------------------------------------------------------------------------- | |
| // File: leak_check.h | |
| // ----------------------------------------------------------------------------- | |
| // | |
| // This file contains functions that affect leak checking behavior within | |
| // targets built with the LeakSanitizer (LSan), a memory leak detector that is | |
| // integrated within the AddressSanitizer (ASan) as an additional component, or | |
| // which can be used standalone. LSan and ASan are included (or can be provided) | |
| // as additional components for most compilers such as Clang, gcc and MSVC. | |
| // Note: this leak checking API is not yet supported in MSVC. | |
| // Leak checking is enabled by default in all ASan builds. | |
| // | |
| // https://clang.llvm.org/docs/LeakSanitizer.html | |
| // https://github.com/google/sanitizers/wiki/AddressSanitizerLeakSanitizer | |
| // | |
| // GCC and Clang both automatically enable LeakSanitizer when AddressSanitizer | |
| // is enabled. To use the mode, simply pass `-fsanitize=address` to both the | |
| // compiler and linker. An example Bazel command could be | |
| // | |
| // $ bazel test --copt=-fsanitize=address --linkopt=-fsanitize=address ... | |
| // | |
| // GCC and Clang auto support a standalone LeakSanitizer mode (a mode which does | |
| // not also use AddressSanitizer). To use the mode, simply pass | |
| // `-fsanitize=leak` to both the compiler and linker. Since GCC does not | |
| // currently provide a way of detecting this mode at compile-time, GCC users | |
| // must also pass -DLEAK_SANITIZER to the compiler. An example Bazel command | |
| // could be | |
| // | |
| // $ bazel test --copt=-DLEAK_SANITIZER --copt=-fsanitize=leak | |
| // --linkopt=-fsanitize=leak ... | |
| // | |
| // ----------------------------------------------------------------------------- | |
| namespace absl { | |
| ABSL_NAMESPACE_BEGIN | |
| // HaveLeakSanitizer() | |
| // | |
| // Returns true if a leak-checking sanitizer (either ASan or standalone LSan) is | |
| // currently built into this target. | |
| bool HaveLeakSanitizer(); | |
| // LeakCheckerIsActive() | |
| // | |
| // Returns true if a leak-checking sanitizer (either ASan or standalone LSan) is | |
| // currently built into this target and is turned on. | |
| bool LeakCheckerIsActive(); | |
| // DoIgnoreLeak() | |
| // | |
| // Implements `IgnoreLeak()` below. This function should usually | |
| // not be called directly; calling `IgnoreLeak()` is preferred. | |
| void DoIgnoreLeak(const void* ptr); | |
| // IgnoreLeak() | |
| // | |
| // Instruct the leak sanitizer to ignore leak warnings on the object referenced | |
| // by the passed pointer, as well as all heap objects transitively referenced | |
| // by it. The passed object pointer can point to either the beginning of the | |
| // object or anywhere within it. | |
| // | |
| // Example: | |
| // | |
| // static T* obj = IgnoreLeak(new T(...)); | |
| // | |
| // If the passed `ptr` does not point to an actively allocated object at the | |
| // time `IgnoreLeak()` is called, the call is a no-op; if it is actively | |
| // allocated, leak sanitizer will assume this object is referenced even if | |
| // there is no actual reference in user memory. | |
| // | |
| template <typename T> | |
| T* IgnoreLeak(T* ptr) { | |
| DoIgnoreLeak(ptr); | |
| return ptr; | |
| } | |
| // FindAndReportLeaks() | |
| // | |
| // If any leaks are detected, prints a leak report and returns true. This | |
| // function may be called repeatedly, and does not affect end-of-process leak | |
| // checking. | |
| // | |
| // Example: | |
| // if (FindAndReportLeaks()) { | |
| // ... diagnostic already printed. Exit with failure code. | |
| // exit(1) | |
| // } | |
| bool FindAndReportLeaks(); | |
| // LeakCheckDisabler | |
| // | |
| // This helper class indicates that any heap allocations done in the code block | |
| // covered by the scoped object, which should be allocated on the stack, will | |
| // not be reported as leaks. Leak check disabling will occur within the code | |
| // block and any nested function calls within the code block. | |
| // | |
| // Example: | |
| // | |
| // void Foo() { | |
| // LeakCheckDisabler disabler; | |
| // ... code that allocates objects whose leaks should be ignored ... | |
| // } | |
| // | |
| // REQUIRES: Destructor runs in same thread as constructor | |
| class LeakCheckDisabler { | |
| public: | |
| LeakCheckDisabler(); | |
| LeakCheckDisabler(const LeakCheckDisabler&) = delete; | |
| LeakCheckDisabler& operator=(const LeakCheckDisabler&) = delete; | |
| ~LeakCheckDisabler(); | |
| }; | |
| // RegisterLivePointers() | |
| // | |
| // Registers `ptr[0,size-1]` as pointers to memory that is still actively being | |
| // referenced and for which leak checking should be ignored. This function is | |
| // useful if you store pointers in mapped memory, for memory ranges that we know | |
| // are correct but for which normal analysis would flag as leaked code. | |
| void RegisterLivePointers(const void* ptr, size_t size); | |
| // UnRegisterLivePointers() | |
| // | |
| // Deregisters the pointers previously marked as active in | |
| // `RegisterLivePointers()`, enabling leak checking of those pointers. | |
| void UnRegisterLivePointers(const void* ptr, size_t size); | |
| ABSL_NAMESPACE_END | |
| } // namespace absl | |