|
| 1 | +//===--- Generators.h - "Coroutines" for doing traversals -------*- C++ -*-===// |
| 2 | +// |
| 3 | +// This source file is part of the Swift.org open source project |
| 4 | +// |
| 5 | +// Copyright (c) 2023 Apple Inc. and the Swift project authors |
| 6 | +// Licensed under Apache License v2.0 with Runtime Library Exception |
| 7 | +// |
| 8 | +// See https://swift.org/LICENSE.txt for license information |
| 9 | +// See https://swift.org/CONTRIBUTORS.txt for the list of Swift project authors |
| 10 | +// |
| 11 | +//===----------------------------------------------------------------------===// |
| 12 | +// |
| 13 | +// This file defines a few types for defining types that follow this |
| 14 | +// simple generator concept: |
| 15 | +// |
| 16 | +// concept Generator { |
| 17 | +// // ...some number of accessors for the current value... |
| 18 | +// |
| 19 | +// /// Is this generator finished producing values? |
| 20 | +// bool isFinished() const; |
| 21 | +// |
| 22 | +// /// Given that this generator is not finished, advance to the |
| 23 | +// /// next value. |
| 24 | +// void advance(); |
| 25 | +// |
| 26 | +// /// Finish the generator, asserting that all values have been |
| 27 | +// /// produced. |
| 28 | +// void finish(); |
| 29 | +// }; |
| 30 | +// |
| 31 | +// concept SimpleGenerator : Generator { |
| 32 | +// type reference; |
| 33 | +// |
| 34 | +// reference claimNext(); |
| 35 | +// } |
| 36 | +// |
| 37 | +// Generators are useful when some structure needs to be traversed but |
| 38 | +// that traversal can't be done in a simple lexical loop. For example, |
| 39 | +// you can't do two traversals in parallel with a single loop unless you |
| 40 | +// break down all the details of the traversal. This is a minor problem |
| 41 | +// for simple traversals like walking a flat array, but it's a significant |
| 42 | +// problem when traversals get more complex, like when different components |
| 43 | +// of an array are grouped together according to some additional structure |
| 44 | +// (such as the abstraction pattern of a function's parameter list). |
| 45 | +// It's tempting to write those traversals as higher-order functions that |
| 46 | +// invoke a callback for each element, but this breaks down when parallel |
| 47 | +// traversal is required. Expressing the traversal as a generator |
| 48 | +// allows the traversal logic to to be reused without that limitation. |
| 49 | +// |
| 50 | +//===----------------------------------------------------------------------===// |
| 51 | + |
| 52 | +#ifndef SWIFT_BASIC_GENERATORS_H |
| 53 | +#define SWIFT_BASIC_GENERATORS_H |
| 54 | + |
| 55 | +#include "llvm/ADT/ArrayRef.h" |
| 56 | + |
| 57 | +namespace swift { |
| 58 | + |
| 59 | +namespace generator_details { |
| 60 | + |
| 61 | +template <class T> |
| 62 | +struct is_array_ref_like { |
| 63 | + enum { value = false }; |
| 64 | +}; |
| 65 | + |
| 66 | +template <class T> |
| 67 | +struct is_array_ref_like<llvm::ArrayRef<T>> { |
| 68 | + enum { value = true }; |
| 69 | +}; |
| 70 | + |
| 71 | +template <class T> |
| 72 | +struct is_array_ref_like<llvm::MutableArrayRef<T>> { |
| 73 | + enum { value = true }; |
| 74 | +}; |
| 75 | +} |
| 76 | + |
| 77 | +/// A class for generating the elements of an ArrayRef-like collection. |
| 78 | +template <class CollectionType> |
| 79 | +class ArrayRefGenerator { |
| 80 | + static_assert(generator_details::is_array_ref_like<CollectionType>::value, |
| 81 | + "ArrayRefGenerator should only be used with ArrayRef-like " |
| 82 | + "types"); |
| 83 | + |
| 84 | + CollectionType values; |
| 85 | + |
| 86 | +public: |
| 87 | + using reference = |
| 88 | + typename std::iterator_traits<typename CollectionType::iterator>::reference; |
| 89 | + |
| 90 | + ArrayRefGenerator() {} |
| 91 | + ArrayRefGenerator(CollectionType values) : values(values) {} |
| 92 | + |
| 93 | + // Prevent accidental copying of the generator. |
| 94 | + ArrayRefGenerator(const ArrayRefGenerator &other) = delete; |
| 95 | + ArrayRefGenerator &operator=(const ArrayRefGenerator &other) = delete; |
| 96 | + |
| 97 | + ArrayRefGenerator(ArrayRefGenerator &&other) = default; |
| 98 | + ArrayRefGenerator &operator=(ArrayRefGenerator &&other) = default; |
| 99 | + |
| 100 | + /// Explicitly copy the current generator state. |
| 101 | + ArrayRefGenerator clone() const { |
| 102 | + return ArrayRefGenerator(values); |
| 103 | + } |
| 104 | + |
| 105 | + /// Return the current element of the array. |
| 106 | + reference getCurrent() const { |
| 107 | + assert(!isFinished()); |
| 108 | + return values.front(); |
| 109 | + } |
| 110 | + |
| 111 | + /// Claim the current element of the array and advance past it. |
| 112 | + reference claimNext() { |
| 113 | + assert(!isFinished()); |
| 114 | + reference result = getCurrent(); |
| 115 | + advance(); |
| 116 | + return result; |
| 117 | + } |
| 118 | + |
| 119 | + /// Claim the next N elements of the array and advance past them. |
| 120 | + CollectionType claimNext(size_t count) { |
| 121 | + assert(count <= values.size() && "claiming too many values"); |
| 122 | + CollectionType result = values.slice(0, count); |
| 123 | + values = values.slice(count); |
| 124 | + return result; |
| 125 | + } |
| 126 | + |
| 127 | + /// Is this generation finished? |
| 128 | + bool isFinished() const { |
| 129 | + return values.empty(); |
| 130 | + } |
| 131 | + |
| 132 | + /// Given that this generation is not finished, advance to the |
| 133 | + /// next element. |
| 134 | + void advance() { |
| 135 | + assert(!isFinished()); |
| 136 | + values = values.slice(1); |
| 137 | + } |
| 138 | + |
| 139 | + /// Perform any final work required to complete the generation. |
| 140 | + void finish() { |
| 141 | + assert(isFinished() && "didn't finish generating the collection"); |
| 142 | + } |
| 143 | +}; |
| 144 | + |
| 145 | +/// An abstracting reference to an existing generator. |
| 146 | +/// |
| 147 | +/// The implementation of this type holds the reference to the existing |
| 148 | +/// generator without allocating any additional storage; it is sufficient |
| 149 | +/// for the caller ensures that the object passed to the constructor |
| 150 | +/// stays valid. Values of this type can otherwise be safely copied |
| 151 | +/// around. |
| 152 | +template <class T> |
| 153 | +class SimpleGeneratorRef { |
| 154 | +public: |
| 155 | + using reference = T; |
| 156 | + |
| 157 | +private: |
| 158 | + struct VTable { |
| 159 | + bool (*isFinished)(const void *impl); |
| 160 | + reference (*claimNext)(void *impl); |
| 161 | + void (*advance)(void *impl); |
| 162 | + void (*finish)(void *impl); |
| 163 | + }; |
| 164 | + |
| 165 | + template <class G> struct VTableImpl { |
| 166 | + static constexpr VTable vtable = { |
| 167 | + [](const void *p) { return static_cast<const G*>(p)->isFinished(); }, |
| 168 | + [](void *p) -> reference { return static_cast<G*>(p)->claimNext(); }, |
| 169 | + [](void *p) { static_cast<G*>(p)->advance(); }, |
| 170 | + [](void *p) { static_cast<G*>(p)->finish(); }, |
| 171 | + }; |
| 172 | + }; |
| 173 | + |
| 174 | + const VTable *vtable; |
| 175 | + void *pointer; |
| 176 | + |
| 177 | +public: |
| 178 | + constexpr SimpleGeneratorRef() : vtable(nullptr), pointer(nullptr) {} |
| 179 | + |
| 180 | + template <class G> |
| 181 | + constexpr SimpleGeneratorRef(G &generator) |
| 182 | + : vtable(&VTableImpl<G>::vtable), pointer(&generator) {} |
| 183 | + |
| 184 | + /// Test whether this generator ref was initialized with a |
| 185 | + /// valid reference to a generator. |
| 186 | + explicit operator bool() const { |
| 187 | + return pointer != nullptr; |
| 188 | + } |
| 189 | + |
| 190 | + bool isFinished() const { |
| 191 | + assert(pointer); |
| 192 | + return vtable->isFinished(pointer); |
| 193 | + } |
| 194 | + |
| 195 | + reference claimNext() { |
| 196 | + assert(pointer); |
| 197 | + return vtable->claimNext(pointer); |
| 198 | + } |
| 199 | + |
| 200 | + void advance() { |
| 201 | + assert(pointer); |
| 202 | + vtable->advance(pointer); |
| 203 | + } |
| 204 | + |
| 205 | + void finish() { |
| 206 | + assert(pointer); |
| 207 | + vtable->finish(pointer); |
| 208 | + } |
| 209 | +}; |
| 210 | + |
| 211 | +} // end namespace swift |
| 212 | + |
| 213 | +#endif |
0 commit comments