1//===- llvm/ADT/EpochTracker.h - ADT epoch tracking --------------*- C++ -*-==//
2//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6//
7//===----------------------------------------------------------------------===//
8///
9/// \file
10/// This file defines the DebugEpochBase and DebugEpochBase::HandleBase classes.
11/// These can be used to write iterators that are fail-fast when LLVM is built
12/// with asserts enabled.
13///
14//===----------------------------------------------------------------------===//
15
16#ifndef LLVM_ADT_EPOCHTRACKER_H
17#define LLVM_ADT_EPOCHTRACKER_H
18
19#include "llvm/Config/abi-breaking.h"
20
21#include <cstdint>
22
23namespace llvm {
24
25#if LLVM_ENABLE_ABI_BREAKING_CHECKS
26#define LLVM_DEBUGEPOCHBASE_HANDLEBASE_EMPTYBASE
27
28/// A base class for data structure classes wishing to make iterators
29/// ("handles") pointing into themselves fail-fast. When building without
30/// asserts, this class is empty and does nothing.
31///
32/// DebugEpochBase does not by itself track handles pointing into itself. The
33/// expectation is that routines touching the handles will poll on
34/// isHandleInSync at appropriate points to assert that the handle they're using
35/// is still valid.
36///
37class DebugEpochBase {
38 uint64_t Epoch = 0;
39
40public:
41 DebugEpochBase() = default;
42
43 /// Calling incrementEpoch invalidates all handles pointing into the
44 /// calling instance.
45 void incrementEpoch() { ++Epoch; }
46
47 /// The destructor calls incrementEpoch to make use-after-free bugs
48 /// more likely to crash deterministically.
49 ~DebugEpochBase() { incrementEpoch(); }
50
51 /// A base class for iterator classes ("handles") that wish to poll for
52 /// iterator invalidating modifications in the underlying data structure.
53 /// When LLVM is built without asserts, this class is empty and does nothing.
54 ///
55 /// HandleBase does not track the parent data structure by itself. It expects
56 /// the routines modifying the data structure to call incrementEpoch when they
57 /// make an iterator-invalidating modification.
58 ///
59 class HandleBase {
60 const uint64_t *EpochAddress = nullptr;
61 uint64_t EpochAtCreation = UINT64_MAX;
62
63 public:
64 HandleBase() = default;
65
66 explicit HandleBase(const DebugEpochBase *Parent)
67 : EpochAddress(&Parent->Epoch), EpochAtCreation(Parent->Epoch) {}
68
69 /// Returns true if the DebugEpochBase this Handle is linked to has
70 /// not called incrementEpoch on itself since the creation of this
71 /// HandleBase instance.
72 bool isHandleInSync() const { return *EpochAddress == EpochAtCreation; }
73
74 /// Returns a pointer to the epoch word stored in the data structure
75 /// this handle points into. Can be used to check if two iterators point
76 /// into the same data structure.
77 const void *getEpochAddress() const { return EpochAddress; }
78 };
79};
80
81#else
82#ifdef _MSC_VER
83#define LLVM_DEBUGEPOCHBASE_HANDLEBASE_EMPTYBASE __declspec(empty_bases)
84#else
85#define LLVM_DEBUGEPOCHBASE_HANDLEBASE_EMPTYBASE
86#endif // _MSC_VER
87
88class DebugEpochBase {
89public:
90 void incrementEpoch() {}
91
92 class HandleBase {
93 public:
94 HandleBase() = default;
95 explicit HandleBase(const DebugEpochBase *) {}
96 bool isHandleInSync() const { return true; }
97 const void *getEpochAddress() const { return nullptr; }
98 };
99};
100
101#endif // LLVM_ENABLE_ABI_BREAKING_CHECKS
102
103} // namespace llvm
104
105#endif
106

source code of include/llvm-17/llvm/ADT/EpochTracker.h