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.
do spawn {
log(error, "Hello, World!");
}SchedMode - Scheduler modesScheduler - A handle to a schedulerTask - A handle to a taskTaskResult - Indicates the manner in which a task exited.SchedOpts - Scheduler configuration optionsTaskBuilder - The task builder type.TaskOpts - Task configuration optionsof ::std::cmp::Eq for Scheduler - Automatically derived.of ::std::cmp::Eq for Task - Automatically derived.of ::std::cmp::Eq for TaskResult - Automatically derived.of ::std::cmp::Eq for SchedMode - Automatically derived.for TaskBuilderatomically - A stronger version of unkillable that also inhibits scheduling operationsdefault_task_opts - The default task optionsfailing - True if the running task has failedget_schedulerget_task - Get a handle to the running taskrekillable - The inverse of unkillablespawn - Creates and executes a new child taskspawn_sched - * Creates a new task on a new or existing schedulerspawn_supervised - Creates a child task supervised by the current onespawn_unlinked - Creates a child task unlinked from the current onespawn_with - Runs a task, while transfering ownership of one argument to the child.task - Generate the base configuration for spawning a task, off of which more configuration methods can be chainedtry - Execute a function in another task and return either the return value of the function or result::err.unkillable - Temporarily make the task unkillableyield - Yield control to the task schedulerSchedModeScheduler modes
DefaultScheduler - Run task on the default scheduler
CurrentScheduler - Run task on the current scheduler
ExistingScheduler(Scheduler) - Run task on a specific scheduler
PlatformThread - Tasks are scheduled on the main OS thread
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.
SingleThreaded - All tasks run in the same OS thread
ThreadPerCore - Tasks are distributed among available CPUs
ThreadPerTask - Each task runs in its own OS thread
ManualThreads(uint) - Tasks are distributed among a fixed number of OS threads
SchedulerA handle to a scheduler
SchedulerHandle(sched_id)TaskA handle to a task
TaskHandle(task_id)TaskResultIndicates 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.
Success
Failure
SchedOptspub struct SchedOpts {
mode: SchedMode,
foreign_stack_size: Option<uint>,
}Scheduler configuration options
sched_mode - The operating mode of the scheduler
foreign_stack_size - The size of the foreign stack, in bytes
Rust code runs on Rust-specific stacks. When Rust code calls foreign code (via functions in foreign modules) it switches to a typical, large stack appropriate for running code written in languages like C. By default these foreign stacks have unspecified size, but with this option their size can be precisely specified.
TaskBuilderpub 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.
TaskOptspub struct TaskOpts {
linked: bool,
supervised: bool,
notify_chan: Option<Chan<TaskResult>>,
sched: SchedOpts,
}Task configuration options
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.
notify_chan - Enable lifecycle notifications on the given channel
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.
::std::cmp::Eq for SchedulerAutomatically derived.
eqfn eq(&self, __arg_0: &Scheduler) -> ::boolnefn ne(&self, __arg_0: &Scheduler) -> ::bool::std::cmp::Eq for TaskAutomatically derived.
eqfn eq(&self, __arg_0: &Task) -> ::boolnefn ne(&self, __arg_0: &Task) -> ::bool::std::cmp::Eq for TaskResultAutomatically derived.
eqfn eq(&self, __arg_0: &TaskResult) -> ::boolnefn ne(&self, __arg_0: &TaskResult) -> ::bool::std::cmp::Eq for SchedModeAutomatically derived.
eqfn eq(&self, __arg_0: &SchedMode) -> ::boolnefn ne(&self, __arg_0: &SchedMode) -> ::boolTaskBuilderunlinkedfn unlinked(&mut self)Decouple the child task's failure from the parent's. If either fails, the other will not be killed.
supervisedfn 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.
linkedfn linked(&mut self)Link the child task's and parent task's failures. If either fails, the other will be killed.
future_resultfn 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.
Fails if a future_result was already set for this task.
sched_modefn sched_mode(&mut self, mode: SchedMode)Configure a custom scheduler mode for the task.
add_wrapperfn 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.
spawnfn 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.
When spawning into a new scheduler, the number of threads requested must be greater than zero.
spawn_withfn spawn_with<A: Send>(&mut self, arg: A, f: ~fn(v: A))Runs a task, while transfering ownership of one argument to the child.
tryfn 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.
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.
Fails if a future_result was already set for this task.
atomicallyunsafe fn atomically<U>(f: &fn() -> U) -> UA stronger version of unkillable that also inhibits scheduling operations. For use with exclusive ARCs, which use pthread mutexes directly.
default_task_optsfn default_task_opts() -> TaskOptsThe default task options
By default all tasks are supervised by their parent, are spawned into the same scheduler, and do not post lifecycle notifications.
failingfn failing() -> boolTrue if the running task has failed
get_schedulerfn get_scheduler() -> Schedulerget_taskfn get_task() -> TaskGet a handle to the running task
rekillableunsafe fn rekillable<U>(f: &fn() -> U) -> UThe inverse of unkillable. Only ever to be used nested in unkillable().
spawnfn 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).
spawn_schedfn spawn_sched(mode: SchedMode, f: ~fn())Creates a new task on a new or existing scheduler
greater than zero.
spawn_supervisedfn 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.
spawn_unlinkedfn 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.
spawn_withfn spawn_with<A: Send>(arg: A, f: ~fn(v: 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 task().spawn_with(arg, f).
taskfn task() -> TaskBuilderGenerate 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.
tryfn 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.
unkillableunsafe fn unkillable<U>(f: &fn() -> U) -> UTemporarily make the task unkillable
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);
}yieldfn yield()Yield control to the task scheduler