Struct zircon_object::task::Thread

pub struct Thread { /* private fields */ }

Runnable / computation entity

SYNOPSIS

TODO

DESCRIPTION

The thread object is the construct that represents a time-shared CPU execution context. Thread objects live associated to a particular Process Object which provides the memory and the handles to other objects necessary for I/O and computation.

Lifetime

Threads are created by calling Thread::create(), but only start executing when either Thread::start() or Process::start() are called. Both syscalls take as an argument the entrypoint of the initial routine to execute.

The thread passed to Process::start() should be the first thread to start execution on a process.

A thread terminates execution:

• by calling CurrentThread::exit()
• when the parent process terminates
• by calling Task::kill()
• after generating an exception for which there is no handler or the handler decides to terminate the thread.

Returning from the entrypoint routine does not terminate execution. The last action of the entrypoint should be to call CurrentThread::exit().

Closing the last handle to a thread does not terminate execution. In order to forcefully kill a thread for which there is no available handle, use KernelObject::get_child() to obtain a handle to the thread. This method is strongly discouraged. Killing a thread that is executing might leave the process in a corrupt state.

Fuchsia native threads are always detached. That is, there is no join() operation needed to do a clean termination. However, some runtimes above the kernel, such as C11 or POSIX might require threads to be joined.

Signals

Threads provide the following signals:

• THREAD_TERMINATED
• THREAD_SUSPENDED
• THREAD_RUNNING

When a thread is started THREAD_RUNNING is asserted. When it is suspended THREAD_RUNNING is deasserted, and THREAD_SUSPENDED is asserted. When the thread is resumed THREAD_SUSPENDED is deasserted and THREAD_RUNNING is asserted. When a thread terminates both THREAD_RUNNING and THREAD_SUSPENDED are deasserted and THREAD_TERMINATED is asserted.

Note that signals are OR’d into the state maintained by the KernelObject::wait_signal() family of functions thus you may see any combination of requested signals when they return.

Implementations

impl Thread

pub fn create(proc: &Arc<Process>, name: &str) -> ZxResult<Arc<Self>>

Create a new thread.

pub fn create_with_ext(
    proc: &Arc<Process>,
    name: &str,
    ext: impl Any + Send + Sync
) -> ZxResult<Arc<Self>>

Create a new thread with extension info.

Example

let job = Job::root();
let proc = Process::create(&job, "proc").unwrap();
// create a thread with extension info
let thread = Thread::create_with_ext(&proc, "thread", job.clone()).unwrap();
// get the extension info
let ext = thread.ext().downcast_ref::<Arc<Job>>().unwrap();
assert!(Arc::ptr_eq(ext, &job));

pub fn proc(&self) -> &Arc<Process>

Get the process.

pub fn ext(&self) -> &Box<dyn Any + Send + Sync>

Get the extension info.

pub fn context_cloned(&self) -> ZxResult<UserContext>

Returns a copy of saved context of current thread, or Err(ZxError::BAD_STATE) if the thread is running.

pub fn with_context<T, F>(&self, f: F) -> ZxResult<T> where
    F: FnOnce(&mut UserContext) -> T, 

Access saved context of current thread, or Err(ZxError::BAD_STATE) if the thread is running.

pub fn backup_context(&self, context: UserContext, siginfo: usize, uctx: usize)

Backup current user context before calling signal handler

pub fn fetch_backup_context(&self) -> Option<(UserContext, usize, usize)>

Fetch the context backup

pub fn start(self: &Arc<Self>, thread_fn: ThreadFn) -> ZxResult

Start execution on the thread.

pub fn start_with_entry(
    self: &Arc<Self>,
    entry: usize,
    stack: usize,
    arg1: usize,
    arg2: usize,
    thread_fn: ThreadFn
) -> ZxResult

Setup the instruction and stack pointer, then tart execution on the thread

pub fn read_state(&self, kind: ThreadStateKind, buf: &mut [u8]) -> ZxResult<usize>

Read one aspect of thread state.

pub fn write_state(&self, kind: ThreadStateKind, buf: &[u8]) -> ZxResult

Write one aspect of thread state.

pub fn get_thread_info(&self) -> ThreadInfo

Get the thread’s information.

pub fn get_thread_exception_info(&self) -> ZxResult<ExceptionReport>

Get the thread’s exception report.

pub fn state(&self) -> ThreadState

Get the thread state.

pub fn time_add(&self, time: u128)

Add the parameter to the time this thread has run on cpu.

pub fn get_time(&self) -> u64

Get the time this thread has run on cpu.

pub fn is_first_thread(&self) -> bool

Whether this thread is the first thread of a process.

pub fn flags(&self) -> ThreadFlag

Get the thread’s flags.

pub fn update_flags(&self, f: impl FnOnce(&mut ThreadFlag))

Apply f to the thread’s flags.

Trait Implementations

impl Debug for Thread

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl KernelObject for Thread

fn id(&self) -> KoID

Get object’s KoID.

fn type_name(&self) -> &str

Get the name of the type of the kernel object.

fn name(&self) -> String

Get object’s name.

fn set_name(&self, name: &str)

Set object’s name.

fn signal(&self) -> Signal

Get the signal status.

fn signal_set(&self, signal: Signal)

Assert signal.

fn signal_clear(&self, signal: Signal)

Deassert signal.

fn signal_change(&self, clear: Signal, set: Signal)

Change signal status: first clear then set indicated bits.

fn add_signal_callback(&self, callback: SignalHandler)

Add callback for signal status changes.

fn related_koid(&self) -> KoID

If the object is related to another (such as the other end of a channel, or the parent of a job), returns the KoID of that object, otherwise returns zero.

fn get_child(&self, _id: KoID) -> ZxResult<Arc<dyn KernelObject>>

Attempt to find a child of the object with given KoID.

fn peer(&self) -> ZxResult<Arc<dyn KernelObject>>

Attempt to get the object’s peer.

fn allowed_signals(&self) -> Signal

Get object’s allowed signals.

impl Task for Thread

fn kill(&self)

Kill the task. The task do not terminate immediately when killed. It will terminate after all its children are terminated or some cleanups are finished.

fn suspend(&self)

Suspend the task. Currently only thread or process handles may be suspended.

fn resume(&self)

Resume the task

fn exceptionate(&self) -> Arc<Exceptionate>

Get the exceptionate.

fn debug_exceptionate(&self) -> Arc<Exceptionate>

Get the debug exceptionate.