136 lines
5.1 KiB
Groff
136 lines
5.1 KiB
Groff
.\" $NetBSD: rump_lwproc.3,v 1.4 2011/01/02 13:03:29 pooka Exp $
|
|
.\"
|
|
.\" Copyright (c) 2010 Antti Kantee. All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.Dd January 2, 2011
|
|
.Dt RUMP_LWPROC 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm rump_lwproc
|
|
.Nd rump process/lwp management
|
|
.Sh LIBRARY
|
|
rump kernel (librump, \-lrump)
|
|
.Sh SYNOPSIS
|
|
.In rump/rump.h
|
|
.Ft int
|
|
.Fn rump_pub_lwproc_rfork "int flags"
|
|
.Ft int
|
|
.Fn rump_pub_lwproc_newlwp "pid_t pid"
|
|
.Ft void
|
|
.Fn rump_pub_lwproc_switch "struct lwp *l"
|
|
.Ft void
|
|
.Fn rump_pub_lwproc_releaselwp
|
|
.Ft struct lwp *
|
|
.Fn rump_pub_lwproc_curlwp
|
|
.Sh DESCRIPTION
|
|
In a normal operating system model a process is a resource
|
|
container and a thread (lwp) is the execution context.
|
|
Every lwp is associated with exactly one process, and a process is
|
|
associated with one or more lwps.
|
|
The current lwp (curlwp) indicates the current process and determines
|
|
which resources, such as UID/GID, current working directory, and
|
|
file descriptor table, are currently used.
|
|
These basic principles apply to rump kernels as well, but since
|
|
rump uses the host's thread and process context directly, the rules
|
|
for how thread context is determined are different.
|
|
.Pp
|
|
In the rump model, each host thread (pthread) is either bound to
|
|
a rump kernel lwp or accesses the rump kernel with an implicit thread
|
|
context associated with pid 1.
|
|
An implicit thread context is created every time the rump kernel
|
|
is entered and disbanded upon exit.
|
|
While convenient for occasional calls, creating an implicit thread
|
|
uses a shared resource which can become highly contended in a
|
|
multithreaded situation.
|
|
It is therefore recommended that dedicated threads are created.
|
|
.Pp
|
|
The association between host threads and the rump kernel curlwp is
|
|
left to the caller.
|
|
It is possible to create a dedicated host thread for every
|
|
rump kernel lwp or multiplex them on top of a single host thread.
|
|
After rump lwps have been created, switching curlwp is very cheap
|
|
-- faster than a thread context switch on the host.
|
|
In case multiple lwps/processes are created, it is the caller's
|
|
responsibility to keep track of them and release them when they
|
|
are no longer necessary.
|
|
Like other rump kernel resources, procs/lwps will be released when
|
|
the process hosting the rump kernel exits.
|
|
.Bl -tag -width xxxx
|
|
.It Fn rump_pub_lwproc_rfork
|
|
Create a process, one lwp inside it and set curlwp to the new lwp.
|
|
The
|
|
.Ar flags
|
|
parameter controls how file descriptors are inherited from the
|
|
parent.
|
|
By default (flags=0) file descriptors are shared.
|
|
Other options are:
|
|
.Bl -tag -width RUMP_RFCFDGXX
|
|
.It Dv RUMP_RFFDG
|
|
Copy file descriptors from parent.
|
|
This is what
|
|
.Xr fork 2
|
|
does.
|
|
.It Dv RUMP_RFCFDG
|
|
File descriptors neither copied nor shared, i.e. new process does not
|
|
have access to the parent's file descriptors.
|
|
.El
|
|
.Pp
|
|
This routine returns 0 for success or an errno indicating the reason
|
|
for failure.
|
|
The new process id can be retrieved in the normal fashion by calling
|
|
.Fn rump_sys_getpid .
|
|
.It Fn rump_pub_lwproc_newlwp "pid"
|
|
Create a new lwp attached to the process specified by
|
|
.Fa pid .
|
|
Sets curlwp to the new lwp.
|
|
This routine returns 0 for success or an errno indicating the reason
|
|
for failure.
|
|
.It Fn rump_pub_lwproc_switch "l"
|
|
Sets curlwp to
|
|
.Fa l .
|
|
In case the new thread is associated with a different process than the
|
|
current one, the process context is also switched.
|
|
The special value
|
|
.Dv NULL
|
|
sets curlwp to implicit context.
|
|
Switching to an already running lwp, i.e. attempting to use the
|
|
same curlwp in two host threads simultaneously causes a fatal error.
|
|
.It Fn rump_pub_lwproc_releaselwp
|
|
Release curlwp and set curlwp to context.
|
|
In case curlwp was the last thread inside the current process, the
|
|
process container is also released.
|
|
Calling this routine without a dedicated curlwp is a fatal error.
|
|
.It Fn rump_pub_lwproc_curlwp
|
|
Returns curlwp or
|
|
.Dv NULL
|
|
if the current context is an implicit context.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr getpid 2 ,
|
|
.Xr rump 3
|
|
.Sh HISTORY
|
|
.Nm
|
|
first appeared in
|
|
.Nx 6.0 .
|