Struct rustrt::task::Task [src]

pub struct Task {
    pub heap: LocalHeap,
    pub gc: GarbageCollector,
    pub storage: LocalStorage,
    pub unwinder: Unwinder,
    pub death: Death,
    pub destroyed: bool,
    pub name: Option<SendStr>,
    // some fields omitted
}

State associated with Rust tasks.

Rust tasks are primarily built with two separate components. One is this structure which handles standard services such as TLD, unwinding support, naming of a task, etc. The second component is the runtime of this task, a Runtime trait object.

The Runtime object instructs this task how it can perform critical operations such as blocking, rescheduling, I/O constructors, etc. The two halves are separately owned, but one is often found contained in the other. A task's runtime can be reflected upon with the maybe_take_runtime method, and otherwise its ownership is managed with take_runtime and put_runtime.

In general, this structure should not be used. This is meant to be an unstable internal detail of the runtime itself. From time-to-time, however, it is useful to manage tasks directly. An example of this would be interoperating with the Rust runtime from FFI callbacks or such. For this reason, there are two methods of note with the Task structure.

run - This function will execute a closure inside the context of a task. Failure is caught and handled via the task's on_exit callback. If this fails, the task is still returned, but it can no longer be used, it is poisoned.
destroy - This is a required function to call to destroy a task. If a task falls out of scope without calling destroy, its destructor bomb will go off, aborting the process.

With these two methods, tasks can be re-used to execute code inside of its context while having a point in the future where destruction is allowed. More information can be found on these specific methods.

Example

extern crate native;
use std::uint;

// Create a task using a native runtime
let task = native::task::new((0, uint::MAX));

// Run some code, catching any possible failures
let task = task.run(|| {
    // Run some code inside this task
    println!("Hello with a native runtime!");
});

// Run some code again, catching the failure
let task = task.run(|| {
    fail!("oh no, what to do!");
});

// Now that the task is failed, it can never be used again
assert!(task.is_destroyed());

// Deallocate the resources associated with this task
task.destroy();

Fields

`heap`
`gc`
`storage`
`unwinder`
`death`
`destroyed`
`name`

Methods

`impl Task`

`fn new() -> Task`

Creates a new uninitialized task.

This method cannot be used to immediately invoke run because the task itself will likely require a runtime to be inserted via put_runtime.

Note that you likely don't want to call this function, but rather the task creation functions through libnative or libgreen.

`fn run(~self, f: ||) -> Box<Task>`

Consumes ownership of a task, runs some code, and returns the task back.

This function can be used as an emulated "try/catch" to interoperate with the rust runtime at the outermost boundary. It is not possible to use this function in a nested fashion (a try/catch inside of another try/catch). Invoking this funciton is quite cheap.

If the closure f succeeds, then the returned task can be used again for another invocation of run. If the closure f fails then self will be internally destroyed along with all of the other associated resources of this task. The on_exit callback is invoked with the cause of failure (not returned here). This can be discovered by querying is_destroyed().

Note that it is possible to view partial execution of the closure f because it is not guaranteed to run to completion, but this function is guaranteed to return if it fails. Care should be taken to ensure that stack references made by f are handled appropriately.

It is invalid to call this function with a task that has been previously destroyed via a failed call to run.

Example

extern crate native;
use std::uint;

// Create a new native task
let task = native::task::new((0, uint::MAX));

// Run some code once and then destroy this task
task.run(|| {
    println!("Hello with a native runtime!");
}).destroy();

`fn destroy(~self) -> Box<Task>`

Destroy all associated resources of this task.

This function will perform any necessary clean up to prepare the task for destruction. It is required that this is called before a Task falls out of scope.

The returned task cannot be used for running any more code, but it may be used to extract the runtime as necessary.

`fn is_destroyed(&self) -> bool`

Queries whether this can be destroyed or not.

`fn put_runtime(&mut self, ops: Box<Runtime + Send>)`

Inserts a runtime object into this task, transferring ownership to the task. It is illegal to replace a previous runtime object in this task with this argument.

`fn take_runtime(&mut self) -> Box<Runtime + Send>`

Removes the runtime from this task, transferring ownership to the caller.

`fn maybe_take_runtime<T: 'static>(&mut self) -> Option<Box<T>>`

Attempts to extract the runtime as a specific type. If the runtime does not have the provided type, then the runtime is not removed. If the runtime does have the specified type, then it is removed and returned (transfer of ownership).

It is recommended to only use this method when absolutely necessary. This function may not be available in the future.

`fn spawn_sibling(~self, opts: TaskOpts, f: proc(): Send)`

Spawns a sibling to this task. The newly spawned task is configured with the opts structure and will run f as the body of its code.

`fn deschedule(~self, amt: uint, f: |BlockedTask| -> Result<(), BlockedTask>)`

Deschedules the current task, invoking f amt times. It is not recommended to use this function directly, but rather communication primitives in std::comm should be used.

`fn reawaken(~self)`

Wakes up a previously blocked task, optionally specifying whether the current task can accept a change in scheduling. This function can only be called on tasks that were previously blocked in deschedule.

`fn yield_now(~self)`

Yields control of this task to another task. This function will eventually return, but possibly not immediately. This is used as an opportunity to allow other tasks a chance to run.

`fn maybe_yield(~self)`

