From: James Sedgwick Date: Thu, 8 Jan 2015 15:51:15 +0000 (-0800) Subject: doxygen comments for Try X-Git-Tag: v0.22.0~21 X-Git-Url: http://demsky.eecs.uci.edu/git/?a=commitdiff_plain;h=4ea6cf430338d067f73b156a04a1fead6e57c341;p=folly.git 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 --- diff --git a/folly/wangle/futures/Try.h b/folly/wangle/futures/Try.h index a1101d37..b262556e 100644 --- a/folly/wangle/futures/Try.h +++ b/folly/wangle/futures/Try.h @@ -27,6 +27,16 @@ namespace folly { namespace wangle { +/* + * Try 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, which represents either success + * or an exception. + */ template class Try { static_assert(!std::is_reference::value, @@ -39,14 +49,45 @@ class Try { }; public: + /* + * The value type for the Try + */ typedef T element_type; + /* + * Construct an empty Try + */ 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) {} + + /* + * 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)) {} + + /* + * Construct a Try with an exception_wrapper + * + * @param e The exception_wrapper + */ explicit Try(exception_wrapper e) : contains_(Contains::EXCEPTION), e_(folly::make_unique(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 : contains_(Contains::EXCEPTION) { try { @@ -58,30 +99,78 @@ class Try { } } - // move + // Move constructor Try(Try&& t); + // Move assigner Try& operator=(Try&& t); - // no copy + // Non-copyable Try(const Try& t) = delete; + // Non-copyable Try& operator=(const Try& t) = delete; ~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(); + /* + * 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; + /* + * If the Try contains an exception, rethrow it. Otherwise do nothing. + */ 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(); } - T& operator*() { 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(); } + + /* + * 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(); } - T* operator->() { 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(); } + + /* + * @returns True if the Try contains a value, false otherwise + */ bool hasValue() const { return contains_ == Contains::VALUE; } + /* + * @returns True if the Try contains an exception, false otherwise + */ bool hasException() const { return contains_ == Contains::EXCEPTION; } + /* + * @returns True if the Try contains an exception of type Ex, false otherwise + */ template bool hasException() const { return hasException() && e_->is_compatible_with(); @@ -94,6 +183,13 @@ class Try { 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 bool withException(F func) const { if (!hasException()) { @@ -110,13 +206,31 @@ class Try { }; }; +/* + * Specialization of Try for void value type. Encapsulates either success or an + * exception. + */ template <> class Try { public: + // Construct a Try holding a successful and void result Try() : hasValue_(true) {} + + /* + * Construct a Try with an exception_wrapper + * + * @param e The exception_wrapper + */ explicit Try(exception_wrapper e) : hasValue_(false), e_(folly::make_unique(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) { try { std::rethrow_exception(ep); @@ -127,6 +241,7 @@ class Try { } } + // Copy assigner Try& operator=(const Try& t) { hasValue_ = t.hasValue_; if (t.e_) { @@ -134,23 +249,35 @@ class Try { } return *this; } + // Copy constructor Try(const Try& t) { *this = t; } + // If the Try contains an exception, throws it void value() const { throwIfFailed(); } + // Dereference operator. If the Try contains an exception, throws it void operator*() const { return value(); } + // If the Try contains an exception, throws it inline void throwIfFailed() const; + // @returns False if the Try contains an exception, true otherwise bool hasValue() const { return hasValue_; } + // @returns True if the Try contains an exception, false otherwise bool hasException() const { return !hasValue_; } + // @returns True if the Try contains an exception of type Ex, false otherwise template bool hasException() const { return hasException() && e_->is_compatible_with(); } + /* + * @throws WangleException if the Try doesn't contain an exception + * + * @returns mutable reference to the exception contained by this Try + */ exception_wrapper& exception() { if (UNLIKELY(!hasException())) { throw WangleException("exception(): Try does not contain an exception"); @@ -158,6 +285,13 @@ class Try { 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 bool withException(F func) const { if (!hasException()) { @@ -171,20 +305,27 @@ class Try { std::unique_ptr e_{nullptr}; }; -/** +/* * 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 T moveFromTry(wangle::Try&& t); -/** +/* * Throws if try contained an exception. + * + * @param t Try to move from */ void moveFromTry(wangle::Try&& t); -/** - * Constructs Try based on the result of execution of function f (e.g. result - * or exception). +/* + * @param f a function to execute and capture the result of (value or exception) + * + * @returns Try holding the result of f */ template typename std::enable_if< @@ -192,8 +333,12 @@ typename std::enable_if< Try::type>>::type 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 holding the result of f */ template typename std::enable_if<