[StreamExecutor] getOrDie and dieIfError utils

[jlebar]

streamexecutor/include/streamexecutor/StreamExecutor.h

30

that

[jhen]

• Fix comment typo spotted by jlebar

[jprice]

The getOrDie function seems to be generating an additional 'unchecked error' message when dying. For example, this trivial program (which should obviously generate an error):

#include <streamexecutor/streamexecutor.h>

namespace se = ::streamexecutor;

int main(int argc, char *argv[])
{
  se::Platform *platform =
    se::getOrDie(se::PlatformManager::getPlatformByName("foobar"));

  return 0;
}

generates this output:

Error extracting an expected value: no available platform with name foobar.
Program aborted due to an unhandled Error:
Error value was Success. (Note: Success values must still be checked prior to being destroyed).

Is this expected?

[jhen]

Thanks for the report, jprice. What you described is not expected behavior. You're right that the error should not be "unhandled".

So far, however, I can't reproduce that behavior. I think the example program you gave should fail in the same way as the example/example executable that is checked into StreamExecutor now. They both die because there is no platform registered for the required name, and they are both wrapped in getOrDie.

When you run the example executable, do you see the same behavior, because I only see the first line:

Error extracting an expected value: no available platform with name CUDA.

and no other error message.

If you are seeing the same problem with the example, I think there may be some difference in the versions of the LLVM support libraries we are using. Do you have a revision number for the LLVM you are using?

Thanks again for your help.

[jprice]

Hmm, maybe a false alarm.

It only seems to happen if I build SE in Release/RelWithDebInfo mode and then compile the test program without passing -DNDEBUG, which I guess conflicts with the SE build which would have used -DNDEBUG. I can't reproduce it with the example for that reason, unless I manually compile it without that flag. If SE is built in Debug mode as well, there is no issue.

[jhen]

It's good to know that we have to be careful with the compiler flags. I'll have to think more about the implications here, but maybe we need to include a se-config tool like llvm-config to help users get the right compiler flags. Or we might rethink the idea of using LLVM's libraries at all.

streamexecutor/examples/Example.cpp

 #include <cassert>
 #include <cstdio>
 #include <cstdlib>
 #include <memory>
 #include <vector>
 
 #include "streamexecutor/StreamExecutor.h"
 
