//===-- llvm/CodeGen/GCStrategy.h - Garbage collection ----------*- C++ -*-===// // // The LLVM Compiler Infrastructure // // This file is distributed under the University of Illinois Open Source // License. See LICENSE.TXT for details. // //===----------------------------------------------------------------------===// // // GCStrategy coordinates code generation algorithms and implements some itself // in order to generate code compatible with a target code generator as // specified in a function's 'gc' attribute. Algorithms are enabled by setting // flags in a subclass's constructor, and some virtual methods can be // overridden. // // GCStrategy is relevant for implementations using either gc.root or // gc.statepoint based lowering strategies, but is currently focused mostly on // options for gc.root. This will change over time. // // When requested by a subclass of GCStrategy, the gc.root implementation will // populate GCModuleInfo and GCFunctionInfo with that about each Function in // the Module that opts in to garbage collection. Specifically: // // - Safe points // Garbage collection is generally only possible at certain points in code. // GCStrategy can request that the collector insert such points: // // - At and after any call to a subroutine // - Before returning from the current function // - Before backwards branches (loops) // // - Roots // When a reference to a GC-allocated object exists on the stack, it must be // stored in an alloca registered with llvm.gcoot. // // This information can used to emit the metadata tables which are required by // the target garbage collector runtime. // // When used with gc.statepoint, information about safepoint and roots can be // found in the binary StackMap section after code generation. Safepoint // placement is currently the responsibility of the frontend, though late // insertion support is planned. gc.statepoint does not currently support // custom stack map formats; such can be generated by parsing the standard // stack map section if desired. // // The read and write barrier support can be used with either implementation. // //===----------------------------------------------------------------------===// #ifndef LLVM_IR_GCSTRATEGY_H #define LLVM_IR_GCSTRATEGY_H #include "llvm/ADT/Optional.h" #include "llvm/IR/Function.h" #include "llvm/IR/Module.h" #include "llvm/IR/Value.h" #include "llvm/Support/ErrorHandling.h" #include "llvm/Support/Registry.h" #include namespace llvm { namespace GC { /// PointKind - Used to indicate whether the address of the call instruction /// or the address after the call instruction is listed in the stackmap. For /// most runtimes, PostCall safepoints are appropriate. /// enum PointKind { PreCall, ///< Instr is a call instruction. PostCall ///< Instr is the return address of a call. }; } /// GCStrategy describes a garbage collector algorithm's code generation /// requirements, and provides overridable hooks for those needs which cannot /// be abstractly described. GCStrategy objects must be looked up through /// the Function. The objects themselves are owned by the Context and must /// be immutable. class GCStrategy { private: std::string Name; friend class GCModuleInfo; protected: bool UseStatepoints; /// Uses gc.statepoints as opposed to gc.roots, /// if set, none of the other options can be /// anything but their default values. unsigned NeededSafePoints; ///< Bitmask of required safe points. bool CustomReadBarriers; ///< Default is to insert loads. bool CustomWriteBarriers; ///< Default is to insert stores. bool CustomRoots; ///< Default is to pass through to backend. bool InitRoots; ///< If set, roots are nulled during lowering. bool UsesMetadata; ///< If set, backend must emit metadata tables. public: GCStrategy(); virtual ~GCStrategy() {} /// Return the name of the GC strategy. This is the value of the collector /// name string specified on functions which use this strategy. const std::string &getName() const { return Name; } /// By default, write barriers are replaced with simple store /// instructions. If true, you must provide a custom pass to lower /// calls to @llvm.gcwrite. bool customWriteBarrier() const { return CustomWriteBarriers; } /// By default, read barriers are replaced with simple load /// instructions. If true, you must provide a custom pass to lower /// calls to @llvm.gcread. bool customReadBarrier() const { return CustomReadBarriers; } /// Returns true if this strategy is expecting the use of gc.statepoints, /// and false otherwise. bool useStatepoints() const { return UseStatepoints; } /** @name Statepoint Specific Properties */ ///@{ /// If the value specified can be reliably distinguished, returns true for /// pointers to GC managed locations and false for pointers to non-GC /// managed locations. Note a GCStrategy can always return 'None' (i.e. an /// empty optional indicating it can't reliably distinguish. virtual Optional isGCManagedPointer(const Value *V) const { return None; } ///@} /** @name GCRoot Specific Properties * These properties and overrides only apply to collector strategies using * GCRoot. */ ///@{ /// True if safe points of any kind are required. By default, none are /// recorded. bool needsSafePoints() const { return NeededSafePoints != 0; } /// True if the given kind of safe point is required. By default, none are /// recorded. bool needsSafePoint(GC::PointKind Kind) const { return (NeededSafePoints & 1 << Kind) != 0; } /// By default, roots are left for the code generator so it can generate a /// stack map. If true, you must provide a custom pass to lower /// calls to @llvm.gcroot. bool customRoots() const { return CustomRoots; } /// If set, gcroot intrinsics should initialize their allocas to null /// before the first use. This is necessary for most GCs and is enabled by /// default. bool initializeRoots() const { return InitRoots; } /// If set, appropriate metadata tables must be emitted by the back-end /// (assembler, JIT, or otherwise). For statepoint, this method is /// currently unsupported. The stackmap information can be found in the /// StackMap section as described in the documentation. bool usesMetadata() const { return UsesMetadata; } ///@} }; /// Subclasses of GCStrategy are made available for use during compilation by /// adding them to the global GCRegistry. This can done either within the /// LLVM source tree or via a loadable plugin. An example registeration /// would be: /// static GCRegistry::Add X("custom-name", /// "my custom supper fancy gc strategy"); /// /// Note that to use a custom GCMetadataPrinter w/gc.roots, you must also /// register your GCMetadataPrinter subclass with the /// GCMetadataPrinterRegistery as well. typedef Registry GCRegistry; } // namespace llvm #endif