Task management.

An executing Rust program consists of a tree of tasks, each with their own stack, and sole ownership of their allocated heap data. Tasks communicate with each other using ports and channels.

When a task fails, that failure will propagate to its parent (the task that spawned it) and the parent will fail as well. The reverse is not true: when a parent task fails its children will continue executing. When the root (main) task fails, all tasks fail, and then so does the entire process.

Tasks may execute in parallel and are scheduled automatically by the runtime.

Example

do spawn {
    log(error, "Hello, World!");
}

Type local_data_key

type local_data_key<T> = fn@(+@T)

Type sched_opts

type sched_opts = {mode: sched_mode, foreign_stack_size: option<uint>,}

Scheduler configuration options

Fields

Type task_opts

type task_opts = {supervise: bool,
 notify_chan: option<comm::chan<notification>>,
 sched: option<sched_opts>,}

Task configuration options

Fields

Enum builder

The task builder type.

Provides detailed control over the properties and behavior of new tasks.

Variants

Enum notification

A message type for notifying of task lifecycle events

Variants

Enum sched_mode

Scheduler modes

Variants

The main OS thread is the thread used to launch the runtime which, in most cases, is the process's initial thread as created by the OS.

Enum task

A handle to a task

Variants

Enum task_result

Indicates the manner in which a task exited.

A task that completes without failing and whose supervised children complete without failing is considered to exit successfully.

