LCOV - code coverage report
Current view: top level - include/llvm/CodeGen - GCStrategy.h (source / functions) Hit Total Coverage
Test: llvm-toolchain.info Lines: 4 6 66.7 %
Date: 2017-09-14 15:23:50 Functions: 1 4 25.0 %
Legend: Lines: hit not hit

          Line data    Source code
       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_CODEGEN_GCSTRATEGY_H
      51             : #define LLVM_CODEGEN_GCSTRATEGY_H
      52             : 
      53             : #include "llvm/ADT/None.h"
      54             : #include "llvm/ADT/Optional.h"
      55             : #include "llvm/Support/Registry.h"
      56             : #include <string>
      57             : 
      58             : namespace llvm {
      59             : 
      60             : class Type;
      61             : 
      62             : namespace GC {
      63             : 
      64             : /// PointKind - Used to indicate whether the address of the call instruction
      65             : /// or the address after the call instruction is listed in the stackmap.  For
      66             : /// most runtimes, PostCall safepoints are appropriate.
      67             : ///
      68             : enum PointKind {
      69             :   PreCall, ///< Instr is a call instruction.
      70             :   PostCall ///< Instr is the return address of a call.
      71             : };
      72             : 
      73             : } // end namespace GC
      74             : 
      75             : /// GCStrategy describes a garbage collector algorithm's code generation
      76             : /// requirements, and provides overridable hooks for those needs which cannot
      77             : /// be abstractly described.  GCStrategy objects must be looked up through
      78             : /// the Function.  The objects themselves are owned by the Context and must
      79             : /// be immutable.
      80          50 : class GCStrategy {
      81             : private:
      82             :   friend class GCModuleInfo;
      83             : 
      84             :   std::string Name;
      85             : 
      86             : protected:
      87             :   bool UseStatepoints = false; /// Uses gc.statepoints as opposed to gc.roots,
      88             :                                /// if set, none of the other options can be
      89             :                                /// anything but their default values.
      90             : 
      91             :   unsigned NeededSafePoints = 0;    ///< Bitmask of required safe points.
      92             :   bool CustomReadBarriers = false;  ///< Default is to insert loads.
      93             :   bool CustomWriteBarriers = false; ///< Default is to insert stores.
      94             :   bool CustomRoots = false;      ///< Default is to pass through to backend.
      95             :   bool InitRoots= true;          ///< If set, roots are nulled during lowering.
      96             :   bool UsesMetadata = false;     ///< If set, backend must emit metadata tables.
      97             : 
      98             : public:
      99             :   GCStrategy();
     100          50 :   virtual ~GCStrategy() = default;
     101             : 
     102             :   /// Return the name of the GC strategy.  This is the value of the collector
     103             :   /// name string specified on functions which use this strategy.
     104          18 :   const std::string &getName() const { return Name; }
     105             : 
     106             :   /// By default, write barriers are replaced with simple store
     107             :   /// instructions. If true, you must provide a custom pass to lower 
     108             :   /// calls to @llvm.gcwrite.
     109             :   bool customWriteBarrier() const { return CustomWriteBarriers; }
     110             : 
     111             :   /// By default, read barriers are replaced with simple load
     112             :   /// instructions. If true, you must provide a custom pass to lower 
     113             :   /// calls to @llvm.gcread.
     114             :   bool customReadBarrier() const { return CustomReadBarriers; }
     115             : 
     116             :   /// Returns true if this strategy is expecting the use of gc.statepoints,
     117             :   /// and false otherwise.
     118             :   bool useStatepoints() const { return UseStatepoints; }
     119             : 
     120             :   /** @name Statepoint Specific Properties */
     121             :   ///@{
     122             : 
     123             :   /// If the type specified can be reliably distinguished, returns true for
     124             :   /// pointers to GC managed locations and false for pointers to non-GC
     125             :   /// managed locations.  Note a GCStrategy can always return 'None' (i.e. an
     126             :   /// empty optional indicating it can't reliably distinguish.
     127           0 :   virtual Optional<bool> isGCManagedPointer(const Type *Ty) const {
     128           0 :     return None;
     129             :   }
     130             :   ///@}
     131             : 
     132             :   /** @name GCRoot Specific Properties
     133             :    * These properties and overrides only apply to collector strategies using
     134             :    * GCRoot.
     135             :    */
     136             :   ///@{
     137             : 
     138             :   /// True if safe points of any kind are required. By default, none are
     139             :   /// recorded.
     140             :   bool needsSafePoints() const { return NeededSafePoints != 0; }
     141             : 
     142             :   /// True if the given kind of safe point is required. By default, none are
     143             :   /// recorded.
     144             :   bool needsSafePoint(GC::PointKind Kind) const {
     145           8 :     return (NeededSafePoints & 1 << Kind) != 0;
     146             :   }
     147             : 
     148             :   /// By default, roots are left for the code generator so it can generate a
     149             :   /// stack map. If true, you must provide a custom pass to lower 
     150             :   /// calls to @llvm.gcroot.
     151             :   bool customRoots() const { return CustomRoots; }
     152             : 
     153             :   /// If set, gcroot intrinsics should initialize their allocas to null
     154             :   /// before the first use. This is necessary for most GCs and is enabled by
     155             :   /// default.
     156             :   bool initializeRoots() const { return InitRoots; }
     157             : 
     158             :   /// If set, appropriate metadata tables must be emitted by the back-end
     159             :   /// (assembler, JIT, or otherwise). For statepoint, this method is
     160             :   /// currently unsupported.  The stackmap information can be found in the
     161             :   /// StackMap section as described in the documentation.
     162             :   bool usesMetadata() const { return UsesMetadata; }
     163             : 
     164             :   ///@}
     165             : };
     166             : 
     167             : /// Subclasses of GCStrategy are made available for use during compilation by
     168             : /// adding them to the global GCRegistry.  This can done either within the
     169             : /// LLVM source tree or via a loadable plugin.  An example registeration
     170             : /// would be:
     171             : /// static GCRegistry::Add<CustomGC> X("custom-name",
     172             : ///        "my custom supper fancy gc strategy");
     173             : ///
     174             : /// Note that to use a custom GCMetadataPrinter w/gc.roots, you must also
     175             : /// register your GCMetadataPrinter subclass with the
     176             : /// GCMetadataPrinterRegistery as well.
     177             : using GCRegistry = Registry<GCStrategy>;
     178             : 
     179             : } // end namespace llvm
     180             : 
     181             : #endif // LLVM_CODEGEN_GCSTRATEGY_H

Generated by: LCOV version 1.13