1//=== Registry.h - Linker-supported plugin registries -----------*- C++ -*-===//
2//
3// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
4// See https://llvm.org/LICENSE.txt for license information.
5// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
6//
7//===----------------------------------------------------------------------===//
8//
9// Defines a registry template for discovering pluggable modules.
10//
11//===----------------------------------------------------------------------===//
12
13#ifndef LLVM_SUPPORT_REGISTRY_H
14#define LLVM_SUPPORT_REGISTRY_H
15
16#include "llvm/ADT/STLExtras.h"
17#include "llvm/ADT/StringRef.h"
18#include "llvm/ADT/iterator_range.h"
19#include "llvm/Support/Compiler.h"
20#include "llvm/Support/DynamicLibrary.h"
21#include <memory>
22
23namespace llvm {
24  /// A simple registry entry which provides only a name, description, and
25  /// no-argument constructor.
26  template <typename T>
27  class SimpleRegistryEntry {
28    StringRef Name, Desc;
29    std::unique_ptr<T> (*Ctor)();
30
31  public:
32    SimpleRegistryEntry(StringRef N, StringRef D, std::unique_ptr<T> (*C)())
33        : Name(N), Desc(D), Ctor(C) {}
34
35    StringRef getName() const { return Name; }
36    StringRef getDesc() const { return Desc; }
37    std::unique_ptr<T> instantiate() const { return Ctor(); }
38  };
39
40  /// A global registry used in conjunction with static constructors to make
41  /// pluggable components (like targets or garbage collectors) "just work" when
42  /// linked with an executable.
43  template <typename T>
44  class Registry {
45  public:
46    typedef T type;
47    typedef SimpleRegistryEntry<T> entry;
48
49    class node;
50    class iterator;
51
52  private:
53    Registry() = delete;
54
55    friend class node;
56    static node *Head, *Tail;
57
58  public:
59    /// Node in linked list of entries.
60    ///
61    class node {
62      friend class iterator;
63      friend Registry<T>;
64
65      node *Next;
66      const entry& Val;
67
68    public:
69      node(const entry &V) : Next(nullptr), Val(V) {}
70    };
71
72    /// Add a node to the Registry: this is the interface between the plugin and
73    /// the executable.
74    ///
75    /// This function is exported by the executable and called by the plugin to
76    /// add a node to the executable's registry. Therefore it's not defined here
77    /// to avoid it being instantiated in the plugin and is instead defined in
78    /// the executable (see LLVM_INSTANTIATE_REGISTRY below).
79    static void add_node(node *N);
80
81    /// Iterators for registry entries.
82    ///
83    class iterator
84        : public llvm::iterator_facade_base<iterator, std::forward_iterator_tag,
85                                            const entry> {
86      const node *Cur;
87
88    public:
89      explicit iterator(const node *N) : Cur(N) {}
90
91      bool operator==(const iterator &That) const { return Cur == That.Cur; }
92      iterator &operator++() { Cur = Cur->Next; return *this; }
93      const entry &operator*() const { return Cur->Val; }
94    };
95
96    // begin is not defined here in order to avoid usage of an undefined static
97    // data member, instead it's instantiated by LLVM_INSTANTIATE_REGISTRY.
98    static iterator begin();
99    static iterator end()   { return iterator(nullptr); }
100
101    static iterator_range<iterator> entries() {
102      return make_range(begin(), end());
103    }
104
105    /// A static registration template. Use like such:
106    ///
107    ///   Registry<Collector>::Add<FancyGC>
108    ///   X("fancy-gc", "Newfangled garbage collector.");
109    ///
110    /// Use of this template requires that:
111    ///
112    ///  1. The registered subclass has a default constructor.
113    template <typename V>
114    class Add {
115      entry Entry;
116      node Node;
117
118      static std::unique_ptr<T> CtorFn() { return std::make_unique<V>(); }
119
120    public:
121      Add(StringRef Name, StringRef Desc)
122          : Entry(Name, Desc, CtorFn), Node(Entry) {
123        add_node(&Node);
124      }
125    };
126  };
127} // end namespace llvm
128
129/// Instantiate a registry class.
130///
131/// This provides template definitions of add_node, begin, and the Head and Tail
132/// pointers, then explicitly instantiates them. We could explicitly specialize
133/// them, instead of the two-step process of define then instantiate, but
134/// strictly speaking that's not allowed by the C++ standard (we would need to
135/// have explicit specialization declarations in all translation units where the
136/// specialization is used) so we don't.
137#define LLVM_INSTANTIATE_REGISTRY(REGISTRY_CLASS) \
138  namespace llvm { \
139  template<typename T> typename Registry<T>::node *Registry<T>::Head = nullptr;\
140  template<typename T> typename Registry<T>::node *Registry<T>::Tail = nullptr;\
141  template<typename T> \
142  void Registry<T>::add_node(typename Registry<T>::node *N) { \
143    if (Tail) \
144      Tail->Next = N; \
145    else \
146      Head = N; \
147    Tail = N; \
148  } \
149  template<typename T> typename Registry<T>::iterator Registry<T>::begin() { \
150    return iterator(Head); \
151  } \
152  template REGISTRY_CLASS::node *Registry<REGISTRY_CLASS::type>::Head; \
153  template REGISTRY_CLASS::node *Registry<REGISTRY_CLASS::type>::Tail; \
154  template \
155  void Registry<REGISTRY_CLASS::type>::add_node(REGISTRY_CLASS::node*); \
156  template REGISTRY_CLASS::iterator Registry<REGISTRY_CLASS::type>::begin(); \
157  }
158
159#endif // LLVM_SUPPORT_REGISTRY_H
160