AllocToken.h

Go to the documentation of this file.

//===- llvm/Support/AllocToken.h - Allocation Token Calculation -----*- C++ -*//
//
// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
// See https://llvm.org/LICENSE.txt for license information.
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
//
//===----------------------------------------------------------------------===//
//
// Definition of AllocToken modes and shared calculation of stateless token IDs.
//
//===----------------------------------------------------------------------===//
 
#ifndef LLVM_SUPPORT_ALLOCTOKEN_H
#define LLVM_SUPPORT_ALLOCTOKEN_H
 
#include "llvm/ADT/SmallString.h"
#include "llvm/ADT/StringRef.h"
#include <cstdint>
#include <optional>
 
namespace llvm {
 
/// Modes for generating allocation token IDs.
enum class AllocTokenMode {
  /// Incrementally increasing token ID.
  Increment,
 
  /// Simple mode that returns a statically-assigned random token ID.
  Random,
 
  /// Token ID based on allocated type hash.
  TypeHash,
 
  /// Token ID based on allocated type hash, where the top half ID-space is
  /// reserved for types that contain pointers and the bottom half for types
  /// that do not contain pointers.
  TypeHashPointerSplit,
 
  /// Token ID based on allocated type hash and containing function name hash.
  /// Uses k bits if MaxTokens is 2^k-1 (e.g. SIZE_MAX), or
  /// floor(log2(MaxTokens)) bits otherwise.
  TypeFuncHash,
 
  /// Like TypeFuncHash, but for MaxTokens > 1 the most significant bit of the
  /// ID space is set for types that contain pointers.
  TypeFuncHashPointerSplit,
};
 
/// The default allocation token mode.
inline constexpr AllocTokenMode DefaultAllocTokenMode =
    AllocTokenMode::TypeHashPointerSplit;
 
/// Returns the AllocTokenMode from its canonical string name; if an invalid
/// name was provided returns nullopt.
LLVM_ABI std::optional<AllocTokenMode>
getAllocTokenModeFromString(StringRef Name);
 
/// Returns the canonical string name for the given AllocTokenMode.
LLVM_ABI StringRef getAllocTokenModeAsString(AllocTokenMode Mode);
 
/// Metadata about an allocation used to generate a token ID.
struct AllocTokenMetadata {
  SmallString<64> TypeName;
  bool ContainsPointer;
  /// Name of the function containing the allocation (TypeFuncHash modes).
  std::optional<SmallString<64>> FunctionName = std::nullopt;
};
 
/// Calculates stable allocation token ID. Returns std::nullopt for stateful
/// modes that are only available in the AllocToken pass, and for TypeFuncHash
/// modes if FunctionName is not set.
///
/// \param Mode The token generation mode.
/// \param Metadata The metadata about the allocation.
/// \param MaxTokens The maximum number of tokens (must not be 0)
/// \return The calculated allocation token ID, or std::nullopt.
LLVM_ABI std::optional<uint64_t>
getAllocToken(AllocTokenMode Mode, const AllocTokenMetadata &Metadata,
              uint64_t MaxTokens);
 
} // end namespace llvm
 
#endif // LLVM_SUPPORT_ALLOCTOKEN_H