--- pth.pod 2002/10/25 11:56:16 1.157
+++ pth.pod 2002/11/03 09:59:33 1.158
@@ -138,6 +138,15 @@
pth_barrier_init,
pth_barrier_reach.
+=item B<User-Space Context>
+
+pth_uctx_create,
+pth_uctx_make,
+pth_uctx_save,
+pth_uctx_restore,
+pth_uctx_switch,
+pth_uctx_destroy.
+
=item B<Generalized POSIX Replacement API>
pth_sigwait_ev,
@@ -1464,6 +1473,86 @@
=back
+=head2 User-Space Context
+
+The following functions provide a stand-alone sub-API for user-space
+context switching. It internally is based on the same underlying machine
+context switching mechanism the threads in B<GNU Pth> are based on.
+Hence these functions you can use for implementing your own simple
+user-space threads. The C<pth_uctx_t> context is somewhat modeled after
+POSIX ucontext(3).
+
+The time required to create (via pth_uctx_make(3)) a user-space context
+can range from just a few microseconds up to a more dramatical time
+(depending on the machine context switching method which is available on
+the platform). On the other hand, the raw performance in switching the
+user-space contexts is always very good (nearly independent of the used
+machine context switching method). For instance, on an Intel Pentium-III
+CPU with 800Mhz running under FreeBSD 4 one usually achieves about
+260,000 user-space context switches (via pth_uctx_switch(3)) per second.
+
+=over 4
+
+=item int B<pth_uctx_create>(pth_uctx_t *I<uctx>);
+
+This function creates a user-space context and stores it into I<uctx>.
+There is still no underlying user-space context configured. You still
+have to do this with pth_uctx_make(3) or pth_uctx_set(3). On success,
+this function returns C<TRUE>, else C<FALSE>.
+
+=item int B<pth_uctx_make>(pth_uctx_t I<uctx>, char *I<sk_addr>, size_t I<sk_size>, const sigset_t *I<sigmask>, void (*I<start_func>)(void *), void *I<start_arg>, pth_uctx_t I<uctx_after>);
+
+This function makes a new user-space context in I<uctx> which will
+operate on the run-time stack I<sk_addr> (which is of maximum
+size I<sk_size>), with the signals in I<sigmask> blocked (if
+I<sigmask> is not C<NULL>) and starting to execute with the call
+I<start_func>(I<start_arg>). If I<sk_addr> is C<NULL>, a stack
+is dynamically allocated. The stack size I<sk_size> has to be at
+least 16384 (16KB). If the start function I<start_func> returns and
+I<uctx_after> is not C<NULL>, an implicit user-space context switch
+to this context is performed. Else (if I<uctx_after> is C<NULL>) the
+process is terminated with exit(3). This function is somewhat modeled
+after POSIX makecontext(3). On success, this function returns C<TRUE>,
+else C<FALSE>.
+
+=item int B<pth_uctx_save>(pth_uctx_t I<uctx>);
+
+This function saves the current user-space context in I<uctx> for later
+restoring by either pth_uctx_restore(3) or pth_uctx_switch(3). This
+function is somewhat modeled after POSIX getcontext(3). If I<uctx> is
+C<NULL>, C<FALSE> is returned instead of C<TRUE>. This is the only error
+possible.
+
+=item int B<pth_uctx_restore>(pth_uctx_t I<uctx>);
+
+This function restores the current user-space context from I<uctx>,
+which previously had to be set with either pth_uctx_make(3) or
+pth_uctx_save(3). This function is somewhat modeled after POSIX
+setcontext(3). If I<uctx> is C<NULL> or I<uctx> contains no valid
+user-space context, C<FALSE> is returned instead of C<TRUE>. These are
+the only errors possible.
+
+=item int B<pth_uctx_switch>(pth_uctx_t I<uctx_from>, pth_uctx_t I<uctx_to>);
+
+This function saves the current user-space context in I<uctx_from> for
+later restoring by either pth_uctx_restore(3) or pth_uctx_switch(3) and
+restores the new user-space context from I<uctx>, which previously
+had to be set with either pth_uctx_make(3) or pth_uctx_save(3). This
+function is somewhat modeled after POSIX swapcontext(3). If I<uctx_from>
+or I<uctx_to> are C<NULL> or if I<uctx_to> contains no valid user-space
+context, C<FALSE> is returned instead of C<TRUE>. These are the only
+errors possible.
+
+=item int B<pth_uctx_destroy>(pth_uctx_t I<uctx>);
+
+This function destroys the user-space context in I<uctx>. The run-time
+stack associated with the user-space context is deallocated only if it
+was given by the application (see I<sk_addr> of pth_uctx_create(3)).
+If I<uctx> is C<NULL>, C<FALSE> is returned instead of C<TRUE>. This
+is the only error possible.
+
+=back
+
=head2 Generalized POSIX Replacement API
The following functions are generalized replacements functions for the POSIX
|
