2 * Copyright 2015 Facebook, Inc.
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
19 #include <folly/futures/detail/Types.h>
23 template <class> class Future;
25 /// A Timekeeper handles the details of keeping time and fulfilling delay
26 /// promises. The returned Future<void> will either complete after the
27 /// elapsed time, or in the event of some kind of exceptional error may hold
28 /// an exception. These Futures respond to cancellation. If you use a lot of
29 /// Delays and many of them ultimately are unneeded (as would be the case for
30 /// Delays that are used to trigger timeouts of async operations), then you
31 /// can and should cancel them to reclaim resources.
33 /// Users will typically get one of these via Future::sleep(Duration) or
34 /// use them implicitly behind the scenes by passing a timeout to some Future
37 /// Although we don't formally alias Delay = Future<void>,
38 /// that's an appropriate term for it. People will probably also call these
39 /// Timeouts, and that's ok I guess, but that term is so overloaded I thought
40 /// it made sense to introduce a cleaner term.
42 /// Remember that Duration is a std::chrono duration (millisecond resolution
43 /// at the time of writing).
46 virtual ~Timekeeper() = default;
48 /// Returns a future that will complete after the given duration with the
49 /// elapsed time. Exceptional errors can happen but they must be
50 /// exceptional. Use the steady (monotonic) clock.
52 /// You may cancel this Future to reclaim resources.
54 /// This future probably completes on the timer thread. You should almost
55 /// certainly follow it with a via() call or the accuracy of other timers
57 virtual Future<void> after(Duration) = 0;
59 /// Returns a future that will complete at the requested time.
61 /// You may cancel this Future to reclaim resources.
63 /// NB This is sugar for `after(when - now)`, so while you are welcome to
64 /// use a std::chrono::system_clock::time_point it will not track changes to
65 /// the system clock but rather execute that many milliseconds in the future
66 /// according to the steady clock.
67 template <class Clock>
68 Future<void> at(std::chrono::time_point<Clock> when);
73 // now get those definitions
74 #include <folly/futures/Future.h>
76 // finally we can use Future
79 template <class Clock>
80 Future<void> Timekeeper::at(std::chrono::time_point<Clock> when) {
81 auto now = Clock::now();
87 return after(when - now);