Module task

Example

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

Enum SchedMode - Scheduler modes
Enum TaskResult - Indicates the manner in which a task exited.
Struct SchedOpts - Scheduler configuration options
Struct TaskBuilder - The task builder type.
Struct TaskOpts - Task configuration options
Implementation of ::std::cmp::Eq for TaskResult - Automatically derived.
Implementation of ::std::cmp::Eq for SchedMode - Automatically derived.
Implementation for TaskBuilder
Function default_task_opts - The default task options
Function deschedule - Yield control to the task scheduler
Function failing - True if the running task has failed
Function rekillable - Makes killable a task marked as unkillable
Function spawn - Creates and executes a new child task
Function spawn_indestructible - Creates a child task that cannot be killed by linked failure
Function spawn_sched - * Creates a new task on a new or existing scheduler
Function spawn_supervised - Creates a child task supervised by the current one
Function spawn_unlinked - Creates a child task unlinked from the current one
Function spawn_with - Runs a task, while transferring ownership of one argument to the child.
Function task - Generate the base configuration for spawning a task, off of which more configuration methods can be chained
Function try - Execute a function in another task and return either the return value of the function or result::err.
Function unkillable - Temporarily make the task unkillable
Function with_task_name - Read the name of the current task.

Enum `SchedMode`

Scheduler modes

Variants

DefaultScheduler - Run task on the default scheduler
SingleThreaded - All tasks run in the same OS thread

Enum `TaskResult`

Indicates the manner in which a task exited.

A task that completes without failing is considered to exit successfully. Supervised ancestors and linked siblings may yet fail after this task succeeds. Also note that in such a case, it may be nondeterministic whether linked failure or successful exit happen first.

If you wish for this result's delivery to block until all linked and/or children tasks complete, recommend using a result future.

Variants

Success
Failure

Struct `SchedOpts`

pub struct SchedOpts {
    mode: SchedMode,
}

Scheduler configuration options

Fields

sched_mode - The operating mode of the scheduler

Struct `TaskBuilder`

pub struct TaskBuilder {
    opts: TaskOpts,
    gen_body: Option<~fn(v: ~fn()) -> ~fn()>,
    can_not_copy: Option<util::NonCopyable>,
    consumed: bool,
}

The task builder type.

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

Struct `TaskOpts`

pub struct TaskOpts {
    linked: bool,
    supervised: bool,
    watched: bool,
    indestructible: bool,
    notify_chan: Option<Chan<TaskResult>>,
    name: Option<~str>,
    sched: SchedOpts,
    stack_size: Option<uint>,
}

Task configuration options

Fields

