Module Name: src
Committed By: pooka
Date: Thu Sep 2 12:29:49 UTC 2010
Modified Files:
src/distrib/sets/lists/comp: mi
src/lib/librump: Makefile
Added Files:
src/lib/librump: rump_lwproc.3
Log Message:
document rump_lwproc
To generate a diff of this commit:
cvs rdiff -u -r1.1505 -r1.1506 src/distrib/sets/lists/comp/mi
cvs rdiff -u -r1.2 -r1.3 src/lib/librump/Makefile
cvs rdiff -u -r0 -r1.1 src/lib/librump/rump_lwproc.3
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/distrib/sets/lists/comp/mi
diff -u src/distrib/sets/lists/comp/mi:1.1505 src/distrib/sets/lists/comp/mi:1.1506
--- src/distrib/sets/lists/comp/mi:1.1505 Fri Aug 27 16:29:13 2010
+++ src/distrib/sets/lists/comp/mi Thu Sep 2 12:29:49 2010
@@ -1,4 +1,4 @@
-# $NetBSD: mi,v 1.1505 2010/08/27 16:29:13 tron Exp $
+# $NetBSD: mi,v 1.1506 2010/09/02 12:29:49 pooka Exp $
#
# Note: don't delete entries from here - mark them as "obsolete" instead.
#
@@ -7861,6 +7861,7 @@
./usr/share/man/cat3/rresvport_af.0 comp-c-catman .cat
./usr/share/man/cat3/rsa.0 comp-obsolete obsolete
./usr/share/man/cat3/rump.0 comp-c-catman .cat
+./usr/share/man/cat3/rump_lwproc.0 comp-c-catman .cat
./usr/share/man/cat3/rumpuser.0 comp-c-catman .cat
./usr/share/man/cat3/ruserok.0 comp-c-catman .cat
./usr/share/man/cat3/savetty.0 comp-c-catman .cat
@@ -13748,6 +13749,7 @@
./usr/share/man/html3/rresvport.html comp-c-htmlman html
./usr/share/man/html3/rresvport_af.html comp-c-htmlman html
./usr/share/man/html3/rump.html comp-c-htmlman html
+./usr/share/man/html3/rump_lwproc.html comp-c-htmlman html
./usr/share/man/html3/rumpuser.html comp-c-htmlman html
./usr/share/man/html3/ruserok.html comp-c-htmlman html
./usr/share/man/html3/savetty.html comp-c-htmlman html
@@ -19643,6 +19645,7 @@
./usr/share/man/man3/rresvport_af.3 comp-c-man .man
./usr/share/man/man3/rsa.3 comp-obsolete obsolete
./usr/share/man/man3/rump.3 comp-c-man .man
+./usr/share/man/man3/rump_lwproc.3 comp-c-man .man
./usr/share/man/man3/rumpuser.3 comp-c-man .man
./usr/share/man/man3/ruserok.3 comp-c-man .man
./usr/share/man/man3/savetty.3 comp-c-man .man
Index: src/lib/librump/Makefile
diff -u src/lib/librump/Makefile:1.2 src/lib/librump/Makefile:1.3
--- src/lib/librump/Makefile:1.2 Thu Feb 12 13:20:17 2009
+++ src/lib/librump/Makefile Thu Sep 2 12:29:49 2010
@@ -1,10 +1,10 @@
-# $NetBSD: Makefile,v 1.2 2009/02/12 13:20:17 lukem Exp $
+# $NetBSD: Makefile,v 1.3 2010/09/02 12:29:49 pooka Exp $
#
RUMPTOP= ${.CURDIR}/../../sys/rump
LIBDPLIBS+= rumpuser ${.CURDIR}/../librumpuser
-MAN= rump.3
+MAN= rump.3 rump_lwproc.3
WARNS= 3 # XXX: kernel isn't ready for -Wsign-compare
Added files:
Index: src/lib/librump/rump_lwproc.3
diff -u /dev/null src/lib/librump/rump_lwproc.3:1.1
--- /dev/null Thu Sep 2 12:29:50 2010
+++ src/lib/librump/rump_lwproc.3 Thu Sep 2 12:29:49 2010
@@ -0,0 +1,119 @@
+.\" $NetBSD: rump_lwproc.3,v 1.1 2010/09/02 12:29:49 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 September 2, 2010
+.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_newproc
+.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 a implicit thread
+context associated with the system process proc0.
+The implicit thread context is created every time the rump kernel
+is entered and disbanded upon exit.
+While convenient for occasional calls, creating the 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_newproc
+Create a process and one lwp inside it.
+Sets curlwp to the new lwp.
+The new process id can be retrieved in the normal fashion by calling
+.Fn rump_sys_getpid .
+This routine returns 0 for success or an errno indicating the reason
+for failure.
+.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 proc0 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 proc0 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 the implicit proc0 context.
+.El
+.Sh SEE ALSO
+.Xr getpid 2 ,
+.Xr rump 3
+.Sh HISTORY
+.Nm
+first appeared in
+.Nx 6.0 .
