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.
13 //! An executing Rust program consists of a collection of tasks, each
14 //! with their own stack and local state. A Rust task is typically
15 //! backed by an operating system thread, making tasks 'just threads',
16 //! but may also be implemented via other strategies as well
17 //! (e.g. Rust comes with the [`green`](../../green/index.html)
18 //! scheduling crate for creating tasks backed by green threads).
20 //! Tasks generally have their memory *isolated* from each other by
21 //! virtue of Rust's owned types (which of course may only be owned by
22 //! a single task at a time). Communication between tasks is primarily
23 //! done through [channels](../../std/comm/index.html), Rust's
24 //! message-passing types, though [other forms of task
25 //! synchronization](../../std/sync/index.html) are often employed to
26 //! achieve particular performance goals. In particular, types that
27 //! are guaranteed to be threadsafe are easily shared between threads
28 //! using the atomically-reference-counted container,
29 //! [`Arc`](../../std/sync/struct.Arc.html).
31 //! Fatal logic errors in Rust cause *task failure*, during which
32 //! a task will unwind the stack, running destructors and freeing
33 //! owned resources. Task failure is unrecoverable from within
34 //! the failing task (i.e. there is no 'try/catch' in Rust), but
35 //! failure may optionally be detected from a different task. If
36 //! the main task fails the application will exit with a non-zero
39 //! # Basic task scheduling
41 //! By default, every task is created with the same "flavor" as the calling task.
42 //! This flavor refers to the scheduling mode, with two possibilities currently
43 //! being 1:1 and M:N modes. Green (M:N) tasks are cooperatively scheduled and
44 //! native (1:1) tasks are scheduled by the OS kernel.
50 //! println!("Hello, World!");
54 //! # Advanced task scheduling
56 //! Task spawning can also be configured to use a particular scheduler, to
57 //! redirect the new task's output, or to yield a `future` representing the
58 //! task's final result. The configuration is established using the
59 //! `TaskBuilder` API:
64 //! extern crate green;
65 //! extern crate native;
67 //! use std::task::TaskBuilder;
68 //! use green::{SchedPool, PoolConfig, GreenTaskBuilder};
69 //! use native::NativeTaskBuilder;
72 //! // Create a green scheduler pool with the default configuration
73 //! let mut pool = SchedPool::new(PoolConfig::new());
75 //! // Spawn a task in the green pool
76 //! let mut fut_green = TaskBuilder::new().green(&mut pool).try_future(proc() {
80 //! // Spawn a native task
81 //! let mut fut_native = TaskBuilder::new().native().try_future(proc() {
85 //! // Wait for both tasks to finish, recording their outcome
86 //! let res_green = fut_green.unwrap();
87 //! let res_native = fut_native.unwrap();
89 //! // Shut down the green scheduler pool
98 use io::{Writer, stdio};
99 use kinds::{Send, marker};
100 use option::{None, Some, Option};
103 use rt::local::Local;
106 use str::{Str, SendStr, IntoMaybeOwned};
109 use to_string::ToString;
111 /// A means of spawning a task
113 /// Spawn a task, given low-level task options.
114 fn spawn(self, opts: task::TaskOpts, f: proc():Send);
117 /// The default task spawner, which spawns siblings to the current task.
118 pub struct SiblingSpawner;
120 impl Spawner for SiblingSpawner {
121 fn spawn(self, opts: task::TaskOpts, f: proc():Send) {
122 // bind tb to provide type annotation
123 let tb: Option<Box<Task>> = Local::try_take();
125 Some(t) => t.spawn_sibling(opts, f),
126 None => fail!("need a local task to spawn a sibling task"),
131 /// The task builder type.
133 /// Provides detailed control over the properties and behavior of new tasks.
135 // NB: Builders are designed to be single-use because they do stateful
136 // things that get weird when reusing - e.g. if you create a result future
137 // it only applies to a single task, so then you have to maintain Some
138 // potentially tricky state to ensure that everything behaves correctly
139 // when you try to reuse the builder to spawn a new task. We'll just
140 // sidestep that whole issue by making builders uncopyable and making
141 // the run function move them in.
142 pub struct TaskBuilder<S = SiblingSpawner> {
143 // A name for the task-to-be, for identification in failure messages
144 name: Option<SendStr>,
145 // The size of the stack for the spawned task
146 stack_size: Option<uint>,
148 stdout: Option<Box<Writer + Send>>,
150 stderr: Option<Box<Writer + Send>>,
151 // The mechanics of actually spawning the task (i.e.: green or native)
153 // Optionally wrap the eventual task body
154 gen_body: Option<proc(v: proc():Send):Send -> proc():Send>,
155 nocopy: marker::NoCopy,
158 impl TaskBuilder<SiblingSpawner> {
159 /// Generate the base configuration for spawning a task, off of which more
160 /// configuration methods can be chained.
161 pub fn new() -> TaskBuilder<SiblingSpawner> {
167 spawner: SiblingSpawner,
169 nocopy: marker::NoCopy,
174 impl<S: Spawner> TaskBuilder<S> {
175 /// Name the task-to-be. Currently the name is used for identification
176 /// only in failure messages.
177 #[unstable = "IntoMaybeOwned will probably change."]
178 pub fn named<T: IntoMaybeOwned<'static>>(mut self, name: T) -> TaskBuilder<S> {
179 self.name = Some(name.into_maybe_owned());
183 /// Set the size of the stack for the new task.
184 pub fn stack_size(mut self, size: uint) -> TaskBuilder<S> {
185 self.stack_size = Some(size);
189 /// Redirect task-local stdout.
190 #[experimental = "May not want to make stdio overridable here."]
191 pub fn stdout(mut self, stdout: Box<Writer + Send>) -> TaskBuilder<S> {
192 self.stdout = Some(stdout);
196 /// Redirect task-local stderr.
197 #[experimental = "May not want to make stdio overridable here."]
198 pub fn stderr(mut self, stderr: Box<Writer + Send>) -> TaskBuilder<S> {
199 self.stderr = Some(stderr);
203 /// Set the spawning mechanism for the task.
205 /// The `TaskBuilder` API configures a task to be spawned, but defers to the
206 /// "spawner" to actually create and spawn the task. The `spawner` method
207 /// should not be called directly by `TaskBuiler` clients. It is intended
208 /// for use by downstream crates (like `native` and `green`) that implement
209 /// tasks. These downstream crates then add extension methods to the
210 /// builder, like `.native()` and `.green(pool)`, that actually set the
212 pub fn spawner<T: Spawner>(self, spawner: T) -> TaskBuilder<T> {
213 // repackage the entire TaskBuilder since its type is changing.
215 name, stack_size, stdout, stderr, spawner: _, gen_body, nocopy
219 stack_size: stack_size,
228 // Where spawning actually happens (whether yielding a future or not)
229 fn spawn_internal(self, f: proc():Send,
230 on_exit: Option<proc(Result<(), Box<Any + Send>>):Send>) {
232 name, stack_size, stdout, stderr, spawner, mut gen_body, nocopy: _
234 let f = match gen_body.take() {
238 let opts = task::TaskOpts {
241 stack_size: stack_size,
243 if stdout.is_some() || stderr.is_some() {
244 spawner.spawn(opts, proc() {
245 let _ = stdout.map(stdio::set_stdout);
246 let _ = stderr.map(stdio::set_stderr);
250 spawner.spawn(opts, f)
254 /// Creates and executes a new child task.
256 /// Sets up a new task with its own call stack and schedules it to run
257 /// the provided proc. The task has the properties and behavior
258 /// specified by the `TaskBuilder`.
259 pub fn spawn(self, f: proc():Send) {
260 self.spawn_internal(f, None)
263 /// Execute a proc in a newly-spawned task and return a future representing
264 /// the task's result. The task has the properties and behavior
265 /// specified by the `TaskBuilder`.
267 /// Taking the value of the future will block until the child task
272 /// If the child task executes successfully (without failing) then the
273 /// future returns `result::Ok` containing the value returned by the
274 /// function. If the child task fails then the future returns `result::Err`
275 /// containing the argument to `fail!(...)` as an `Any` trait object.
276 #[experimental = "Futures are experimental."]
277 pub fn try_future<T:Send>(self, f: proc():Send -> T)
278 -> Future<Result<T, Box<Any + Send>>> {
279 // currently, the on_exit proc provided by librustrt only works for unit
280 // results, so we use an additional side-channel to communicate the
283 let (tx_done, rx_done) = channel(); // signal that task has exited
284 let (tx_retv, rx_retv) = channel(); // return value from task
286 let on_exit = proc(res) { let _ = tx_done.send_opt(res); };
287 self.spawn_internal(proc() { let _ = tx_retv.send_opt(f()); },
290 Future::from_fn(proc() {
291 rx_done.recv().map(|_| rx_retv.recv())
295 /// Execute a function in a newly-spawnedtask and block until the task
296 /// completes or fails. Equivalent to `.try_future(f).unwrap()`.
297 #[unstable = "Error type may change."]
298 pub fn try<T:Send>(self, f: proc():Send -> T) -> Result<T, Box<Any + Send>> {
299 self.try_future(f).unwrap()
303 /* Convenience functions */
305 /// Creates and executes a new child task
307 /// Sets up a new task with its own call stack and schedules it to run
308 /// the provided unique closure.
310 /// This function is equivalent to `TaskBuilder::new().spawn(f)`.
311 pub fn spawn(f: proc(): Send) {
312 TaskBuilder::new().spawn(f)
315 /// Execute a function in a newly-spawned task and return either the return
316 /// value of the function or an error if the task failed.
318 /// This is equivalent to `TaskBuilder::new().try`.
319 #[unstable = "Error type may change."]
320 pub fn try<T: Send>(f: proc(): Send -> T) -> Result<T, Box<Any + Send>> {
321 TaskBuilder::new().try(f)
324 /// Execute a function in another task and return a future representing the
327 /// This is equivalent to `TaskBuilder::new().try_future`.
328 #[experimental = "Futures are experimental."]
329 pub fn try_future<T:Send>(f: proc():Send -> T) -> Future<Result<T, Box<Any + Send>>> {
330 TaskBuilder::new().try_future(f)
334 /* Lifecycle functions */
336 /// Read the name of the current task.
338 pub fn name() -> Option<String> {
341 let task = Local::borrow(None::<Task>);
343 Some(ref name) => Some(name.as_slice().to_string()),
348 /// Yield control to the task scheduler.
349 #[unstable = "Name will change."]
350 pub fn deschedule() {
351 use rt::local::Local;
353 // FIXME(#7544): Optimize this, since we know we won't block.
354 let task: Box<Task> = Local::take();
358 /// True if the running task is currently failing (e.g. will return `true` inside a
359 /// destructor that is run while unwinding the stack after a call to `fail!()`).
360 #[unstable = "May move to a different module."]
361 pub fn failing() -> bool {
363 Local::borrow(None::<Task>).unwinder.unwinding()
368 use any::{Any, AnyRefExt};
371 use result::{Ok, Err};
373 use std::io::{ChanReader, ChanWriter};
377 // !!! These tests are dangerous. If something is buggy, they will hang, !!!
378 // !!! instead of exiting cleanly. This might wedge the buildbots. !!!
381 fn test_unnamed_task() {
383 assert!(name().is_none());
384 }).map_err(|_| ()).unwrap();
388 fn test_owned_named_task() {
389 TaskBuilder::new().named("ada lovelace".to_string()).try(proc() {
390 assert!(name().unwrap() == "ada lovelace".to_string());
391 }).map_err(|_| ()).unwrap();
395 fn test_static_named_task() {
396 TaskBuilder::new().named("ada lovelace").try(proc() {
397 assert!(name().unwrap() == "ada lovelace".to_string());
398 }).map_err(|_| ()).unwrap();
402 fn test_send_named_task() {
403 TaskBuilder::new().named("ada lovelace".into_maybe_owned()).try(proc() {
404 assert!(name().unwrap() == "ada lovelace".to_string());
405 }).map_err(|_| ()).unwrap();
409 fn test_run_basic() {
410 let (tx, rx) = channel();
411 TaskBuilder::new().spawn(proc() {
418 fn test_try_future() {
419 let result = TaskBuilder::new().try_future(proc() {});
420 assert!(result.unwrap().is_ok());
422 let result = TaskBuilder::new().try_future(proc() -> () {
425 assert!(result.unwrap().is_err());
429 fn test_try_success() {
431 "Success!".to_string()
432 }).as_ref().map(|s| s.as_slice()) {
433 result::Ok("Success!") => (),
443 result::Err(_) => (),
444 result::Ok(()) => fail!()
449 fn test_spawn_sched() {
452 let (tx, rx) = channel();
454 fn f(i: int, tx: Sender<()>) {
470 fn test_spawn_sched_childs_on_default_sched() {
471 let (tx, rx) = channel();
482 fn avoid_copying_the_body(spawnfn: |v: proc():Send|) {
483 let (tx, rx) = channel::<uint>();
486 let x_in_parent = (&*x) as *const int as uint;
489 let x_in_child = (&*x) as *const int as uint;
493 let x_in_child = rx.recv();
494 assert_eq!(x_in_parent, x_in_child);
498 fn test_avoid_copying_the_body_spawn() {
499 avoid_copying_the_body(spawn);
503 fn test_avoid_copying_the_body_task_spawn() {
504 avoid_copying_the_body(|f| {
505 let builder = TaskBuilder::new();
506 builder.spawn(proc() {
513 fn test_avoid_copying_the_body_try() {
514 avoid_copying_the_body(|f| {
522 fn test_child_doesnt_ref_parent() {
523 // If the child refcounts the parent task, this will stack overflow when
524 // climbing the task tree to dereference each ancestor. (See #1789)
525 // (well, it would if the constant were 8000+ - I lowered it to be more
526 // valgrind-friendly. try this at home, instead..!)
527 static GENERATIONS: uint = 16;
528 fn child_no(x: uint) -> proc(): Send {
531 TaskBuilder::new().spawn(child_no(x+1));
535 TaskBuilder::new().spawn(child_no(0));
539 fn test_simple_newsched_spawn() {
544 fn test_try_fail_message_static_str() {
546 fail!("static string");
549 type T = &'static str;
550 assert!(e.is::<T>());
551 assert_eq!(*e.downcast::<T>().unwrap(), "static string");
558 fn test_try_fail_message_owned_str() {
560 fail!("owned string".to_string());
564 assert!(e.is::<T>());
565 assert_eq!(*e.downcast::<T>().unwrap(), "owned string".to_string());
572 fn test_try_fail_message_any() {
574 fail!(box 413u16 as Box<Any + Send>);
577 type T = Box<Any + Send>;
578 assert!(e.is::<T>());
579 let any = e.downcast::<T>().unwrap();
580 assert!(any.is::<u16>());
581 assert_eq!(*any.downcast::<u16>().unwrap(), 413u16);
588 fn test_try_fail_message_unit_struct() {
594 Err(ref e) if e.is::<Juju>() => {}
595 Err(_) | Ok(()) => fail!()
601 let (tx, rx) = channel();
602 let mut reader = ChanReader::new(rx);
603 let stdout = ChanWriter::new(tx);
605 let r = TaskBuilder::new().stdout(box stdout as Box<Writer + Send>)
607 print!("Hello, world!");
611 let output = reader.read_to_string().unwrap();
612 assert_eq!(output, "Hello, world!".to_string());
615 // NOTE: the corresponding test for stderr is in run-pass/task-stderr, due
616 // to the test harness apparently interfering with stderr configuration.
620 fn task_abort_no_kill_runtime() {
625 let tb = TaskBuilder::new();
626 let rx = tb.try_future(proc() {});
628 timer::sleep(Duration::milliseconds(1000));