Similar to yield_now, except that this function may immediately return without yielding (depending on what the runtime decides to do).

`fn local_io<'a>(&'a mut self) -> Option<LocalIo<'a>>`

Acquires a handle to the I/O factory that this task contains, normally stored in the task's runtime. This factory may not always be available, which is why the return type is Option

`fn stack_bounds(&self) -> (uint, uint)`

Returns the stack bounds for this task in (lo, hi) format. The stack bounds may not be known for all tasks, so the return value may be None.

`fn can_block(&self) -> bool`

Returns whether it is legal for this task to block the OS thread that it is running on.

Structs

Struct rustrt::task::Task [src]

Example

Fields

Methods

`impl Task`

`fn new() -> Task`

`fn run(~self, f: ||) -> Box<Task>`

Example

`fn destroy(~self) -> Box<Task>`

`fn is_destroyed(&self) -> bool`

`fn put_runtime(&mut self, ops: Box<Runtime + Send>)`

`fn take_runtime(&mut self) -> Box<Runtime + Send>`

`fn maybe_take_runtime<T: 'static>(&mut self) -> Option<Box<T>>`

`fn spawn_sibling(~self, opts: TaskOpts, f: proc(): Send)`

`fn deschedule(~self, amt: uint, f: |BlockedTask| -> Result<(), BlockedTask>)`

`fn reawaken(~self)`

`fn yield_now(~self)`

`fn maybe_yield(~self)`

`fn local_io<'a>(&'a mut self) -> Option<LocalIo<'a>>`

`fn stack_bounds(&self) -> (uint, uint)`

`fn can_block(&self) -> bool`

Trait Implementations

`impl Local<Borrowed<Task>> for Task`

`fn put(value: Box<Task>)`

`fn take() -> Box<Task>`

`fn try_take() -> Option<Box<Task>>`

`fn exists(_: Option<Task>) -> bool`

`fn borrow(_: Option<Task>) -> Borrowed<Task>`

`unsafe fn unsafe_take() -> Box<Task>`

`unsafe fn unsafe_borrow() -> *mut Task`

`unsafe fn try_unsafe_borrow() -> Option<*mut Task>`

`impl Drop for Task`

`fn drop(&mut self)`

Keyboard shortcuts

Search tricks

Structs

Struct rustrt::task::Task[src]

Example

Fields

Methods

impl Task

fn new() -> Task

fn run(~self, f: ||) -> Box<Task>

Example

fn destroy(~self) -> Box<Task>

fn is_destroyed(&self) -> bool

fn put_runtime(&mut self, ops: Box<Runtime + Send>)

fn take_runtime(&mut self) -> Box<Runtime + Send>

fn maybe_take_runtime<T: 'static>(&mut self) -> Option<Box<T>>

fn spawn_sibling(~self, opts: TaskOpts, f: proc(): Send)

fn deschedule(~self, amt: uint, f: |BlockedTask| -> Result<(), BlockedTask>)

fn reawaken(~self)

fn yield_now(~self)

fn maybe_yield(~self)

fn local_io<'a>(&'a mut self) -> Option<LocalIo<'a>>

fn stack_bounds(&self) -> (uint, uint)

fn can_block(&self) -> bool

Trait Implementations

impl Local<Borrowed<Task>> for Task

fn put(value: Box<Task>)

fn take() -> Box<Task>

fn try_take() -> Option<Box<Task>>

fn exists(_: Option<Task>) -> bool

fn borrow(_: Option<Task>) -> Borrowed<Task>

unsafe fn unsafe_take() -> Box<Task>

unsafe fn unsafe_borrow() -> *mut Task

unsafe fn try_unsafe_borrow() -> Option<*mut Task>

impl Drop for Task

fn drop(&mut self)

Keyboard shortcuts

Search tricks

Struct rustrt::task::Task [src]

`impl Task`

`fn new() -> Task`

`fn run(~self, f: ||) -> Box<Task>`

`fn destroy(~self) -> Box<Task>`

`fn is_destroyed(&self) -> bool`

`fn put_runtime(&mut self, ops: Box<Runtime + Send>)`

`fn take_runtime(&mut self) -> Box<Runtime + Send>`

`fn maybe_take_runtime<T: 'static>(&mut self) -> Option<Box<T>>`

`fn spawn_sibling(~self, opts: TaskOpts, f: proc(): Send)`

`fn deschedule(~self, amt: uint, f: |BlockedTask| -> Result<(), BlockedTask>)`

`fn reawaken(~self)`

`fn yield_now(~self)`

`fn maybe_yield(~self)`

`fn local_io<'a>(&'a mut self) -> Option<LocalIo<'a>>`

`fn stack_bounds(&self) -> (uint, uint)`

`fn can_block(&self) -> bool`

`impl Local<Borrowed<Task>> for Task`

`fn put(value: Box<Task>)`

`fn take() -> Box<Task>`

`fn try_take() -> Option<Box<Task>>`

`fn exists(_: Option<Task>) -> bool`

`fn borrow(_: Option<Task>) -> Borrowed<Task>`

`unsafe fn unsafe_take() -> Box<Task>`

`unsafe fn unsafe_borrow() -> *mut Task`

`unsafe fn try_unsafe_borrow() -> Option<*mut Task>`

`impl Drop for Task`

`fn drop(&mut self)`