1// Copyright 2018 The Abseil Authors.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7// https://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14//
15// -----------------------------------------------------------------------------
16// File: leak_check.h
17// -----------------------------------------------------------------------------
18//
19// This file contains functions that affect leak checking behavior within
20// targets built with the LeakSanitizer (LSan), a memory leak detector that is
21// integrated within the AddressSanitizer (ASan) as an additional component, or
22// which can be used standalone. LSan and ASan are included (or can be provided)
23// as additional components for most compilers such as Clang, gcc and MSVC.
24// Note: this leak checking API is not yet supported in MSVC.
25// Leak checking is enabled by default in all ASan builds.
26//
27// See https://github.com/google/sanitizers/wiki/AddressSanitizerLeakSanitizer
28//
29// -----------------------------------------------------------------------------
30#ifndef ABSL_DEBUGGING_LEAK_CHECK_H_
31#define ABSL_DEBUGGING_LEAK_CHECK_H_
32
33#include <cstddef>
34
35namespace absl {
36
37// HaveLeakSanitizer()
38//
39// Returns true if a leak-checking sanitizer (either ASan or standalone LSan) is
40// currently built into this target.
41bool HaveLeakSanitizer();
42
43// DoIgnoreLeak()
44//
45// Implements `IgnoreLeak()` below. This function should usually
46// not be called directly; calling `IgnoreLeak()` is preferred.
47void DoIgnoreLeak(const void* ptr);
48
49// IgnoreLeak()
50//
51// Instruct the leak sanitizer to ignore leak warnings on the object referenced
52// by the passed pointer, as well as all heap objects transitively referenced
53// by it. The passed object pointer can point to either the beginning of the
54// object or anywhere within it.
55//
56// Example:
57//
58// static T* obj = IgnoreLeak(new T(...));
59//
60// If the passed `ptr` does not point to an actively allocated object at the
61// time `IgnoreLeak()` is called, the call is a no-op; if it is actively
62// allocated, the object must not get deallocated later.
63//
64template <typename T>
65T* IgnoreLeak(T* ptr) {
66 DoIgnoreLeak(ptr);
67 return ptr;
68}
69
70// LeakCheckDisabler
71//
72// This helper class indicates that any heap allocations done in the code block
73// covered by the scoped object, which should be allocated on the stack, will
74// not be reported as leaks. Leak check disabling will occur within the code
75// block and any nested function calls within the code block.
76//
77// Example:
78//
79// void Foo() {
80// LeakCheckDisabler disabler;
81// ... code that allocates objects whose leaks should be ignored ...
82// }
83//
84// REQUIRES: Destructor runs in same thread as constructor
85class LeakCheckDisabler {
86 public:
87 LeakCheckDisabler();
88 LeakCheckDisabler(const LeakCheckDisabler&) = delete;
89 LeakCheckDisabler& operator=(const LeakCheckDisabler&) = delete;
90 ~LeakCheckDisabler();
91};
92
93// RegisterLivePointers()
94//
95// Registers `ptr[0,size-1]` as pointers to memory that is still actively being
96// referenced and for which leak checking should be ignored. This function is
97// useful if you store pointers in mapped memory, for memory ranges that we know
98// are correct but for which normal analysis would flag as leaked code.
99void RegisterLivePointers(const void* ptr, size_t size);
100
101// UnRegisterLivePointers()
102//
103// Deregisters the pointers previously marked as active in
104// `RegisterLivePointers()`, enabling leak checking of those pointers.
105void UnRegisterLivePointers(const void* ptr, size_t size);
106
107} // namespace absl
108
109#endif // ABSL_DEBUGGING_LEAK_CHECK_H_
110