linked - Propagate failure bidirectionally between child and parent. True by default. If both this and 'supervised' are false, then either task's failure will not affect the other ("unlinked").
supervised - Propagate failure unidirectionally from parent to child, but not from child to parent. False by default.
watched - Make parent task collect exit status notifications from child before reporting its own exit status. (This delays the parent task's death and cleanup until after all transitively watched children also exit.) True by default.
indestructible - Configures the task to ignore kill signals received from linked failure. This may cause process hangs during failure if not used carefully, but causes task blocking code paths (e.g. port recv() calls) to be faster by 2 atomic operations. False by default.
notify_chan - Enable lifecycle notifications on the given channel
name - A name for the task-to-be, for identification in failure messages.
sched - Specify the configuration of a new scheduler to create the task in

By default, every task is created in the same scheduler as its parent, where it is scheduled cooperatively with all other tasks in that scheduler. Some specialized applications may want more control over their scheduling, in which case they can be spawned into a new scheduler with the specific properties required.

This is of particular importance for libraries which want to call into foreign code that blocks. Without doing so in a different scheduler other tasks will be impeded or even blocked indefinitely.

Implementation of `::std::cmp::Eq` for `TaskResult`

Automatically derived.

Method `eq`

fn eq(&self, __arg_0: &TaskResult) -> ::bool

Method `ne`

fn ne(&self, __arg_0: &TaskResult) -> ::bool

Implementation of `::std::cmp::Eq` for `SchedMode`

Automatically derived.

Method `eq`

fn eq(&self, __arg_0: &SchedMode) -> ::bool

Method `ne`

fn ne(&self, __arg_0: &SchedMode) -> ::bool

Implementation for `TaskBuilder`

Method `unlinked`

fn unlinked(&mut self)

Decouple the child task's failure from the parent's. If either fails, the other will not be killed.

Method `supervised`

fn supervised(&mut self)

Unidirectionally link the child task's failure with the parent's. The child's failure will not kill the parent, but the parent's will kill the child.

Method `linked`

fn linked(&mut self)

Link the child task's and parent task's failures. If either fails, the other will be killed.

Method `watched`

fn watched(&mut self)

Cause the parent task to collect the child's exit status (and that of all transitively-watched grandchildren) before reporting its own.

Method `unwatched`

fn unwatched(&mut self)

Allow the child task to outlive the parent task, at the possible cost of the parent reporting success even if the child task fails later.

Method `indestructible`

fn indestructible(&mut self)

Cause the child task to ignore any kill signals received from linked failure. This optimizes context switching, at the possible expense of process hangs in the case of unexpected failure.

Method `future_result`

fn future_result(&mut self, blk: &fn(v: Port<TaskResult>))

Get a future representing the exit status of the task.

Taking the value of the future will block until the child task terminates. The future-receiving callback specified will be called before the task is spawned; as such, do not invoke .get() within the closure; rather, store it in an outer variable/list for later use.

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.

Failure

Fails if a future_result was already set for this task.

Method `name`

fn name(&mut self, name: ~str)

Name the task-to-be. Currently the name is used for identification only in failure messages.

Method `sched_mode`

fn sched_mode(&mut self, mode: SchedMode)

Configure a custom scheduler mode for the task.

Method `add_wrapper`

fn add_wrapper(&mut self, wrapper: ~fn(v: ~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.

Method `spawn`

fn spawn(&mut self, 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. The task has the properties and behavior specified by the task_builder.

Failure

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

Method `spawn_with`

fn spawn_with<A: Send>(&mut self, arg: A, f: ~fn(v: A))

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

Method `try`

fn try<T: Send>(&mut self, 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.

Failure

Fails if a future_result was already set for this task.

Function `default_task_opts`

fn default_task_opts() -> TaskOpts

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 `deschedule`

fn deschedule()

Yield control to the task scheduler

Function `failing`

fn failing() -> bool

True if the running task has failed

Function `rekillable`

fn rekillable<U>(f: &fn() -> U) -> U

Makes killable a task marked as unkillable. This is meant to be used only nested in unkillable.

Example

_~ do task::unkillable { do task::rekillable { // Task is killable } // Task is unkillable again }

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 task().spawn(f).

Function `spawn_indestructible`

fn spawn_indestructible(f: ~fn())

Creates a child task that cannot be killed by linked failure. This causes its context-switch path to be faster by 2 atomic swap operations. (Note that this convenience wrapper still uses linked-failure, so the child's children will still be killable by the parent. For the fastest possible spawn mode, use task::task().unlinked().indestructible().spawn.)

Function `spawn_sched`

fn spawn_sched(mode: SchedMode, f: ~fn())

Creates a new task on a new or existing 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_supervised`

fn spawn_supervised(f: ~fn())

Creates a child task supervised by the current one. If the child task fails, the parent will not be killed, but if the parent fails, the child will be killed.

Function `spawn_unlinked`

fn spawn_unlinked(f: ~fn())

Creates a child task unlinked from the current one. If either this task or the child task fails, the other will not be killed.

Function `spawn_with`

fn spawn_with<A: Send>(arg: A, f: ~fn(v: A))

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

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

This function is equivalent to task().spawn_with(arg, f).

Function `task`

fn task() -> TaskBuilder

Generate the base configuration for spawning a task, off of which more configuration methods can be chained. For example, task().unlinked().spawn is equivalent to spawn_unlinked.

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.

This is equivalent to task().supervised().try.

Function `unkillable`

fn unkillable<U>(f: &fn() -> U) -> U

Temporarily make the task unkillable

Example

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

Function `with_task_name`

fn with_task_name<U>(blk: &fn(Option<&str>) -> U) -> U

Read the name of the current task.

Module task

Example

Enum SchedMode

Variants

Enum TaskResult

Variants

Struct SchedOpts

Fields

Struct TaskBuilder

Struct TaskOpts

Fields

Implementation of ::std::cmp::Eq for TaskResult

Method eq

Method ne

Implementation of ::std::cmp::Eq for SchedMode

Method eq

Method ne

Implementation for TaskBuilder

Method unlinked

Method supervised

Method linked

Method watched

Method unwatched

Method indestructible

Method future_result

Failure

Method name

Method sched_mode

Method add_wrapper

Method spawn

Failure

Method spawn_with

Method try

Return value

Failure

Function default_task_opts

Function deschedule

Function failing

Function rekillable

Example

Function spawn

Function spawn_indestructible

Function spawn_sched

Failure

Function spawn_supervised

Function spawn_unlinked

Function spawn_with

Function task

Function try

Function unkillable

Example

Function with_task_name

Enum `SchedMode`

Enum `TaskResult`

Struct `SchedOpts`

Struct `TaskBuilder`

Struct `TaskOpts`

Implementation of `::std::cmp::Eq` for `TaskResult`

Method `eq`

Method `ne`

Implementation of `::std::cmp::Eq` for `SchedMode`

Method `eq`

Method `ne`

Implementation for `TaskBuilder`

Method `unlinked`

Method `supervised`

Method `linked`

Method `watched`

Method `unwatched`

Method `indestructible`

Method `future_result`

Method `name`

Method `sched_mode`

Method `add_wrapper`

Method `spawn`

Method `spawn_with`

Method `try`

Function `default_task_opts`

Function `deschedule`

Function `failing`

Function `rekillable`

Function `spawn`

Function `spawn_indestructible`

Function `spawn_sched`

Function `spawn_supervised`

Function `spawn_unlinked`

Function `spawn_with`

Function `task`

Function `try`

Function `unkillable`

Function `with_task_name`