1 //===- llvm/IR/MetadataTracking.h - Metadata tracking ---------------------===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 // Low-level functions to enable tracking of metadata that could RAUW.
12 //===----------------------------------------------------------------------===//
14 #ifndef LLVM_IR_METADATATRACKING_H
15 #define LLVM_IR_METADATATRACKING_H
17 #include "llvm/ADT/PointerUnion.h"
18 #include "llvm/Support/Casting.h"
19 #include <type_traits>
24 class MetadataAsValue;
26 /// \brief API for tracking metadata references through RAUW and deletion.
28 /// Shared API for updating \a Metadata pointers in subclasses that support
31 /// This API is not meant to be used directly. See \a TrackingMDRef for a
32 /// user-friendly tracking reference.
33 class MetadataTracking {
35 /// \brief Track the reference to metadata.
37 /// Register \c MD with \c *MD, if the subclass supports tracking. If \c *MD
38 /// gets RAUW'ed, \c MD will be updated to the new address. If \c *MD gets
39 /// deleted, \c MD will be set to \c nullptr.
41 /// If tracking isn't supported, \c *MD will not change.
43 /// \return true iff tracking is supported by \c MD.
44 static bool track(Metadata *&MD) {
45 return track(&MD, *MD, static_cast<Metadata *>(nullptr));
48 /// \brief Track the reference to metadata for \a Metadata.
50 /// As \a track(Metadata*&), but with support for calling back to \c Owner to
51 /// tell it that its operand changed. This could trigger \c Owner being
53 static bool track(void *Ref, Metadata &MD, Metadata &Owner) {
54 return track(Ref, MD, &Owner);
57 /// \brief Track the reference to metadata for \a MetadataAsValue.
59 /// As \a track(Metadata*&), but with support for calling back to \c Owner to
60 /// tell it that its operand changed. This could trigger \c Owner being
62 static bool track(void *Ref, Metadata &MD, MetadataAsValue &Owner) {
63 return track(Ref, MD, &Owner);
66 /// \brief Stop tracking a reference to metadata.
68 /// Stops \c *MD from tracking \c MD.
69 static void untrack(Metadata *&MD) { untrack(&MD, *MD); }
70 static void untrack(void *Ref, Metadata &MD);
72 /// \brief Move tracking from one reference to another.
74 /// Semantically equivalent to \c untrack(MD) followed by \c track(New),
75 /// except that ownership callbacks are maintained.
77 /// Note: it is an error if \c *MD does not equal \c New.
79 /// \return true iff tracking is supported by \c MD.
80 static bool retrack(Metadata *&MD, Metadata *&New) {
81 return retrack(&MD, *MD, &New);
83 static bool retrack(void *Ref, Metadata &MD, void *New);
85 /// \brief Check whether metadata is replaceable.
86 static bool isReplaceable(const Metadata &MD);
88 typedef PointerUnion<MetadataAsValue *, Metadata *> OwnerTy;
91 /// \brief Track a reference to metadata for an owner.
93 /// Generalized version of tracking.
94 static bool track(void *Ref, Metadata &MD, OwnerTy Owner);
97 } // end namespace llvm