Commit 4ea6cf43 authored by James Sedgwick's avatar James Sedgwick Committed by Viswanath Sivakumar

doxygen comments for Try

Summary:
One header at a time, starting with the small fry

I'm allowed to drink while I do this right? Good, because I don't think I ever had a choice.

Test Plan: generated doxygen and looked decent http://home.fburl.com/~jsedgwick/html/classfolly_1_1wangle_1_1Try.html

Reviewed By: davejwatson@fb.com

Subscribers: trunkagent, fugalh, njormrod, folly-diffs@

FB internal diff: D1677730

Tasks: 5480262

Signature: t1:1677730:1415899240:bdd03569a82be1c8def8c13786eae39b4a2a2f94
parent 352bbea6
...@@ -27,6 +27,16 @@ ...@@ -27,6 +27,16 @@
namespace folly { namespace wangle { namespace folly { namespace wangle {
/*
* Try<T> is a wrapper that contains either an instance of T, an exception, or
* nothing. Its primary use case is as a representation of a Promise or Future's
* result and so it provides a number of methods that are useful in that
* context. Exceptions are stored as exception_wrappers so that the user can
* minimize rethrows if so desired.
*
* There is a specialization, Try<void>, which represents either success
* or an exception.
*/
template <class T> template <class T>
class Try { class Try {
static_assert(!std::is_reference<T>::value, static_assert(!std::is_reference<T>::value,
...@@ -39,14 +49,45 @@ class Try { ...@@ -39,14 +49,45 @@ class Try {
}; };
public: public:
/*
* The value type for the Try
*/
typedef T element_type; typedef T element_type;
/*
* Construct an empty Try
*/
Try() : contains_(Contains::NOTHING) {} Try() : contains_(Contains::NOTHING) {}
/*
* Construct a Try with a value by copy
*
* @param v The value to copy in
*/
explicit Try(const T& v) : contains_(Contains::VALUE), value_(v) {} explicit Try(const T& v) : contains_(Contains::VALUE), value_(v) {}
/*
* Construct a Try with a value by move
*
* @param v The value to move in
*/
explicit Try(T&& v) : contains_(Contains::VALUE), value_(std::move(v)) {} explicit Try(T&& v) : contains_(Contains::VALUE), value_(std::move(v)) {}
/*
* Construct a Try with an exception_wrapper
*
* @param e The exception_wrapper
*/
explicit Try(exception_wrapper e) explicit Try(exception_wrapper e)
: contains_(Contains::EXCEPTION), : contains_(Contains::EXCEPTION),
e_(folly::make_unique<exception_wrapper>(std::move(e))) {} e_(folly::make_unique<exception_wrapper>(std::move(e))) {}
/*
* DEPRECATED
* Construct a Try with an exception_pointer
*
* @param ep The exception_pointer. Will be rethrown.
*/
explicit Try(std::exception_ptr ep) DEPRECATED explicit Try(std::exception_ptr ep) DEPRECATED
: contains_(Contains::EXCEPTION) { : contains_(Contains::EXCEPTION) {
try { try {
...@@ -58,30 +99,78 @@ class Try { ...@@ -58,30 +99,78 @@ class Try {
} }
} }
// move // Move constructor
Try(Try<T>&& t); Try(Try<T>&& t);
// Move assigner
Try& operator=(Try<T>&& t); Try& operator=(Try<T>&& t);
// no copy // Non-copyable
Try(const Try<T>& t) = delete; Try(const Try<T>& t) = delete;
// Non-copyable
Try& operator=(const Try<T>& t) = delete; Try& operator=(const Try<T>& t) = delete;
~Try(); ~Try();
/*
* Get a mutable reference to the contained value. If the Try contains an
* exception it will be rethrown.
*
* @returns mutable reference to the contained value
*/
T& value(); T& value();
/*
* Get a const reference to the contained value. If the Try contains an
* exception it will be rethrown.
*
* @returns const reference to the contained value
*/
const T& value() const; const T& value() const;
/*
* If the Try contains an exception, rethrow it. Otherwise do nothing.
*/
void throwIfFailed() const; void throwIfFailed() const;
/*
* Const dereference operator. If the Try contains an exception it will be
* rethrown.
*
* @returns const reference to the contained value
*/
const T& operator*() const { return value(); } const T& operator*() const { return value(); }
/*
* Dereference operator. If the Try contains an exception it will be rethrown.
*
* @returns mutable reference to the contained value
*/
T& operator*() { return value(); } T& operator*() { return value(); }
/*
* Const arrow operator. If the Try contains an exception it will be
* rethrown.
*
* @returns const reference to the contained value
*/
const T* operator->() const { return &value(); } const T* operator->() const { return &value(); }
/*
* Arrow operator. If the Try contains an exception it will be rethrown.
*
* @returns mutable reference to the contained value
*/
T* operator->() { return &value(); } T* operator->() { return &value(); }
/*
* @returns True if the Try contains a value, false otherwise
*/
bool hasValue() const { return contains_ == Contains::VALUE; } bool hasValue() const { return contains_ == Contains::VALUE; }
/*
* @returns True if the Try contains an exception, false otherwise
*/
bool hasException() const { return contains_ == Contains::EXCEPTION; } bool hasException() const { return contains_ == Contains::EXCEPTION; }
/*
* @returns True if the Try contains an exception of type Ex, false otherwise
*/
template <class Ex> template <class Ex>
bool hasException() const { bool hasException() const {
return hasException() && e_->is_compatible_with<Ex>(); return hasException() && e_->is_compatible_with<Ex>();
...@@ -94,6 +183,13 @@ class Try { ...@@ -94,6 +183,13 @@ class Try {
return *e_; return *e_;
} }
/*
* If the Try contains an exception and it is of type Ex, execute func(Ex)
*
* @param func a function that takes a single parameter of type const Ex&
*
* @returns True if the Try held an Ex and func was executed, false otherwise
*/
template <class Ex, class F> template <class Ex, class F>
bool withException(F func) const { bool withException(F func) const {
if (!hasException()) { if (!hasException()) {
...@@ -110,13 +206,31 @@ class Try { ...@@ -110,13 +206,31 @@ class Try {
}; };
}; };
/*
* Specialization of Try for void value type. Encapsulates either success or an
* exception.
*/
template <> template <>
class Try<void> { class Try<void> {
public: public:
// Construct a Try holding a successful and void result
Try() : hasValue_(true) {} Try() : hasValue_(true) {}
/*
* Construct a Try with an exception_wrapper
*
* @param e The exception_wrapper
*/
explicit Try(exception_wrapper e) explicit Try(exception_wrapper e)
: hasValue_(false), : hasValue_(false),
e_(folly::make_unique<exception_wrapper>(std::move(e))) {} e_(folly::make_unique<exception_wrapper>(std::move(e))) {}
/*
* DEPRECATED
* Construct a Try with an exception_pointer
*
* @param ep The exception_pointer. Will be rethrown.
*/
explicit Try(std::exception_ptr ep) DEPRECATED : hasValue_(false) { explicit Try(std::exception_ptr ep) DEPRECATED : hasValue_(false) {
try { try {
std::rethrow_exception(ep); std::rethrow_exception(ep);
...@@ -127,6 +241,7 @@ class Try<void> { ...@@ -127,6 +241,7 @@ class Try<void> {
} }
} }
// Copy assigner
Try& operator=(const Try<void>& t) { Try& operator=(const Try<void>& t) {
hasValue_ = t.hasValue_; hasValue_ = t.hasValue_;
if (t.e_) { if (t.e_) {
...@@ -134,23 +249,35 @@ class Try<void> { ...@@ -134,23 +249,35 @@ class Try<void> {
} }
return *this; return *this;
} }
// Copy constructor
Try(const Try<void>& t) { Try(const Try<void>& t) {
*this = t; *this = t;
} }
// If the Try contains an exception, throws it
void value() const { throwIfFailed(); } void value() const { throwIfFailed(); }
// Dereference operator. If the Try contains an exception, throws it
void operator*() const { return value(); } void operator*() const { return value(); }
// If the Try contains an exception, throws it
inline void throwIfFailed() const; inline void throwIfFailed() const;
// @returns False if the Try contains an exception, true otherwise
bool hasValue() const { return hasValue_; } bool hasValue() const { return hasValue_; }
// @returns True if the Try contains an exception, false otherwise
bool hasException() const { return !hasValue_; } bool hasException() const { return !hasValue_; }
// @returns True if the Try contains an exception of type Ex, false otherwise
template <class Ex> template <class Ex>
bool hasException() const { bool hasException() const {
return hasException() && e_->is_compatible_with<Ex>(); return hasException() && e_->is_compatible_with<Ex>();
} }
/*
* @throws WangleException if the Try doesn't contain an exception
*
* @returns mutable reference to the exception contained by this Try
*/
exception_wrapper& exception() { exception_wrapper& exception() {
if (UNLIKELY(!hasException())) { if (UNLIKELY(!hasException())) {
throw WangleException("exception(): Try does not contain an exception"); throw WangleException("exception(): Try does not contain an exception");
...@@ -158,6 +285,13 @@ class Try<void> { ...@@ -158,6 +285,13 @@ class Try<void> {
return *e_; return *e_;
} }
/*
* If the Try contains an exception and it is of type Ex, execute func(Ex)
*
* @param func a function that takes a single parameter of type const Ex&
*
* @returns True if the Try held an Ex and func was executed, false otherwise
*/
template <class Ex, class F> template <class Ex, class F>
bool withException(F func) const { bool withException(F func) const {
if (!hasException()) { if (!hasException()) {
...@@ -171,20 +305,27 @@ class Try<void> { ...@@ -171,20 +305,27 @@ class Try<void> {
std::unique_ptr<exception_wrapper> e_{nullptr}; std::unique_ptr<exception_wrapper> e_{nullptr};
}; };
/** /*
* Extracts value from try and returns it. Throws if try contained an exception. * Extracts value from try and returns it. Throws if try contained an exception.
*
* @param t Try to extract value from
*
* @returns value contained in t
*/ */
template <typename T> template <typename T>
T moveFromTry(wangle::Try<T>&& t); T moveFromTry(wangle::Try<T>&& t);
/** /*
* Throws if try contained an exception. * Throws if try contained an exception.
*
* @param t Try to move from
*/ */
void moveFromTry(wangle::Try<void>&& t); void moveFromTry(wangle::Try<void>&& t);
/** /*
* Constructs Try based on the result of execution of function f (e.g. result * @param f a function to execute and capture the result of (value or exception)
* or exception). *
* @returns Try holding the result of f
*/ */
template <typename F> template <typename F>
typename std::enable_if< typename std::enable_if<
...@@ -192,8 +333,12 @@ typename std::enable_if< ...@@ -192,8 +333,12 @@ typename std::enable_if<
Try<typename std::result_of<F()>::type>>::type Try<typename std::result_of<F()>::type>>::type
makeTryFunction(F&& f); makeTryFunction(F&& f);
/** /*
* makeTryFunction specialization for void functions. * Specialization of makeTryFunction for void
*
* @param f a function to execute and capture the result of
*
* @returns Try<void> holding the result of f
*/ */
template <typename F> template <typename F>
typename std::enable_if< typename std::enable_if<
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment