Struct zircon_object::task::Process
source · [−]pub struct Process { /* private fields */ }
Expand description
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:
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
sourceimpl Process
impl Process
sourcepub fn create(job: &Arc<Job>, name: &str) -> ZxResult<Arc<Self>>
pub fn create(job: &Arc<Job>, name: &str) -> ZxResult<Arc<Self>>
Create a new process in the job
.
sourcepub fn create_with_ext(
job: &Arc<Job>,
name: &str,
ext: impl Any + Send + Sync
) -> ZxResult<Arc<Self>>
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.
sourcepub fn start(
&self,
thread: &Arc<Thread>,
entry: usize,
stack: usize,
arg1: Option<Handle>,
arg2: usize,
thread_fn: ThreadFn
) -> ZxResult
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.put_context(cx);
})).unwrap();
sourcepub fn exit(&self, retcode: i64)
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.
sourcepub fn check_policy(&self, condition: PolicyCondition) -> ZxResult
pub fn check_policy(&self, condition: PolicyCondition) -> ZxResult
Check whether condition
is allowed in the parent job’s policy.
sourcepub fn set_critical_at_job(
&self,
critical_to_job: &Arc<Job>,
retcode_nonzero: bool
) -> ZxResult
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.
sourcepub fn vmar(&self) -> Arc<VmAddressRegion>
pub fn vmar(&self) -> Arc<VmAddressRegion>
Get the VmAddressRegion
of the process.
sourcepub fn add_handle(&self, handle: Handle) -> HandleValue
pub fn add_handle(&self, handle: Handle) -> HandleValue
Add a handle to the process
sourcepub fn add_handles(&self, handles: Vec<Handle>) -> Vec<HandleValue>
pub fn add_handles(&self, handles: Vec<Handle>) -> Vec<HandleValue>
Add all handles to the process
sourcepub fn remove_handle(&self, handle_value: HandleValue) -> ZxResult<Handle>
pub fn remove_handle(&self, handle_value: HandleValue) -> ZxResult<Handle>
Remove a handle from the process
sourcepub fn remove_handles(
&self,
handle_values: &[HandleValue]
) -> ZxResult<Vec<Handle>>
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.
sourcepub fn remove_object<T: KernelObject>(
&self,
handle_value: HandleValue
) -> ZxResult<Arc<T>>
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.
sourcepub fn dup_handle_operating_rights(
&self,
handle_value: HandleValue,
operation: impl FnOnce(Rights) -> ZxResult<Rights>
) -> ZxResult<HandleValue>
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.
sourcepub fn get_object_with_rights<T: KernelObject>(
&self,
handle_value: HandleValue,
desired_rights: Rights
) -> ZxResult<Arc<T>>
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
.
sourcepub fn get_object_and_rights<T: KernelObject>(
&self,
handle_value: HandleValue
) -> ZxResult<(Arc<T>, 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.
sourcepub fn get_dyn_object_with_rights(
&self,
handle_value: HandleValue,
desired_rights: Rights
) -> ZxResult<Arc<dyn KernelObject>>
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
.
sourcepub fn get_dyn_object_and_rights(
&self,
handle_value: HandleValue
) -> ZxResult<(Arc<dyn KernelObject>, 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.
sourcepub fn get_object<T: KernelObject>(
&self,
handle_value: HandleValue
) -> ZxResult<Arc<T>>
pub fn get_object<T: KernelObject>(
&self,
handle_value: HandleValue
) -> ZxResult<Arc<T>>
Get the kernel object corresponding to this handle_value
sourcepub fn get_handle_info(
&self,
handle_value: HandleValue
) -> ZxResult<HandleBasicInfo>
pub fn get_handle_info(
&self,
handle_value: HandleValue
) -> ZxResult<HandleBasicInfo>
Get the handle’s information corresponding to handle_value
.
sourcepub fn get_info(&self) -> ProcessInfo
pub fn get_info(&self) -> ProcessInfo
Get information of this process.
sourcepub fn set_debug_addr(&self, addr: usize)
pub fn set_debug_addr(&self, addr: usize)
Set the debug address.
sourcepub fn get_debug_addr(&self) -> usize
pub fn get_debug_addr(&self) -> usize
Get the debug address.
sourcepub fn set_dyn_break_on_load(&self, addr: usize)
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.
sourcepub fn get_dyn_break_on_load(&self) -> usize
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.
sourcepub fn get_cancel_token(
&self,
handle_value: HandleValue
) -> ZxResult<Receiver<()>>
pub fn get_cancel_token(
&self,
handle_value: HandleValue
) -> ZxResult<Receiver<()>>
Get an one-shot Receiver
for receiving cancel message of the given handle.
sourcepub fn thread_ids(&self) -> Vec<KoID>
pub fn thread_ids(&self) -> Vec<KoID>
Get KoIDs of Threads.
sourcepub async fn wait_for_exit(self: &Arc<Self>) -> i64
pub async fn wait_for_exit(self: &Arc<Self>) -> i64
Wait for process exit and get return code.
Trait Implementations
sourceimpl KernelObject for Process
impl KernelObject for Process
sourcefn signal_set(&self, signal: Signal)
fn signal_set(&self, signal: Signal)
Assert signal
.
sourcefn signal_clear(&self, signal: Signal)
fn signal_clear(&self, signal: Signal)
Deassert signal
.
sourcefn signal_change(&self, clear: Signal, set: Signal)
fn signal_change(&self, clear: Signal, set: Signal)
Change signal status: first clear
then set
indicated bits. Read more
sourcefn add_signal_callback(&self, callback: SignalHandler)
fn add_signal_callback(&self, callback: SignalHandler)
Add callback
for signal status changes. Read more
sourcefn get_child(&self, id: KoID) -> ZxResult<Arc<dyn KernelObject>>
fn get_child(&self, id: KoID) -> ZxResult<Arc<dyn KernelObject>>
Attempt to find a child of the object with given KoID. Read more
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. Read more
sourcefn allowed_signals(&self) -> Signal
fn allowed_signals(&self) -> Signal
Get object’s allowed signals.
sourceimpl Task for Process
impl Task for Process
sourcefn kill(&self)
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. Read more
sourcefn exceptionate(&self) -> Arc<Exceptionate>
fn exceptionate(&self) -> Arc<Exceptionate>
Get the exceptionate.
sourcefn debug_exceptionate(&self) -> Arc<Exceptionate>
fn debug_exceptionate(&self) -> Arc<Exceptionate>
Get the debug exceptionate.
Auto Trait Implementations
impl !RefUnwindSafe for Process
impl Send for Process
impl Sync for Process
impl Unpin for Process
impl !UnwindSafe for Process
Blanket Implementations
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
sourceimpl<T> CheckedAs for T
impl<T> CheckedAs for T
sourcefn checked_as<Dst>(self) -> Option<Dst> where
T: CheckedCast<Dst>,
fn checked_as<Dst>(self) -> Option<Dst> where
T: CheckedCast<Dst>,
Casts the value.
sourceimpl<Src, Dst> CheckedCastFrom<Src> for Dst where
Src: CheckedCast<Dst>,
impl<Src, Dst> CheckedCastFrom<Src> for Dst where
Src: CheckedCast<Dst>,
sourcefn checked_cast_from(src: Src) -> Option<Dst>
fn checked_cast_from(src: Src) -> Option<Dst>
Casts the value.
impl<T> Downcast for T where
T: Any,
impl<T> Downcast for T where
T: Any,
fn into_any(self: Box<T, Global>) -> Box<dyn Any + 'static, Global>
fn into_any(self: Box<T, Global>) -> Box<dyn Any + 'static, Global>
Convert Box<dyn Trait>
(where Trait: Downcast
) to Box<dyn Any>
. Box<dyn Any>
can
then be further downcast
into Box<ConcreteType>
where ConcreteType
implements Trait
. Read more
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any + 'static>
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any + 'static>
Convert Rc<Trait>
(where Trait: Downcast
) to Rc<Any>
. Rc<Any>
can then be
further downcast
into Rc<ConcreteType>
where ConcreteType
implements Trait
. Read more
fn as_any(&self) -> &(dyn Any + 'static)
fn as_any(&self) -> &(dyn Any + 'static)
Convert &Trait
(where Trait: Downcast
) to &Any
. This is needed since Rust cannot
generate &Any
’s vtable from &Trait
’s. Read more
fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
Convert &mut Trait
(where Trait: Downcast
) to &Any
. This is needed since Rust cannot
generate &mut Any
’s vtable from &mut Trait
’s. Read more
sourceimpl<T> OverflowingAs for T
impl<T> OverflowingAs for T
sourcefn overflowing_as<Dst>(self) -> (Dst, bool) where
T: OverflowingCast<Dst>,
fn overflowing_as<Dst>(self) -> (Dst, bool) where
T: OverflowingCast<Dst>,
Casts the value.
sourceimpl<Src, Dst> OverflowingCastFrom<Src> for Dst where
Src: OverflowingCast<Dst>,
impl<Src, Dst> OverflowingCastFrom<Src> for Dst where
Src: OverflowingCast<Dst>,
sourcefn overflowing_cast_from(src: Src) -> (Dst, bool)
fn overflowing_cast_from(src: Src) -> (Dst, bool)
Casts the value.
sourceimpl<T> SaturatingAs for T
impl<T> SaturatingAs for T
sourcefn saturating_as<Dst>(self) -> Dst where
T: SaturatingCast<Dst>,
fn saturating_as<Dst>(self) -> Dst where
T: SaturatingCast<Dst>,
Casts the value.
sourceimpl<Src, Dst> SaturatingCastFrom<Src> for Dst where
Src: SaturatingCast<Dst>,
impl<Src, Dst> SaturatingCastFrom<Src> for Dst where
Src: SaturatingCast<Dst>,
sourcefn saturating_cast_from(src: Src) -> Dst
fn saturating_cast_from(src: Src) -> Dst
Casts the value.
sourceimpl<T> UnwrappedAs for T
impl<T> UnwrappedAs for T
sourcefn unwrapped_as<Dst>(self) -> Dst where
T: UnwrappedCast<Dst>,
fn unwrapped_as<Dst>(self) -> Dst where
T: UnwrappedCast<Dst>,
Casts the value.
sourceimpl<Src, Dst> UnwrappedCastFrom<Src> for Dst where
Src: UnwrappedCast<Dst>,
impl<Src, Dst> UnwrappedCastFrom<Src> for Dst where
Src: UnwrappedCast<Dst>,
sourcefn unwrapped_cast_from(src: Src) -> Dst
fn unwrapped_cast_from(src: Src) -> Dst
Casts the value.
sourceimpl<T> WrappingAs for T
impl<T> WrappingAs for T
sourcefn wrapping_as<Dst>(self) -> Dst where
T: WrappingCast<Dst>,
fn wrapping_as<Dst>(self) -> Dst where
T: WrappingCast<Dst>,
Casts the value.
sourceimpl<Src, Dst> WrappingCastFrom<Src> for Dst where
Src: WrappingCast<Dst>,
impl<Src, Dst> WrappingCastFrom<Src> for Dst where
Src: WrappingCast<Dst>,
sourcefn wrapping_cast_from(src: Src) -> Dst
fn wrapping_cast_from(src: Src) -> Dst
Casts the value.