Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.

RUMP_LWPROC(3)             Library Functions Manual             RUMP_LWPROC(3)

NAME
     rump_lwproc - rump kernel process/lwp management

LIBRARY
     rump kernel (librump, -lrump)

SYNOPSIS
     #include <rump/rump.h>

     int
     rump_pub_lwproc_rfork(int flags);

     int
     rump_pub_lwproc_newlwp(pid_t pid);

     void
     rump_pub_lwproc_switch(struct lwp *l);

     void
     rump_pub_lwproc_releaselwp();

     struct lwp *
     rump_pub_lwproc_curlwp();

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 a rump kernel uses the host's thread and
     process context directly, the rules for how thread context is determined
     are different.

     In the rump kernel model, each host thread (implemented for example with
     pthreads or green threads) 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.

     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 kernel lwps have been created, switching curlwp is very cheap.
     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.  A rump kernel lwp will persist until it is explicitly
     released.  A rump kernel process will persist until all of its lwps have
     been released, at which point the process is automatically released.

     rump_pub_lwproc_rfork()
           Create a process, one lwp inside it and set curlwp to the new lwp.
           The flags parameter controls how file descriptors are inherited
           from the parent.  By default (flags=0) file descriptors are shared.
           Other options are:

           RUMP_RFFDG     Copy file descriptors from parent.  This is what
                          fork(2) does.

           RUMP_RFCFDG    File descriptors neither copied nor shared, i.e. new
                          process does not have access to the parent's file
                          descriptors.

           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 rump_sys_getpid().

     rump_pub_lwproc_newlwp(pid)
           Create a new lwp attached to the process specified by pid.  Sets
           curlwp to the new lwp.  This routine returns 0 for success or an
           errno indicating the reason for failure.

     rump_pub_lwproc_switch(l)
           Sets curlwp to 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 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.

     rump_pub_lwproc_releaselwp()
           Release curlwp and set curlwp to implicit 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.

     rump_pub_lwproc_curlwp()
           Returns curlwp or NULL if the current context is an implicit
           context.

RETURN VALUES
     rump_pub_lwproc_rfork() and rump_pub_lwproc_newlwp() return 0 on success
     or an errno indicating the reason for failure.  rump_pub_lwproc_curlwp()
     returns curlwp or NULL if the current context is an implicit context.

SEE ALSO
     getpid(2), rump(3)

HISTORY
     rump_lwproc first appeared in NetBSD 6.0.

NetBSD 10.99                   October 27, 2014                   NetBSD 10.99