Tom Cherry | 11a3aee | 2017-08-03 12:54:07 -0700 | [diff] [blame] | 1 | /* |
| 2 | * Copyright (C) 2017 The Android Open Source Project |
| 3 | * |
| 4 | * Licensed under the Apache License, Version 2.0 (the "License"); |
| 5 | * you may not use this file except in compliance with the License. |
| 6 | * You may obtain a copy of the License at |
| 7 | * |
| 8 | * http://www.apache.org/licenses/LICENSE-2.0 |
| 9 | * |
| 10 | * Unless required by applicable law or agreed to in writing, software |
| 11 | * distributed under the License is distributed on an "AS IS" BASIS, |
| 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 13 | * See the License for the specific language governing permissions and |
| 14 | * limitations under the License. |
| 15 | */ |
| 16 | |
| 17 | // This file contains classes for returning a successful result along with an optional |
| 18 | // arbitrarily typed return value or for returning a failure result along with an optional string |
| 19 | // indicating why the function failed. |
| 20 | |
| 21 | // There are 3 classes that implement this functionality and one additional helper type. |
| 22 | // |
| 23 | // Result<T> either contains a member of type T that can be accessed using similar semantics as |
Tom Cherry | 130e3d7 | 2017-08-22 16:07:15 -0700 | [diff] [blame] | 24 | // std::optional<T> or it contains a ResultError describing an error, which can be accessed via |
Tom Cherry | 11a3aee | 2017-08-03 12:54:07 -0700 | [diff] [blame] | 25 | // Result<T>::error(). |
| 26 | // |
Tom Cherry | 130e3d7 | 2017-08-22 16:07:15 -0700 | [diff] [blame] | 27 | // ResultError is a type that contains both a std::string describing the error and a copy of errno |
| 28 | // from when the error occurred. ResultError can be used in an ostream directly to print its |
| 29 | // string value. |
| 30 | // |
Tom Cherry | 11a3aee | 2017-08-03 12:54:07 -0700 | [diff] [blame] | 31 | // Success is a typedef that aids in creating Result<T> that do not contain a return value. |
Jiyong Park | 8fd64c8 | 2019-05-31 03:43:34 +0900 | [diff] [blame] | 32 | // Result<Nothing> is the correct return type for a function that either returns successfully or |
| 33 | // returns an error value. Returning Nothing() from a function that returns Result<Nothing> is the |
Tom Cherry | 11a3aee | 2017-08-03 12:54:07 -0700 | [diff] [blame] | 34 | // correct way to indicate that a function without a return type has completed successfully. |
| 35 | // |
| 36 | // A successful Result<T> is constructed implicitly from any type that can be implicitly converted |
| 37 | // to T or from the constructor arguments for T. This allows you to return a type T directly from |
| 38 | // a function that returns Result<T>. |
| 39 | // |
Tom Cherry | 130e3d7 | 2017-08-22 16:07:15 -0700 | [diff] [blame] | 40 | // Error and ErrnoError are used to construct a Result<T> that has failed. The Error class takes |
| 41 | // an ostream as an input and are implicitly cast to a Result<T> containing that failure. |
| 42 | // ErrnoError() is a helper function to create an Error class that appends ": " + strerror(errno) |
| 43 | // to the end of the failure string to aid in interacting with C APIs. Alternatively, an errno |
| 44 | // value can be directly specified via the Error() constructor. |
| 45 | // |
| 46 | // ResultError can be used in the ostream when using Error to construct a Result<T>. In this case, |
| 47 | // the string that the ResultError takes is passed through the stream normally, but the errno is |
| 48 | // passed to the Result<T>. This can be used to pass errno from a failing C function up multiple |
| 49 | // callers. |
| 50 | // |
| 51 | // ResultError can also directly construct a Result<T>. This is particularly useful if you have a |
| 52 | // function that return Result<T> but you have a Result<U> and want to return its error. In this |
| 53 | // case, you can return the .error() from the Result<U> to construct the Result<T>. |
Tom Cherry | 11a3aee | 2017-08-03 12:54:07 -0700 | [diff] [blame] | 54 | |
| 55 | // An example of how to use these is below: |
| 56 | // Result<U> CalculateResult(const T& input) { |
| 57 | // U output; |
| 58 | // if (!SomeOtherCppFunction(input, &output)) { |
| 59 | // return Error() << "SomeOtherCppFunction(" << input << ") failed"; |
| 60 | // } |
| 61 | // if (!c_api_function(output)) { |
| 62 | // return ErrnoError() << "c_api_function(" << output << ") failed"; |
| 63 | // } |
| 64 | // return output; |
| 65 | // } |
| 66 | // |
| 67 | // auto output = CalculateResult(input); |
| 68 | // if (!output) return Error() << "CalculateResult failed: " << output.error(); |
| 69 | // UseOutput(*output); |
| 70 | |
Tom Cherry | 9949ec5 | 2019-05-16 16:54:49 -0700 | [diff] [blame] | 71 | #pragma once |
Tom Cherry | 11a3aee | 2017-08-03 12:54:07 -0700 | [diff] [blame] | 72 | |
Jiyong Park | 8fd64c8 | 2019-05-31 03:43:34 +0900 | [diff] [blame] | 73 | #include <android-base/result.h> |
Tom Cherry | 11a3aee | 2017-08-03 12:54:07 -0700 | [diff] [blame] | 74 | |
Jiyong Park | 8fd64c8 | 2019-05-31 03:43:34 +0900 | [diff] [blame] | 75 | using android::base::ErrnoError; |
| 76 | using android::base::Error; |
| 77 | using android::base::Result; |
| 78 | using android::base::ResultError; |
| 79 | using android::base::Success; |