include/llvm/CodeGen/GCStrategy.h

   1 //===-- llvm/CodeGen/GCStrategy.h - Garbage collection ----------*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file is distributed under the University of Illinois Open Source
   6 // License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9 //
  10 // GCStrategy coordinates code generation algorithms and implements some itself
  11 // in order to generate code compatible with a target code generator as
  12 // specified in a function's 'gc' attribute. Algorithms are enabled by setting
  13 // flags in a subclass's constructor, and some virtual methods can be
  14 // overridden.
  15 //
  16 // GCStrategy is relevant for implementations using either gc.root or
  17 // gc.statepoint based lowering strategies, but is currently focused mostly on
  18 // options for gc.root.  This will change over time.
  19 //
  20 // When requested by a subclass of GCStrategy, the gc.root implementation will
  21 // populate GCModuleInfo and GCFunctionInfo with that about each Function in
  22 // the Module that opts in to garbage collection.  Specifically:
  23 //
  24 // - Safe points
  25 //   Garbage collection is generally only possible at certain points in code.
  26 //   GCStrategy can request that the collector insert such points:
  27 //
  28 //     - At and after any call to a subroutine
  29 //     - Before returning from the current function
  30 //     - Before backwards branches (loops)
  31 //
  32 // - Roots
  33 //   When a reference to a GC-allocated object exists on the stack, it must be
  34 //   stored in an alloca registered with llvm.gcoot.
  35 //
  36 // This information can used to emit the metadata tables which are required by
  37 // the target garbage collector runtime.
  38 //
  39 // When used with gc.statepoint, information about safepoint and roots can be
  40 // found in the binary StackMap section after code generation.  Safepoint
  41 // placement is currently the responsibility of the frontend, though late
  42 // insertion support is planned.  gc.statepoint does not currently support
  43 // custom stack map formats; such can be generated by parsing the standard
  44 // stack map section if desired.
  45 //
  46 // The read and write barrier support can be used with either implementation.
  47 //
  48 //===----------------------------------------------------------------------===//
  49
  50 #ifndef LLVM_IR_GCSTRATEGY_H
  51 #define LLVM_IR_GCSTRATEGY_H
  52
  53 #include "llvm/ADT/Optional.h"
  54 #include "llvm/IR/Function.h"
  55 #include "llvm/IR/Module.h"
  56 #include "llvm/IR/Value.h"
  57 #include "llvm/Support/ErrorHandling.h"
  58 #include "llvm/Support/Registry.h"
  59 #include <string>
  60
  61 namespace llvm {
  62 namespace GC {
  63 /// PointKind - Used to indicate whether the address of the call instruction
  64 /// or the address after the call instruction is listed in the stackmap.  For
  65 /// most runtimes, PostCall safepoints are appropriate.
  66 ///
  67 enum PointKind {
  68   PreCall, ///< Instr is a call instruction.
  69   PostCall ///< Instr is the return address of a call.
  70 };
  71 }
  72
  73 /// GCStrategy describes a garbage collector algorithm's code generation
  74 /// requirements, and provides overridable hooks for those needs which cannot
  75 /// be abstractly described.  GCStrategy objects must be looked up through
  76 /// the Function.  The objects themselves are owned by the Context and must
  77 /// be immutable.
  78 class GCStrategy {
  79 private:
  80   std::string Name;
  81   friend class GCModuleInfo;
  82
  83 protected:
  84   bool UseStatepoints; /// Uses gc.statepoints as opposed to gc.roots,
  85                        /// if set, none of the other options can be
  86                        /// anything but their default values.
  87
  88   unsigned NeededSafePoints; ///< Bitmask of required safe points.
  89   bool CustomReadBarriers;   ///< Default is to insert loads.
  90   bool CustomWriteBarriers;  ///< Default is to insert stores.
  91   bool CustomRoots;          ///< Default is to pass through to backend.
  92   bool InitRoots;            ///< If set, roots are nulled during lowering.
  93   bool UsesMetadata;         ///< If set, backend must emit metadata tables.
  94
  95 public:
  96   GCStrategy();
  97   virtual ~GCStrategy() {}
  98
  99   /// Return the name of the GC strategy.  This is the value of the collector
 100   /// name string specified on functions which use this strategy.
 101   const std::string &getName() const { return Name; }
 102
 103   /// By default, write barriers are replaced with simple store
 104   /// instructions. If true, you must provide a custom pass to lower
 105   /// calls to @llvm.gcwrite.
 106   bool customWriteBarrier() const { return CustomWriteBarriers; }
 107
 108   /// By default, read barriers are replaced with simple load
 109   /// instructions. If true, you must provide a custom pass to lower
 110   /// calls to @llvm.gcread.
 111   bool customReadBarrier() const { return CustomReadBarriers; }
 112
 113   /// Returns true if this strategy is expecting the use of gc.statepoints,
 114   /// and false otherwise.
 115   bool useStatepoints() const { return UseStatepoints; }
 116
 117   /** @name Statepoint Specific Properties */
 118   ///@{
 119
 120   /// If the type specified can be reliably distinguished, returns true for
 121   /// pointers to GC managed locations and false for pointers to non-GC
 122   /// managed locations.  Note a GCStrategy can always return 'None' (i.e. an
 123   /// empty optional indicating it can't reliably distinguish.
 124   virtual Optional<bool> isGCManagedPointer(const Type *Ty) const {
 125     return None;
 126   }
 127   ///@}
 128
 129   /** @name GCRoot Specific Properties
 130    * These properties and overrides only apply to collector strategies using
 131    * GCRoot.
 132    */
 133   ///@{
 134
 135   /// True if safe points of any kind are required. By default, none are
 136   /// recorded.
 137   bool needsSafePoints() const { return NeededSafePoints != 0; }
 138
 139   /// True if the given kind of safe point is required. By default, none are
 140   /// recorded.
 141   bool needsSafePoint(GC::PointKind Kind) const {
 142     return (NeededSafePoints & 1 << Kind) != 0;
 143   }
 144
 145   /// By default, roots are left for the code generator so it can generate a
 146   /// stack map. If true, you must provide a custom pass to lower
 147   /// calls to @llvm.gcroot.
 148   bool customRoots() const { return CustomRoots; }
 149
 150   /// If set, gcroot intrinsics should initialize their allocas to null
 151   /// before the first use. This is necessary for most GCs and is enabled by
 152   /// default.
 153   bool initializeRoots() const { return InitRoots; }
 154
 155   /// If set, appropriate metadata tables must be emitted by the back-end
 156   /// (assembler, JIT, or otherwise). For statepoint, this method is
 157   /// currently unsupported.  The stackmap information can be found in the
 158   /// StackMap section as described in the documentation.
 159   bool usesMetadata() const { return UsesMetadata; }
 160
 161   ///@}
 162 };
 163
 164 /// Subclasses of GCStrategy are made available for use during compilation by
 165 /// adding them to the global GCRegistry.  This can done either within the
 166 /// LLVM source tree or via a loadable plugin.  An example registeration
 167 /// would be:
 168 /// static GCRegistry::Add<CustomGC> X("custom-name",
 169 ///        "my custom supper fancy gc strategy");
 170 ///
 171 /// Note that to use a custom GCMetadataPrinter w/gc.roots, you must also
 172 /// register your GCMetadataPrinter subclass with the
 173 /// GCMetadataPrinterRegistery as well.
 174 typedef Registry<GCStrategy> GCRegistry;
 175 }
 176
 177 #endif