1 // Copyright 2012-2013 The Rust Project Developers. See the COPYRIGHT
2 // file at the top-level directory of this distribution and at
3 // http://rust-lang.org/COPYRIGHT.
5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8 // option. This file may not be copied, modified, or distributed
9 // except according to those terms.
12 * A type representing values that may be computed concurrently and
13 * operations for working with them.
18 * # fn fib(n: uint) -> uint {42};
19 * # fn make_a_sandwich() {};
20 * let mut delayed_fib = extra::future::spawn (|| fib(5000) );
22 * printfln!("fib(5000) = %?", delayed_fib.get())
26 #[allow(missing_doc)];
31 use std::comm::{PortOne, oneshot};
33 use std::util::replace;
35 #[doc = "The future type"]
36 pub struct Future<A> {
37 priv state: FutureState<A>,
40 // n.b. It should be possible to get rid of this.
41 // Add a test, though -- tjc
42 // FIXME(#2829) -- futures should not be copyable, because they close
43 // over ~fn's that have pipes and so forth within!
45 impl<A> Drop for Future<A> {
55 /// Methods on the `future` type
56 impl<A:Clone> Future<A> {
57 pub fn get(&mut self) -> A {
58 //! Get the value of the future.
59 (*(self.get_ref())).clone()
64 /// Gets the value from this future, forcing evaluation.
65 pub fn unwrap(self) -> A {
68 let state = replace(&mut this.state, Evaluating);
71 _ => fail!( "Logic error." ),
77 pub fn get_ref<'a>(&'a mut self) -> &'a A {
79 * Executes the future's closure and then returns a borrowed
80 * pointer to the result. The borrowed pointer lasts as long as
86 Forced(ref mut v) => { return cast::transmute(v); }
87 Evaluating => fail!("Recursive forcing of future!"),
92 let state = replace(&mut self.state, Evaluating);
94 Forced(_) | Evaluating => fail!("Logic error."),
96 self.state = Forced(f());
97 cast::transmute(self.get_ref())
105 pub fn from_value<A>(val: A) -> Future<A> {
107 * Create a future from a value.
109 * The value is immediately available and calling `get` later will
113 Future {state: Forced(val)}
116 pub fn from_port<A:Send>(port: PortOne<A>) -> Future<A> {
118 * Create a future from a port
120 * The first time that the value is requested the task will block
121 * waiting for the result to be received on the port.
124 let port = Cell::new(port);
130 pub fn from_fn<A>(f: ~fn() -> A) -> Future<A> {
132 * Create a future from a function.
134 * The first time that the value is requested it will be retrieved by
135 * calling the function. Note that this function is a local
136 * function. It is not spawned into another task.
139 Future {state: Pending(f)}
142 pub fn spawn<A:Send>(blk: ~fn() -> A) -> Future<A> {
144 * Create a future from a unique closure.
146 * The closure will be run in a new task and its result used as the
147 * value of the future.
150 let (port, chan) = oneshot();
152 let chan = Cell::new(chan);
154 let chan = chan.take();
158 return from_port(port);
166 use std::comm::oneshot;
170 fn test_from_value() {
171 let mut f = from_value(~"snail");
172 assert_eq!(f.get(), ~"snail");
176 fn test_from_port() {
177 let (po, ch) = oneshot();
179 let mut f = from_port(po);
180 assert_eq!(f.get(), ~"whale");
185 let mut f = from_fn(|| ~"brail");
186 assert_eq!(f.get(), ~"brail");
190 fn test_interface_get() {
191 let mut f = from_value(~"fail");
192 assert_eq!(f.get(), ~"fail");
196 fn test_interface_unwrap() {
197 let f = from_value(~"fail");
198 assert_eq!(f.unwrap(), ~"fail");
202 fn test_get_ref_method() {
203 let mut f = from_value(22);
204 assert_eq!(*f.get_ref(), 22);
209 let mut f = spawn(|| ~"bale");
210 assert_eq!(f.get(), ~"bale");
215 fn test_futurefail() {
216 let mut f = spawn(|| fail!());
217 let _x: ~str = f.get();
221 fn test_sendable_future() {
222 let expected = "schlorf";
223 let f = Cell::new(do spawn { expected });
225 let mut f = f.take();
226 let actual = f.get();
227 assert_eq!(actual, expected);