Fix a race condition between the "ephemeral watchpoint disabling" and commands the...
[lldb.git] / parallel-libs / streamexecutor / include / streamexecutor / Error.h
1 //===-- Error.h - Error handling --------------------------------*- 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 /// \file
11 /// Error types used in the public API and internally in StreamExecutor.
12 ///
13 /// StreamExecutor's error handling is based on the types streamexecutor::Error
14 /// and streamexecutor::Expected<T>.
15 ///
16 ///
17 /// \section error The Error Class
18 ///
19 /// The Error class either represents success or contains an error message
20 /// describing the cause of the error. Error instances are created by calling
21 /// Error::success for successes or make_error for errors.
22 ///
23 /// \code{.cpp}
24 /// Error achieveWorldPeace() {
25 ///   if (WorldPeaceAlreadyAchieved) {
26 ///     return Error::success();
27 ///   } else {
28 ///     return make_error("Can't someone else do it?");
29 ///   }
30 /// }
31 /// \endcode
32 ///
33 /// Error instances are implicitly convertible to bool. Error values convert to
34 /// true and successes convert to false. Error instances must have their boolean
35 /// values checked or they must be moved before they go out of scope, otherwise
36 /// their destruction will cause the program to abort with a warning about an
37 /// unchecked Error.
38 ///
39 /// If the Error represents success, then checking the boolean value is all that
40 /// is required, but if the Error represents a real error, the Error value must
41 /// be consumed. The function consumeAndGetMessage is the way to extract the
42 /// error message from an Error and consume the Error at the same time, so
43 /// typical error handling will first check whether there was an error and then
44 /// extract the error message if so. Here is an example:
45 ///
46 /// \code{.cpp}
47 /// if (Error E = achieveWorldPeace()) {
48 ///   printf("An error occurred: %s\n", consumeAndGetMessage(E).c_str());
49 ///   exit(EXIT_FAILURE):
50 /// }
51 /// \endcode
52 ///
53 /// It is also common to simply pass an error along up the call stack if it
54 /// cannot be handled in the current function.
55 ///
56 /// \code{.cpp}
57 /// Error doTask() {
58 ///   if (Error E = achieveWorldPeace()) {
59 ///     return E;
60 ///   }
61 ///   ...
62 /// }
63 /// \endcode
64 ///
65 /// There is also a function consumeError that consumes an error value without
66 /// fetching the error message. This is useful when we want to ignore an error.
67 ///
68 /// The dieIfError function is also provided for quick-and-dirty error handling.
69 ///
70 ///
71 /// \section expected The Expected Class
72 ///
73 /// The Expected<T> class either represents a value of type T or an Error.
74 /// Expected<T> has one constructor that takes a T value and another constructor
75 /// that takes an Error rvalue reference, so Expected instances can be
76 /// constructed either from values or from errors:
77 ///
78 /// \code{.cpp}
79 /// Expected<int> getMyFavoriteInt() {
80 ///   int MyFavorite = 42;
81 ///   if (IsThereAFavorite) {
82 ///     return MyFavorite;
83 ///   } else {
84 ///     return make_error("I don't have a favorite");
85 ///   }
86 /// }
87 /// \endcode
88 ///
89 /// Expected<T> instances are implicitly convertible to bool and are true if
90 /// they contain a value and false if they contain an error. Note that this is
91 /// the opposite convention of the Error type conversion to bool, where true
92 /// meant error and false meant success.
93 ///
94 /// If the Expected<T> instance is not an error, the stored value can be
95 /// obtained by using operator*. If access to members of the value are desired
96 /// instead of the value itself, operator-> can be used as well.
97 ///
98 /// Expected<T> instances must have their boolean value checked or they must be
99 /// moved before they go out of scope, otherwise they will cause the program to
100 /// abort with a warning about an unchecked error. If the Expected<T> instance
101 /// contains a value, then checking the boolean value is all that is required,
102 /// but if it contains an Error object, that Error object must be handled by
103 /// calling Expected<T>::takeError() to get the underlying error.
104 ///
105 /// Here is an example of the use of an Expected<T> value returned from a
106 /// function:
107 ///
108 /// \code{.cpp}
109 /// Expected<int> ExpectedInt = getMyFavoriteInt();
110 /// if (ExpectedInt) {
111 ///   printf("My favorite integer is %d\n", *ExpectedInt);
112 /// } else {
113 ///   printf("An error occurred: %s\n",
114 ///     consumeAndGetMessage(ExpectedInt.takeError()));
115 ///   exit(EXIT_FAILURE);
116 /// }
117 /// \endcode
118 ///
119 /// The following snippet shows some examples of how Errors and Expected values
120 /// can be passed up the stack if they should not be handled in the current
121 /// function.
122 ///
123 /// \code{.cpp}
124 /// Expected<double> doTask3() {
125 ///   Error WorldPeaceError = achieveWorldPeace();
126 ///   if (!WorldPeaceError) {
127 ///     return WorldPeaceError;
128 ///   }
129 ///
130 ///   Expected<martian> ExpectedMartian = getMyFavoriteMartian();
131 ///   if (!ExpectedMartian) {
132 ///     // Must extract the error because martian cannot be converted to double.
133 ///     return ExpectedMartian.takeError():
134 ///   }
135 ///
136 ///   // It's fine to return Expected<int> for Expected<double> because int can
137 ///   // be converted to double.
138 ///   return getMyFavoriteInt();
139 /// }
140 /// \endcode
141 ///
142 /// The getOrDie function is also available for quick-and-dirty error handling.
143 ///
144 ///
145 /// \section llvm Relation to llvm::Error and llvm::Expected
146 ///
147 /// The streamexecutor::Error and streamexecutor::Expected classes are actually
148 /// just their LLVM counterparts redeclared in the streamexectuor namespace, but
149 /// they should be treated as separate types, even so.
150 ///
151 /// StreamExecutor does not support any underlying llvm::ErrorInfo class except
152 /// the one it defines internally for itself, so a streamexecutor::Error can be
153 /// thought of as a restricted llvm::Error that is guaranteed to hold a specific
154 /// error type.
155 ///
156 /// Although code may compile if llvm functions used to handle these
157 /// StreamExecutor error types, it is likely that code will lead to runtime
158 /// errors, so it is strongly recommended that only the functions from the
159 /// streamexecutor namespace are used on these StreamExecutor error types.
160 ///
161 //===----------------------------------------------------------------------===//
162
163 #ifndef STREAMEXECUTOR_ERROR_H
164 #define STREAMEXECUTOR_ERROR_H
165
166 #include <cstdio>
167 #include <cstdlib>
168 #include <memory>
169 #include <string>
170
171 #include "llvm/Support/Error.h"
172
173 namespace streamexecutor {
174
175 using llvm::consumeError;
176 using llvm::Error;
177 using llvm::Expected;
178 using llvm::Twine;
179
180 /// Makes an Error object from an error message.
181 Error make_error(const Twine &Message);
182
183 /// Consumes the input error and returns its error message.
184 ///
185 /// Assumes the input was created by the make_error function above.
186 std::string consumeAndGetMessage(Error &&E);
187
188 /// Extracts the T value from an Expected<T> or prints an error message to
189 /// stderr and exits the program with code EXIT_FAILURE if the Expected<T> is an
190 /// error.
191 ///
192 /// This function and the dieIfError function are provided for applications that
193 /// are OK with aborting the program if an error occurs, and which don't have
194 /// any special error logging needs. Applications with different error handling
195 /// needs will likely want to declare their own functions with similar
196 /// signatures but which log error messages in a different way or attempt to
197 /// recover from errors instead of aborting the program.
198 template <typename T> T getOrDie(Expected<T> &&E) {
199   if (!E) {
200     std::fprintf(stderr, "Error extracting an expected value: %s.\n",
201                  consumeAndGetMessage(E.takeError()).c_str());
202     std::exit(EXIT_FAILURE);
203   }
204   return std::move(*E);
205 }
206
207 /// Prints an error message to stderr and exits the program with code
208 /// EXIT_FAILURE if the input is an error.
209 ///
210 /// \sa getOrDie
211 void dieIfError(Error &&E);
212
213 } // namespace streamexecutor
214
215 #endif // STREAMEXECUTOR_ERROR_H