Struct zircon_object::task::Process

pub struct Process { /* fields omitted */ }

Process abstraction

SYNOPSIS

A zircon process is an instance of a program in the traditional sense: a set of instructions which will be executed by one or more threads, along with a collection of resources.

DESCRIPTION

The process object is a container of the following resources:

• Handles
• Virtual Memory Address Regions
• Threads

In general, it is associated with code which it is executing until it is forcefully terminated or the program exits.

Processes are owned by jobs and allow an application that is composed by more than one process to be treated as a single entity, from the perspective of resource and permission limits, as well as lifetime control.

Lifetime

A process is created via Process::create() and its execution begins with Process::start().

The process stops execution when:

• the last thread is terminated or exits
• the process calls Process::exit()
• the parent job terminates the process
• the parent job is destroyed

The call to Process::start() cannot be issued twice. New threads cannot be added to a process that was started and then its last thread has exited.

Implementations

impl Process

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

Create a new process in the job.

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

Create a new process with extension info.

pub fn start(
    &self,
    thread: &Arc<Thread>,
    entry: usize,
    stack: usize,
    arg1: Option<Handle>,
    arg2: usize,
    thread_fn: ThreadFn
) -> ZxResult

Start the first thread in the process.

This causes a thread to begin execution at the program counter specified by entry and with the stack pointer set to stack. The arguments arg1 and arg2 are arranged to be in the architecture specific registers used for the first two arguments of a function call before the thread is started. All other registers are zero upon start.

Example

let job = Job::root();
let proc = Process::create(&job, "proc").unwrap();
let thread = Thread::create(&proc, "thread").unwrap();
let handle = Handle::new(proc.clone(), Rights::DEFAULT_PROCESS);

// start the new thread
proc.start(&thread, 1, 4, Some(handle), 2, |thread| Box::pin(async move {
    let cx = thread.wait_for_run().await;
    assert_eq!(cx.general.rip, 1);  // entry
    assert_eq!(cx.general.rsp, 4);  // stack_top
    assert_eq!(cx.general.rdi, 3);  // arg0 (handle)
    assert_eq!(cx.general.rsi, 2);  // arg1
    thread.end_running(cx);
})).unwrap();

pub fn exit(&self, retcode: i64)

Exit current process with retcode. The process do not terminate immediately when exited. It will terminate after all its child threads are terminated.

pub fn check_policy(&self, condition: PolicyCondition) -> ZxResult

Check whether condition is allowed in the parent job’s policy.

pub fn set_critical_at_job(
    &self,
    critical_to_job: &Arc<Job>,
    retcode_nonzero: bool
) -> ZxResult

Set a process as critical to the job.

When process terminates, job will be terminated as if task_kill() was called on it. The return code used will be ZX_TASK_RETCODE_CRITICAL_PROCESS_KILL.

The job specified must be the parent of process, or an ancestor.

If retcode_nonzero is true, then job will only be terminated if process has a non-zero return code.

pub fn status(&self) -> Status

Get process status.

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

Get the extension.

pub fn vmar(&self) -> Arc<VmAddressRegion>

Get the VmAddressRegion of the process.

pub fn job(&self) -> Arc<Job>

Get the job of the process.

pub fn add_handle(&self, handle: Handle) -> HandleValue

Add a handle to the process

pub fn add_handles(&self, handles: Vec<Handle>) -> Vec<HandleValue>

Add all handles to the process

pub fn remove_handle(&self, handle_value: HandleValue) -> ZxResult<Handle>

Remove a handle from the process

pub fn remove_handles(
    &self,
    handle_values: &[HandleValue]
) -> ZxResult<Vec<Handle>>

Remove all handles from the process.

If one or more error happens, return one of them. All handles are discarded on success or failure.

pub fn remove_object<T: KernelObject>(
    &self,
    handle_value: HandleValue
) -> ZxResult<Arc<T>>

Remove a handle referring to a kernel object of the given type from the process.

pub fn get_futex(&self, addr: &'static AtomicI32) -> Arc<Futex>

Get a futex from the process

pub fn dup_handle_operating_rights(
    &self,
    handle_value: HandleValue,
    operation: impl FnOnce(Rights) -> ZxResult<Rights>
) -> ZxResult<HandleValue>

Duplicate a handle with new rights, return the new handle value.

The handle must have Rights::DUPLICATE. To duplicate the handle with the same rights use Rights::SAME_RIGHTS. If different rights are desired they must be strictly lesser than of the source handle, or an ZxError::ACCESS_DENIED will be raised.

pub fn get_object_with_rights<T: KernelObject>(
    &self,
    handle_value: HandleValue,
    desired_rights: Rights
) -> ZxResult<Arc<T>>

Get the kernel object corresponding to this handle_value, after checking that this handle has the desired_rights.

pub fn get_object_and_rights<T: KernelObject>(
    &self,
    handle_value: HandleValue
) -> ZxResult<(Arc<T>, Rights)>

Get the kernel object corresponding to this handle_value and this handle’s rights.

pub fn get_dyn_object_with_rights(
    &self,
    handle_value: HandleValue,
    desired_rights: Rights
) -> ZxResult<Arc<dyn KernelObject>>

Get the kernel object corresponding to this handle_value, after checking that this handle has the desired_rights.

pub fn get_dyn_object_and_rights(
    &self,
    handle_value: HandleValue
) -> ZxResult<(Arc<dyn KernelObject>, Rights)>

Get the kernel object corresponding to this handle_value and this handle’s rights.

pub fn get_object<T: KernelObject>(
    &self,
    handle_value: HandleValue
) -> ZxResult<Arc<T>>

Get the kernel object corresponding to this handle_value

pub fn get_handle_info(
    &self,
    handle_value: HandleValue
) -> ZxResult<HandleBasicInfo>

Get the handle’s information corresponding to handle_value.

pub fn get_info(&self) -> ProcessInfo

Get information of this process.

pub fn set_debug_addr(&self, addr: usize)

Set the debug address.

pub fn get_debug_addr(&self) -> usize

Get the debug address.

pub fn set_dyn_break_on_load(&self, addr: usize)

Set the address where the dynamic loader will issue a debug trap on every load of a shared library to. Setting this property to zero will disable it.

pub fn get_dyn_break_on_load(&self) -> usize

Get the address where the dynamic loader will issue a debug trap on every load of a shared library to.

pub fn get_cancel_token(
    &self,
    handle_value: HandleValue
) -> ZxResult<Receiver<()>>

Get an one-shot Receiver for receiving cancel message of the given handle.

pub fn thread_ids(&self) -> Vec<KoID>

Get KoIDs of Threads.

pub async fn wait_for_exit(self: &Arc<Self>) -> i64

Wait for process exit and get return code.

Trait Implementations

impl Debug for Process

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

Formats the value using the given formatter.

impl KernelObject for Process

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 get_child(&self, id: KoID) -> ZxResult<Arc<dyn KernelObject>>

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

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 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 Process

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.