1.\" $NetBSD: rump_lwproc.3,v 1.2 2015/03/23 15:42:29 pooka Exp $ 2.\" 3.\" Copyright (c) 2010 Antti Kantee. All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.Dd October 27, 2014 27.Dt RUMP_LWPROC 3 28.Os 29.Sh NAME 30.Nm rump_lwproc 31.Nd rump kernel process/lwp management 32.Sh LIBRARY 33rump kernel (librump, \-lrump) 34.Sh SYNOPSIS 35.In rump/rump.h 36.Ft int 37.Fn rump_pub_lwproc_rfork "int flags" 38.Ft int 39.Fn rump_pub_lwproc_newlwp "pid_t pid" 40.Ft void 41.Fn rump_pub_lwproc_switch "struct lwp *l" 42.Ft void 43.Fn rump_pub_lwproc_releaselwp 44.Ft struct lwp * 45.Fn rump_pub_lwproc_curlwp 46.Sh DESCRIPTION 47In a normal operating system model a process is a resource 48container and a thread (lwp) is the execution context. 49Every lwp is associated with exactly one process, and a process is 50associated with one or more lwps. 51The current lwp (curlwp) indicates the current process and determines 52which resources, such as UID/GID, current working directory, and 53file descriptor table, are currently used. 54These basic principles apply to rump kernels as well, but since 55a rump kernel uses the host's thread and process context directly, the rules 56for how thread context is determined are different. 57.Pp 58In the rump kernel model, each host thread (implemented for example 59with pthreads or green threads) is either bound to 60a rump kernel lwp or accesses the rump kernel with an implicit thread 61context associated with pid 1. 62An implicit thread context is created every time the rump kernel 63is entered and disbanded upon exit. 64While convenient for occasional calls, creating an implicit thread 65uses a shared resource which can become highly contended in a 66multithreaded situation. 67It is therefore recommended that dedicated threads are created. 68.Pp 69The association between host threads and the rump kernel curlwp is 70left to the caller. 71It is possible to create a dedicated host thread for every 72rump kernel lwp or multiplex them on top of a single host thread. 73After rump kernel lwps have been created, switching curlwp is very cheap. 74In case multiple lwps/processes are created, it is the caller's 75responsibility to keep track of them and release them when they 76are no longer necessary. 77A rump kernel lwp will persist until it is explicitly released. 78A rump kernel process will persist until all of its lwps have been 79released, at which point the process is automatically released. 80.Bl -tag -width xxxx 81.It Fn rump_pub_lwproc_rfork 82Create a process, one lwp inside it and set curlwp to the new lwp. 83The 84.Ar flags 85parameter controls how file descriptors are inherited from the 86parent. 87By default (flags=0) file descriptors are shared. 88Other options are: 89.Bl -tag -width RUMP_RFCFDGXX 90.It Dv RUMP_RFFDG 91Copy file descriptors from parent. 92This is what 93.Xr fork 2 94does. 95.It Dv RUMP_RFCFDG 96File descriptors neither copied nor shared, i.e. new process does not 97have access to the parent's file descriptors. 98.El 99.Pp 100This routine returns 0 for success or an errno indicating the reason 101for failure. 102The new process id can be retrieved in the normal fashion by calling 103.Fn rump_sys_getpid . 104.It Fn rump_pub_lwproc_newlwp "pid" 105Create a new lwp attached to the process specified by 106.Fa pid . 107Sets curlwp to the new lwp. 108This routine returns 0 for success or an errno indicating the reason 109for failure. 110.It Fn rump_pub_lwproc_switch "l" 111Sets curlwp to 112.Fa l . 113In case the new thread is associated with a different process than the 114current one, the process context is also switched. 115The special value 116.Dv NULL 117sets curlwp to implicit context. 118Switching to an already running lwp, i.e. attempting to use the 119same curlwp in two host threads simultaneously causes a fatal error. 120.It Fn rump_pub_lwproc_releaselwp 121Release curlwp and set curlwp to implicit context. 122In case curlwp was the last thread inside the current process, the 123process container is also released. 124Calling this routine without a dedicated curlwp is a fatal error. 125.It Fn rump_pub_lwproc_curlwp 126Returns curlwp or 127.Dv NULL 128if the current context is an implicit context. 129.El 130.Sh RETURN VALUES 131.Fn rump_pub_lwproc_rfork 132and 133.Fn rump_pub_lwproc_newlwp 134return 0 on success or an errno indicating the reason for failure. 135.Fn rump_pub_lwproc_curlwp 136returns curlwp or 137.Dv NULL 138if the current context is an implicit context. 139.Sh SEE ALSO 140.Xr getpid 2 , 141.Xr rump 3 142.Sh HISTORY 143.Nm 144first appeared in 145.Nx 6.0 . 146