LLVM  14.0.0git
fallible_iterator.h
Go to the documentation of this file.
1 //===--- fallible_iterator.h - Wrapper for fallible iterators ---*- 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 #ifndef LLVM_ADT_FALLIBLE_ITERATOR_H
10 #define LLVM_ADT_FALLIBLE_ITERATOR_H
11 
14 #include "llvm/Support/Error.h"
15 
16 #include <type_traits>
17 
18 namespace llvm {
19 
20 /// A wrapper class for fallible iterators.
21 ///
22 /// The fallible_iterator template wraps an underlying iterator-like class
23 /// whose increment and decrement operations are replaced with fallible versions
24 /// like:
25 ///
26 /// @code{.cpp}
27 /// Error inc();
28 /// Error dec();
29 /// @endcode
30 ///
31 /// It produces an interface that is (mostly) compatible with a traditional
32 /// c++ iterator, including ++ and -- operators that do not fail.
33 ///
34 /// Instances of the wrapper are constructed with an instance of the
35 /// underlying iterator and (for non-end iterators) a reference to an Error
36 /// instance. If the underlying increment/decrement operations fail, the Error
37 /// is returned via this reference, and the resulting iterator value set to an
38 /// end-of-range sentinel value. This enables the following loop idiom:
39 ///
40 /// @code{.cpp}
41 /// class Archive { // E.g. Potentially malformed on-disk archive
42 /// public:
43 /// fallible_iterator<ArchiveChildItr> children_begin(Error &Err);
44 /// fallible_iterator<ArchiveChildItr> children_end();
45 /// iterator_range<fallible_iterator<ArchiveChildItr>>
46 /// children(Error &Err) {
47 /// return make_range(children_begin(Err), children_end());
48 /// //...
49 /// };
50 ///
51 /// void walk(Archive &A) {
52 /// Error Err = Error::success();
53 /// for (auto &C : A.children(Err)) {
54 /// // Loop body only entered when increment succeeds.
55 /// }
56 /// if (Err) {
57 /// // handle error.
58 /// }
59 /// }
60 /// @endcode
61 ///
62 /// The wrapper marks the referenced Error as unchecked after each increment
63 /// and/or decrement operation, and clears the unchecked flag when a non-end
64 /// value is compared against end (since, by the increment invariant, not being
65 /// an end value proves that there was no error, and is equivalent to checking
66 /// that the Error is success). This allows early exits from the loop body
67 /// without requiring redundant error checks.
68 template <typename Underlying> class fallible_iterator {
69 private:
70  template <typename T>
71  using enable_if_struct_deref_supported = std::enable_if<
72  !std::is_void<decltype(std::declval<T>().operator->())>::value,
73  decltype(std::declval<T>().operator->())>;
74 
75 public:
76  /// Construct a fallible iterator that *cannot* be used as an end-of-range
77  /// value.
78  ///
79  /// A value created by this method can be dereferenced, incremented,
80  /// decremented and compared, providing the underlying type supports it.
81  ///
82  /// The error that is passed in will be initially marked as checked, so if the
83  /// iterator is not used at all the Error need not be checked.
85  (void)!!Err;
86  return fallible_iterator(std::move(I), &Err);
87  }
88 
89  /// Construct a fallible iterator that can be used as an end-of-range value.
90  ///
91  /// A value created by this method can be dereferenced (if the underlying
92  /// value points at a valid value) and compared, but not incremented or
93  /// decremented.
95  return fallible_iterator(std::move(I), nullptr);
96  }
97 
98  /// Forward dereference to the underlying iterator.
99  decltype(auto) operator*() { return *I; }
100 
101  /// Forward const dereference to the underlying iterator.
102  decltype(auto) operator*() const { return *I; }
103 
104  /// Forward structure dereference to the underlying iterator (if the
105  /// underlying iterator supports it).
106  template <typename T = Underlying>
107  typename enable_if_struct_deref_supported<T>::type operator->() {
108  return I.operator->();
109  }
110 
111  /// Forward const structure dereference to the underlying iterator (if the
112  /// underlying iterator supports it).
113  template <typename T = Underlying>
114  typename enable_if_struct_deref_supported<const T>::type operator->() const {
115  return I.operator->();
116  }
117 
118  /// Increment the fallible iterator.
119  ///
120  /// If the underlying 'inc' operation fails, this will set the Error value
121  /// and update this iterator value to point to end-of-range.
122  ///
123  /// The Error value is marked as needing checking, regardless of whether the
124  /// 'inc' operation succeeds or fails.
126  assert(getErrPtr() && "Cannot increment end iterator");
127  if (auto Err = I.inc())
128  handleError(std::move(Err));
129  else
130  resetCheckedFlag();
131  return *this;
132  }
133 
134  /// Decrement the fallible iterator.
135  ///
136  /// If the underlying 'dec' operation fails, this will set the Error value
137  /// and update this iterator value to point to end-of-range.
138  ///
139  /// The Error value is marked as needing checking, regardless of whether the
140  /// 'dec' operation succeeds or fails.
142  assert(getErrPtr() && "Cannot decrement end iterator");
143  if (auto Err = I.dec())
144  handleError(std::move(Err));
145  else
146  resetCheckedFlag();
147  return *this;
148  }
149 
150  /// Compare fallible iterators for equality.
151  ///
152  /// Returns true if both LHS and RHS are end-of-range values, or if both are
153  /// non-end-of-range values whose underlying iterator values compare equal.
154  ///
155  /// If this is a comparison between an end-of-range iterator and a
156  /// non-end-of-range iterator, then the Error (referenced by the
157  /// non-end-of-range value) is marked as checked: Since all
158  /// increment/decrement operations result in an end-of-range value, comparing
159  /// false against end-of-range is equivalent to checking that the Error value
160  /// is success. This flag management enables early returns from loop bodies
161  /// without redundant Error checks.
162  friend bool operator==(const fallible_iterator &LHS,
163  const fallible_iterator &RHS) {
164  // If both iterators are in the end state they compare
165  // equal, regardless of whether either is valid.
166  if (LHS.isEnd() && RHS.isEnd())
167  return true;
168 
169  assert(LHS.isValid() && RHS.isValid() &&
170  "Invalid iterators can only be compared against end");
171 
172  bool Equal = LHS.I == RHS.I;
173 
174  // If the iterators differ and this is a comparison against end then mark
175  // the Error as checked.
176  if (!Equal) {
177  if (LHS.isEnd())
178  (void)!!*RHS.getErrPtr();
179  else
180  (void)!!*LHS.getErrPtr();
181  }
182 
183  return Equal;
184  }
185 
186  /// Compare fallible iterators for inequality.
187  ///
188  /// See notes for operator==.
189  friend bool operator!=(const fallible_iterator &LHS,
190  const fallible_iterator &RHS) {
191  return !(LHS == RHS);
192  }
193 
194 private:
196  : I(std::move(I)), ErrState(Err, false) {}
197 
198  Error *getErrPtr() const { return ErrState.getPointer(); }
199 
200  bool isEnd() const { return getErrPtr() == nullptr; }
201 
202  bool isValid() const { return !ErrState.getInt(); }
203 
204  void handleError(Error Err) {
205  *getErrPtr() = std::move(Err);
206  ErrState.setPointer(nullptr);
207  ErrState.setInt(true);
208  }
209 
210  void resetCheckedFlag() {
211  *getErrPtr() = Error::success();
212  }
213 
214  Underlying I;
215  mutable PointerIntPair<Error *, 1> ErrState;
216 };
217 
218 /// Convenience wrapper to make a fallible_iterator value from an instance
219 /// of an underlying iterator and an Error reference.
220 template <typename Underlying>
223 }
224 
225 /// Convenience wrapper to make a fallible_iterator end value from an instance
226 /// of an underlying iterator.
227 template <typename Underlying>
230 }
231 
232 template <typename Underlying>
233 iterator_range<fallible_iterator<Underlying>>
235  return make_range(make_fallible_itr(std::move(I), Err),
237 }
238 
239 } // end namespace llvm
240 
241 #endif // LLVM_ADT_FALLIBLE_ITERATOR_H
llvm::object::Equal
@ Equal
Definition: COFFModuleDefinition.cpp:38
llvm
---------------------— PointerInfo ------------------------------------—
Definition: AllocatorList.h:23
llvm::make_range
iterator_range< T > make_range(T x, T y)
Convenience function for iterating over sub-ranges.
Definition: iterator_range.h:53
llvm::make_fallible_end
fallible_iterator< Underlying > make_fallible_end(Underlying E)
Convenience wrapper to make a fallible_iterator end value from an instance of an underlying iterator.
Definition: fallible_iterator.h:228
llvm::Error::success
static ErrorSuccess success()
Create a success value.
Definition: Error.h:331
Error.h
llvm::BitmaskEnumDetail::Underlying
std::underlying_type_t< E > Underlying(E Val)
Check that Val is in range for E, and return Val cast to E's underlying type.
Definition: BitmaskEnum.h:90
llvm::fallible_iterator::operator!=
friend bool operator!=(const fallible_iterator &LHS, const fallible_iterator &RHS)
Compare fallible iterators for inequality.
Definition: fallible_iterator.h:189
llvm::fallible_iterator::operator==
friend bool operator==(const fallible_iterator &LHS, const fallible_iterator &RHS)
Compare fallible iterators for equality.
Definition: fallible_iterator.h:162
PointerIntPair.h
E
static GCRegistry::Add< CoreCLRGC > E("coreclr", "CoreCLR-compatible GC")
llvm::fallible_iterator::end
static fallible_iterator end(Underlying I)
Construct a fallible iterator that can be used as an end-of-range value.
Definition: fallible_iterator.h:94
false
Definition: StackSlotColoring.cpp:142
llvm::fallible_iterator::itr
static fallible_iterator itr(Underlying I, Error &Err)
Construct a fallible iterator that cannot be used as an end-of-range value.
Definition: fallible_iterator.h:84
llvm::fallible_iterator::operator->
enable_if_struct_deref_supported< T >::type operator->()
Forward structure dereference to the underlying iterator (if the underlying iterator supports it).
Definition: fallible_iterator.h:107
move
compiles ldr LCPI1_0 ldr ldr mov lsr tst moveq r1 ldr LCPI1_1 and r0 bx lr It would be better to do something like to fold the shift into the conditional move
Definition: README.txt:546
I
#define I(x, y, z)
Definition: MD5.cpp:59
assert
assert(ImpDefSCC.getReg()==AMDGPU::SCC &&ImpDefSCC.isDef())
llvm::move
OutputIt move(R &&Range, OutputIt Out)
Provide wrappers to std::move which take ranges instead of having to pass begin/end explicitly.
Definition: STLExtras.h:1609
iterator_range.h
llvm::fallible_iterator
A wrapper class for fallible iterators.
Definition: fallible_iterator.h:68
llvm::fallible_iterator::operator++
fallible_iterator & operator++()
Increment the fallible iterator.
Definition: fallible_iterator.h:125
std
Definition: BitVector.h:838
llvm::make_fallible_range
iterator_range< fallible_iterator< Underlying > > make_fallible_range(Underlying I, Underlying E, Error &Err)
Definition: fallible_iterator.h:234
llvm::Error
Lightweight error class with error context and mandatory checking.
Definition: Error.h:157
llvm::fallible_iterator::operator--
fallible_iterator & operator--()
Decrement the fallible iterator.
Definition: fallible_iterator.h:141
llvm::fallible_iterator::operator->
enable_if_struct_deref_supported< const T >::type operator->() const
Forward const structure dereference to the underlying iterator (if the underlying iterator supports i...
Definition: fallible_iterator.h:114
llvm::make_fallible_itr
fallible_iterator< Underlying > make_fallible_itr(Underlying I, Error &Err)
Convenience wrapper to make a fallible_iterator value from an instance of an underlying iterator and ...
Definition: fallible_iterator.h:221