-/// [Example saxpy host helper functions]
-// Example handler for streamexecutor::Expected return values.
-template <typename T> T getOrDie(streamexecutor::Expected<T> &&E) {
-  if (!E) {
-    std::fprintf(stderr, "Error extracting an expected value: %s.\n",
-                 streamexecutor::consumeAndGetMessage(E.takeError()).c_str());
-    std::exit(EXIT_FAILURE);
-  }
-  return std::move(*E);
-}
-
-// Example handler for streamexecutor::Error return values.
-void check(streamexecutor::Error &&E) {
-  if (E) {
-    std::fprintf(stderr, "Error encountered: %s.\n",
-                 streamexecutor::consumeAndGetMessage(std::move(E)).c_str());
-    std::exit(EXIT_FAILURE);
-  }
-}
-/// [Example saxpy host helper functions]
-
 /// [Example saxpy compiler-generated]
 // Code in this namespace is generated by the compiler (e.g. clang).
 //
 // The name of this namespace may depend on the compiler that generated it, so
 // this is just an example name.
 namespace __compilergen {
 
 // Specialization of the streamexecutor::Kernel template class for the parameter
int main() {
 
   // Run operations on a stream.
   std::unique_ptr<se::Stream> Stream = getOrDie(Device->createStream());
   Stream->thenCopyH2D<float>(HostX, X)
       .thenCopyH2D<float>(HostY, Y)
       .thenLaunch(ArraySize, 1, *Kernel, A, X, Y)
       .thenCopyD2H<float>(X, HostX);
   // Wait for the stream to complete.
-  check(Stream->blockHostUntilDone());
+  se::dieIfError(Stream->blockHostUntilDone());
 
   // Process output data in HostX.
   std::vector<float> ExpectedX = {4, 47, 90, 133};
   for (size_t I = 0; I < ArraySize; ++I) {
     assert(HostX[I] == ExpectedX[I]);
   }
 
   // Free device memory.
-  check(Device->freeDeviceMemory(X));
-  check(Device->freeDeviceMemory(Y));
+  se::dieIfError(Device->freeDeviceMemory(X));
+  se::dieIfError(Device->freeDeviceMemory(Y));
   /// [Example saxpy host main]
 }

streamexecutor/include/streamexecutor/StreamExecutor.h

 /// This version of StreamExecutor can be built either as a sub-project of the
 /// LLVM project or as a standalone project depending on LLVM as an external
 /// package.
 ///
 /// Below is an example of the use of the StreamExecutor API:
 ///
 /// \snippet examples/Example.cpp Example saxpy host main
 ///
-/// In the example, a couple of handler functions are used to handle error
-/// return values in the StreamExecutor API:
-///
-/// \snippet examples/Example.cpp Example saxpy host helper functions
-///
-/// These are just example handler functions. A real application will likely
-/// want to define similar handlers of its own that log errors in an
-/// application-specific way, convert errors to the application's own
-/// error-handling framework, or try to recover from errors as appropriate.
+/// In the example, a couple of handler functions, \c getOrDie and \c
+/// dieIfError, are used to handle error return values in the StreamExecutor
+/// API. These functions are provided by StreamExecutor for quick-and-dirty
+/// error handling, but real applications will likely want to define their own
+/// versions of these handlers so that errors are handled more gracefully that
+/// just exiting the program.
 ///
 /// The example also references some symbols from a compiler-generated
 /// namespace:
 ///
 /// \snippet examples/Example.cpp Example saxpy compiler-generated
 ///
 /// Instead of depending on the compiler to generate this code, you can
 /// technically write the code yourself, but this is not recommended because the

streamexecutor/include/streamexecutor/Utils/Error.h

 ///   }
 ///   ...
 /// }
 /// \endcode
 ///
 /// There is also a function consumeError that consumes an error value without
 /// fetching the error message. This is useful when we want to ignore an error.
 ///
+/// The dieIfError function is also provided for quick-and-dirty error handling.
+///
 ///
 /// \section expected The Expected Class
 ///
 /// The Expected<T> class either represents a value of type T or an Error.
 /// Expected<T> has one constructor that takes a T value and another constructor
 /// that takes an Error rvalue reference, so Expected instances can be
 /// constructed either from values or from errors:
 ///

 ///   }
 ///
 ///   // It's fine to return Expected<int> for Expected<double> because int can
 ///   // be converted to double.
 ///   return getMyFavoriteInt();
 /// }
 /// \endcode
 ///
+/// The getOrDie function is also available for quick-and-dirty error handling.
+///
 ///
 /// \section llvm Relation to llvm::Error and llvm::Expected
 ///
 /// The streamexecutor::Error and streamexecutor::Expected classes are actually
 /// just their LLVM counterparts redeclared in the streamexectuor namespace, but
 /// they should be treated as separate types, even so.
 ///
 /// StreamExecutor does not support any underlying llvm::ErrorInfo class except
 /// the one it defines internally for itself, so a streamexecutor::Error can be
 /// thought of as a restricted llvm::Error that is guaranteed to hold a specific
 /// error type.
 ///
 /// Although code may compile if llvm functions used to handle these
 /// StreamExecutor error types, it is likely that code will lead to runtime
 /// errors, so it is strongly recommended that only the functions from the
 /// streamexecutor namespace are used on these StreamExecutor error types.
 ///
 //===----------------------------------------------------------------------===//
 
 #ifndef STREAMEXECUTOR_UTILS_ERROR_H
 #define STREAMEXECUTOR_UTILS_ERROR_H
 
+#include <cstdio>
+#include <cstdlib>
 #include <memory>
 #include <string>
 
 #include "llvm/Support/Error.h"
 
 namespace streamexecutor {
 
 using llvm::consumeError;
 using llvm::Error;
 using llvm::Expected;
 using llvm::Twine;
 
-// Makes an Error object from an error message.
+/// Makes an Error object from an error message.
 Error make_error(Twine Message);
 
-// Consumes the input error and returns its error message.
-//
-// Assumes the input was created by the make_error function above.
+/// Consumes the input error and returns its error message.
+///
+/// Assumes the input was created by the make_error function above.
 std::string consumeAndGetMessage(Error &&E);
 
+/// Extracts the T value from an Expected<T> or prints an error message to
+/// stderr and exits the program with code EXIT_FAILURE if the Expected<T> is an
+/// error.
+///
+/// This function and the dieIfError function are provided for applications that
+/// are OK with aborting the program if an error occurs, and which don't have
+/// any special error logging needs. Applications with different error handling
+/// needs will likely want to declare their own functions with similar
+/// signatures but which log error messages in a different way or attempt to
+/// recover from errors instead of aborting the program.
+template <typename T> T getOrDie(Expected<T> &&E) {
+  if (!E) {
+    std::fprintf(stderr, "Error extracting an expected value: %s.\n",
+                 consumeAndGetMessage(E.takeError()).c_str());
+    std::exit(EXIT_FAILURE);
+  }
+  return std::move(*E);
+}
+
+/// Prints an error message to stderr and exits the program with code
+/// EXIT_FAILURE if the input is an error.
+///
+/// \sa getOrDie
+void dieIfError(Error &&E);
+
 } // namespace streamexecutor
 
 #endif // STREAMEXECUTOR_UTILS_ERROR_H

streamexecutor/lib/Utils/Error.cpp

std::string consumeAndGetMessage(Error &&E) {
   std::string Message;
   llvm::handleAllErrors(std::move(E),
                         [&Message](const StreamExecutorError &SEE) {
                           Message = SEE.getErrorMessage();
                         });
   return Message;
 }
 
+void dieIfError(Error &&E) {
+  if (E) {
+    std::fprintf(stderr, "Error encountered: %s.\n",
+                 streamexecutor::consumeAndGetMessage(std::move(E)).c_str());
+    std::exit(EXIT_FAILURE);
+  }
+}
+
 } // namespace streamexecutor