FIXME (See #1868): This description does not indicate the current behavior for linked failure.

Variants

Implementation extensions of iter::base_iter<A> for IMPL_T<A>

Method each

fn each(blk: fn(A) -> bool)

Method size_hint

fn size_hint() -> option<uint>

Method eachi

fn eachi(blk: fn(uint, A) -> bool)

Method all

fn all(blk: fn(A) -> bool) -> bool

Method any

fn any(blk: fn(A) -> bool) -> bool

Method foldl

fn foldl<B>(+b0: B, blk: fn(B, A) -> B) -> B

Method contains

fn contains(x: A) -> bool

Method count

fn count(x: A) -> uint

Method position

fn position(f: fn(A) -> bool) -> option<uint>

Implementation extensions for IMPL_T<A>

Method filter_to_vec

fn filter_to_vec(pred: fn(A) -> bool) -> ~[A]

Method map_to_vec

fn map_to_vec<B>(op: fn(A) -> B) -> ~[B]

Method to_vec

fn to_vec() -> ~[A]

Method min

fn min() -> A

Method max

fn max() -> A

Method find

fn find(p: fn(A) -> bool) -> option<A>

Implementation extensions for *T

Extension methods for pointers

Method is_null

pure fn is_null() -> bool

Returns true if the pointer is equal to the null pointer.

Method is_not_null

pure fn is_not_null() -> bool

Returns true if the pointer is not equal to the null pointer.

Implementation extensions for dvec<A>

Method swap

fn swap(f: fn(-~[mut A]) -> ~[mut A])

Swaps out the current vector and hands it off to a user-provided function f. The function should transform it however is desired and return a new vector to replace it with.

Method len

fn len() -> uint

Returns the number of elements currently in the dvec

Method set

fn set(+w: ~[mut A])

Overwrite the current contents

Method pop

fn pop() -> A

Remove and return the last element

Method unshift

fn unshift(-t: A)

Insert a single item at the front of the list

Method push

fn push(+t: A)

Append a single item to the end of the list

Method shift

fn shift() -> A

Remove and return the first element

Implementation extensions for dvec<A>

Method push_all

fn push_all(ts: & [const A])

Append all elements of a vector to the end of the list

Equivalent to append_iter() but potentially more efficient.

Method push_slice

fn push_slice(ts: & [const A], from_idx: uint, to_idx: uint)

Appends elements from from_idx to to_idx (exclusive)

Method get

fn get() -> ~[A]

Gets a copy of the current contents.

See unwrap() if you do not wish to copy the contents.

Method []

fn [](idx: uint) -> A

Copy out an individual element

Method get_elt

fn get_elt(idx: uint) -> A

Copy out an individual element

Method set_elt

fn set_elt(idx: uint, a: A)

Overwrites the contents of the element at idx with a

Method grow_set_elt

fn grow_set_elt(idx: uint, initval: A, val: A)

Overwrites the contents of the element at idx with a, growing the vector if necessary. New elements will be initialized with initval

Method last

fn last() -> A

Returns the last element, failing if the vector is empty

Method reach

fn reach(f: fn(A) -> bool)

Iterates over the elements in reverse order

Implementation extensions of iter::base_iter<A> for IMPL_T<A>

Method each

fn each(blk: fn(A) -> bool)

Method size_hint

fn size_hint() -> option<uint>

Method eachi

fn eachi(blk: fn(uint, A) -> bool)

Method all

fn all(blk: fn(A) -> bool) -> bool

Method any

fn any(blk: fn(A) -> bool) -> bool

Method foldl

fn foldl<B>(+b0: B, blk: fn(B, A) -> B) -> B

Method contains

fn contains(x: A) -> bool

Method count

fn count(x: A) -> uint

Method position

fn position(f: fn(A) -> bool) -> option<uint>

Implementation extensions for IMPL_T<A>

Method filter_to_vec

fn filter_to_vec(pred: fn(A) -> bool) -> ~[A]

Method map_to_vec

fn map_to_vec<B>(op: fn(A) -> B) -> ~[B]

Method to_vec

fn to_vec() -> ~[A]

Method min

fn min() -> A

Method max

fn max() -> A

Method find

fn find(p: fn(A) -> bool) -> option<A>

Function add_wrapper

fn add_wrapper(builder: builder, gen_body: fn@(+fn~()) -> fn~())

Add a wrapper to the body of the spawned task.

Before the task is spawned it is passed through a 'body generator' function that may perform local setup operations as well as wrap the task body in remote setup operations. With this the behavior of tasks can be extended in simple ways.

This function augments the current body generator with a new body generator by applying the task body which results from the existing body generator to the new body generator.

Function builder

fn builder() -> builder

Construct a builder

Function default_task_opts

fn default_task_opts() -> task_opts

The default task options

By default all tasks are supervised by their parent, are spawned into the same scheduler, and do not post lifecycle notifications.

Function failing

fn failing() -> bool

True if the running task has failed

Function future_result

fn future_result(builder: builder) -> future::future<task_result>

Get a future representing the exit status of the task.

Taking the value of the future will block until the child task terminates.

Note that the future returning by this function is only useful for obtaining the value of the next task to be spawning with the builder. If additional tasks are spawned with the same builder then a new result future must be obtained prior to spawning each task.

Function future_task

fn future_task(builder: builder) -> future::future<task>

Get a future representing the handle to the new task

Function get_opts

fn get_opts(builder: builder) -> task_opts

Get the task_opts associated with a builder

Function get_task

fn get_task() -> task

Get a handle to the running task

Function local_data_get

unsafe fn local_data_get<T>(key: local_data_key<T>) -> option<@T>

Retrieve a task-local data value. It will also be kept alive in the table until explicitly removed.

Function local_data_modify

unsafe fn local_data_modify<T>(key: local_data_key<T>,
                               modify_fn: fn(option<@T>) -> option<@T>)

Modify a task-local data value. If the function returns 'none', the data is removed (and its reference dropped).

Function local_data_pop

unsafe fn local_data_pop<T>(key: local_data_key<T>) -> option<@T>

Remove a task-local data value from the table, returning the reference that was originally created to insert it.

Function local_data_set

unsafe fn local_data_set<T>(key: local_data_key<T>, -data: @T)

Store a value in task-local data. If this key already has a value, that value is overwritten (and its destructor is run).

Function run

fn run(-builder: builder, +f: fn~())

Creates and exucutes a new child task

Sets up a new task with its own call stack and schedules it to run the provided unique closure. The task has the properties and behavior specified by builder.

Failure

When spawning into a new scheduler, the number of threads requested must be greater than zero.

Function run_listener

fn run_listener<A: send>(-builder: builder, +f: fn~(comm::port<A>)) ->
   comm::chan<A>

Runs a new task while providing a channel from the parent to the child

Sets up a communication channel from the current task to the new child task, passes the port to child's body, and returns a channel linked to the port to the parent.

This encapsulates some boilerplate handshaking logic that would otherwise be required to establish communication from the parent to the child.

Function set_opts

fn set_opts(builder: builder, opts: task_opts)

Set the task_opts associated with a builder

To update a single option use a pattern like the following:

set_opts(builder, {
    supervise: false
    with get_opts(builder)
});

Function set_sched_mode

fn set_sched_mode(builder: builder, mode: sched_mode)

Function spawn

fn spawn(+f: fn~())

Creates and executes a new child task

Sets up a new task with its own call stack and schedules it to run the provided unique closure.

This function is equivalent to run(new_builder(), f).

Function spawn_listener

fn spawn_listener<A: send>(+f: fn~(comm::port<A>)) -> comm::chan<A>

Runs a new task while providing a channel from the parent to the child

Sets up a communication channel from the current task to the new child task, passes the port to child's body, and returns a channel linked to the port to the parent.

This encapsulates some boilerplate handshaking logic that would otherwise be required to establish communication from the parent to the child.

The simplest way to establish bidirectional communication between a parent in child is as follows:

let po = comm::port();
let ch = comm::chan(po);
let ch = do spawn_listener |po| {
    // Now the child has a port called 'po' to read from and
    // an environment-captured channel called 'ch'.
};
// Likewise, the parent has both a 'po' and 'ch'

This function is equivalent to run_listener(builder(), f).

Function spawn_sched

fn spawn_sched(mode: sched_mode, +f: fn~())

Creates a new scheduler and executes a task on it

Tasks subsequently spawned by that task will also execute on the new scheduler. When there are no more tasks to execute the scheduler terminates.

Failure

In manual threads mode the number of threads requested must be greater than zero.

Function spawn_with

fn spawn_with<A: send>(+arg: A, +f: fn~(+A))

Runs a task, while transfering ownership of one argument to the child.

This is useful for transfering ownership of noncopyables to another task.

This function is equivalent to run_with(builder(), arg, f).

Function try

fn try<T: send>(+f: fn~() -> T) -> result<T, ()>

Execute a function in another task and return either the return value of the function or result::err.

Return value

If the function executed successfully then try returns result::ok containing the value returned by the function. If the function fails then try returns result::err containing nil.

Function unkillable

unsafe fn unkillable(f: fn())

Temporarily make the task unkillable

Example

do task::unkillable {
    // detach / yield / destroy must all be called together
    rustrt::rust_port_detach(po);
    // This must not result in the current task being killed
    task::yield();
    rustrt::rust_port_destroy(po);
}

Function unsupervise

fn unsupervise(builder: builder)

Configures the new task to not propagate failure to its parent

Function yield

fn yield()

Yield control to the task scheduler