futures/Deprecated.h \
futures/Future-inl.h \
futures/Future.h \
+ futures/FutureException.h \
futures/InlineExecutor.h \
futures/ManualExecutor.h \
futures/OpaqueCallbackShunt.h \
futures/Timekeeper.h \
futures/Try-inl.h \
futures/Try.h \
- futures/WangleException.h \
futures/detail/Core.h \
futures/detail/FSM.h \
futures/detail/ThreadWheelTimekeeper.h \
#include <folly/futures/Deprecated.h>
#include <folly/futures/Promise.h>
#include <folly/futures/Try.h>
-#include <folly/futures/WangleException.h>
+#include <folly/futures/FutureException.h>
#include <folly/futures/detail/Types.h>
namespace folly {
/// Duration typedef of a `std::chrono` duration type indicates the
/// resolution you can expect to be meaningful (milliseconds at the time of
/// writing). Normally you wouldn't need to specify a Timekeeper, we will
- /// use the global wangle timekeeper (we run a thread whose job it is to
- /// keep time for wangle timeouts) but we provide the option for power
+ /// use the global futures timekeeper (we run a thread whose job it is to
+ /// keep time for futures timeouts) but we provide the option for power
/// users.
///
/// The Timekeeper thread will be lazily created the first time it is
--- /dev/null
+/*
+ * Copyright 2014 Facebook, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+
+#include <exception>
+#include <string>
+
+namespace folly {
+
+class FutureException : public std::exception {
+
+public:
+
+ explicit FutureException(std::string message_arg)
+ : message(message_arg) {}
+
+ ~FutureException() throw(){}
+
+ virtual const char *what() const throw() {
+ return message.c_str();
+ }
+
+ bool operator==(const FutureException &other) const{
+ return other.message == this->message;
+ }
+
+ bool operator!=(const FutureException &other) const{
+ return !(*this == other);
+ }
+
+ protected:
+ std::string message;
+};
+
+class BrokenPromise : public FutureException {
+ public:
+ explicit BrokenPromise() :
+ FutureException("Broken promise") { }
+};
+
+class NoState : public FutureException {
+ public:
+ explicit NoState() : FutureException("No state") { }
+};
+
+class PromiseAlreadySatisfied : public FutureException {
+ public:
+ explicit PromiseAlreadySatisfied() :
+ FutureException("Promise already satisfied") { }
+};
+
+class FutureNotReady : public FutureException {
+ public:
+ explicit FutureNotReady() :
+ FutureException("Future not ready") { }
+};
+
+class FutureAlreadyRetrieved : public FutureException {
+ public:
+ explicit FutureAlreadyRetrieved () :
+ FutureException("Future already retrieved") { }
+};
+
+class UsingUninitializedTry : public FutureException {
+ public:
+ explicit UsingUninitializedTry() :
+ FutureException("Using unitialized try") { }
+};
+
+class FutureCancellation : public FutureException {
+ public:
+ FutureCancellation() : FutureException("Future was cancelled") {}
+};
+
+class TimedOut : public FutureException {
+ public:
+ TimedOut() : FutureException("Timed out") {}
+};
+
+}
#include <atomic>
#include <thread>
-#include <folly/futures/WangleException.h>
+#include <folly/futures/FutureException.h>
#include <folly/futures/detail/Core.h>
namespace folly {
-# Wangle
-Wangle is a framework for expressing asynchronous code in C++ using the Future pattern.
+# folly::Futures
-**wan•gle** |ˈwaNGgəl| informal
-*verb*
-Obtain (something that is desired) by persuading others to comply or by manipulating events.
+Futures is a futures-based async framework inspired by [Twitter's Finagle](http://twitter.github.io/finagle/) (which is in scala), and (loosely) building upon the existing (but anemic) Futures code found in the C++11 standard ([`std::future`](http://en.cppreference.com/w/cpp/thread/future)) and [`boost::future`](http://www.boost.org/doc/libs/1_53_0/boost/thread/future.hpp) (especially >= 1.53.0). Although inspired by the std::future interface, it is not syntactically drop-in compatible because some ideas didn't translate well enough and we decided to break from the API. But semantically, it should be straightforward to translate from existing std::future code to Futures.
-*noun*
-A framework for expressing asynchronous control flow in C++, that is composable and easily translated to/from synchronous code.
-
-*synonyms*
-[Finagle](http://twitter.github.io/finagle/)
-
-Wangle is a futures-based async framework inspired by [Twitter's Finagle](http://twitter.github.io/finagle/) (which is in scala), and (loosely) building upon the existing (but anemic) Futures code found in the C++11 standard ([`std::future`](http://en.cppreference.com/w/cpp/thread/future)) and [`boost::future`](http://www.boost.org/doc/libs/1_53_0/boost/thread/future.hpp) (especially >= 1.53.0). Although inspired by the std::future interface, it is not syntactically drop-in compatible because some ideas didn't translate well enough and we decided to break from the API. But semantically, it should be straightforward to translate from existing std::future code to Wangle.
-
-The primary semantic differences are that Wangle Futures and Promises are not threadsafe; and as does `boost::future`, Wangle supports continuing callbacks (`then()`) and there are helper methods `whenAll()` and `whenAny()` which are important compositional building blocks.
+The primary semantic differences are that folly's Futures and Promises are not threadsafe; and as does `boost::future`, folly::Futures support continuing callbacks (`then()`) and there are helper methods `whenAll()` and `whenAny()` which are important compositional building blocks.
## Brief Synopsis
Up to this point we have skirted around the matter of waiting for Futures. You may never need to wait for a Future, because your code is event-driven and all follow-up action happens in a then-block. But if want to have a batch workflow, where you initiate a batch of asynchronous operations and then wait for them all to finish at a synchronization point, then you will want to wait for a Future.
-Other future frameworks like Finagle and std::future/boost::future, give you the ability to wait directly on a Future, by calling `fut.wait()` (naturally enough). Wangle has diverged from this pattern because we don't want to be in the business of dictating how your thread waits. We may work out something that we feel is sufficiently general, in the meantime adapt this spin loop to however your thread should wait:
+Other future frameworks like Finagle and std::future/boost::future, give you the ability to wait directly on a Future, by calling `fut.wait()` (naturally enough). Futures have diverged from this pattern because we don't want to be in the business of dictating how your thread waits. We may work out something that we feel is sufficiently general, in the meantime adapt this spin loop to however your thread should wait:
while (!f.isReady()) {}
(Hint: you might want to use an event loop or a semaphore or something. You probably don't want to just spin like this.)
-Wangle is partially threadsafe. A Promise or Future can migrate between threads as long as there's a full memory barrier of some sort. `Future::then` and `Promise::setValue` (and all variants that boil down to those two calls) can be called from different threads. BUT, be warned that you might be surprised about which thread your callback executes on. Let's consider an example.
+Futures are partially threadsafe. A Promise or Future can migrate between threads as long as there's a full memory barrier of some sort. `Future::then` and `Promise::setValue` (and all variants that boil down to those two calls) can be called from different threads. BUT, be warned that you might be surprised about which thread your callback executes on. Let's consider an example.
```C++
// Thread A
The tradeoff is memory. Each continuation has a stack, and that stack is usually fixed-size and has to be big enough to support whatever ordinary computation you might want to do on it. So each living continuation requires a relatively large amount of memory. If you know the number of continuations will be small, this might be a good fit. In particular, it might be faster and the code might read cleaner.
-Wangle takes the middle road between callback hell and continuations, one which has been trodden and proved useful in other languages. It doesn't claim to be the best model for all situations. Use your tools wisely.
+Futures takes the middle road between callback hell and continuations, one which has been trodden and proved useful in other languages. It doesn't claim to be the best model for all situations. Use your tools wisely.
#include <stdexcept>
-#include <folly/futures/WangleException.h>
+#include <folly/futures/FutureException.h>
namespace folly {
#include <folly/Likely.h>
#include <folly/Memory.h>
#include <folly/futures/Deprecated.h>
-#include <folly/futures/WangleException.h>
+#include <folly/futures/FutureException.h>
namespace folly {
exception_wrapper& exception() {
if (UNLIKELY(!hasException())) {
- throw WangleException("exception(): Try does not contain an exception");
+ throw FutureException("exception(): Try does not contain an exception");
}
return *e_;
}
}
/*
- * @throws WangleException if the Try doesn't contain an exception
+ * @throws FutureException 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");
+ throw FutureException("exception(): Try does not contain an exception");
}
return *e_;
}
+++ /dev/null
-/*
- * Copyright 2014 Facebook, Inc.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- * http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-#pragma once
-
-#include <exception>
-#include <string>
-
-namespace folly {
-
-class WangleException : public std::exception {
-
-public:
-
- explicit WangleException(std::string message_arg)
- : message(message_arg) {}
-
- ~WangleException() throw(){}
-
- virtual const char *what() const throw() {
- return message.c_str();
- }
-
- bool operator==(const WangleException &other) const{
- return other.message == this->message;
- }
-
- bool operator!=(const WangleException &other) const{
- return !(*this == other);
- }
-
- protected:
- std::string message;
-};
-
-class BrokenPromise : public WangleException {
- public:
- explicit BrokenPromise() :
- WangleException("Broken promise") { }
-};
-
-class NoState : public WangleException {
- public:
- explicit NoState() : WangleException("No state") { }
-};
-
-class PromiseAlreadySatisfied : public WangleException {
- public:
- explicit PromiseAlreadySatisfied() :
- WangleException("Promise already satisfied") { }
-};
-
-class FutureNotReady : public WangleException {
- public:
- explicit FutureNotReady() :
- WangleException("Future not ready") { }
-};
-
-class FutureAlreadyRetrieved : public WangleException {
- public:
- explicit FutureAlreadyRetrieved () :
- WangleException("Future already retrieved") { }
-};
-
-class UsingUninitializedTry : public WangleException {
- public:
- explicit UsingUninitializedTry() :
- WangleException("Using unitialized try") { }
-};
-
-class FutureCancellation : public WangleException {
- public:
- FutureCancellation() : WangleException("Future was cancelled") {}
-};
-
-class TimedOut : public WangleException {
- public:
- TimedOut() : WangleException("Timed out") {}
-};
-
-}
}
};
-typedef WangleException eggs_t;
+typedef FutureException eggs_t;
static eggs_t eggs("eggs");
// Future
projects / folly.git / commitdiff