Index: ossp-pkg/pth/ChangeLog RCS File: /v/ossp/cvs/ossp-pkg/pth/ChangeLog,v rcsdiff -q -kk '-r1.530' '-r1.531' -u '/v/ossp/cvs/ossp-pkg/pth/ChangeLog,v' 2>/dev/null --- ChangeLog 2000/08/18 09:31:15 1.530 +++ ChangeLog 2000/09/30 08:00:17 1.531 @@ -19,7 +19,10 @@ | ||__ _| __|_(_) |_|_____________________________________________________________ - Changes between 1.4a3 and 1.4a4 (29-Jul-2000 to xx-Aug-2000) + Changes between 1.4a3 and 1.4a4 (29-Jul-2000 to xx-Sep-2000) + + *) Fixed typos in pth.pod: "fd" -> "s" for pth_connect/pth_accept. + [Sebastian ] *) Make --disable-shared the default under Solaris-2.[78]/x86, because it is known to segfault sporadically if Pth is built as a DSO. As Index: ossp-pkg/pth/THANKS RCS File: /v/ossp/cvs/ossp-pkg/pth/THANKS,v rcsdiff -q -kk '-r1.75' '-r1.76' -u '/v/ossp/cvs/ossp-pkg/pth/THANKS,v' 2>/dev/null --- THANKS 2000/07/10 06:12:34 1.75 +++ THANKS 2000/09/30 08:00:17 1.76 @@ -81,6 +81,7 @@ o David W. Schuler o Peter Simons o Robert S. Tau + o Sebastian o Anton Umnikov o David Scott Urban o Laurent Vaucher Index: ossp-pkg/pth/pth-config.1 RCS File: /v/ossp/cvs/ossp-pkg/pth/Attic/pth-config.1,v rcsdiff -q -kk '-r1.126' '-r1.127' -u '/v/ossp/cvs/ossp-pkg/pth/Attic/pth-config.1,v' 2>/dev/null --- pth-config.1 2000/08/18 07:39:09 1.126 +++ pth-config.1 2000/09/30 08:00:17 1.127 @@ -1,12 +1,9 @@ -.rn '' }` -''' $RCSfile$$Revision$$Date$ -''' -''' $Log$ -''' Revision 1.126 2000/08/18 07:39:09 rse -''' *** empty log message *** -''' -''' -.de Sh +.\" Automatically generated by Pod::Man version 1.02 +.\" Sat Sep 30 09:59:06 2000 +.\" +.\" Standard preamble: +.\" ====================================================================== +.de Sh \" Subsection heading .br .if t .Sp .ne 5 @@ -14,150 +11,106 @@ \fB\\$1\fR .PP .. -.de Sp +.de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. -.de Ip +.de Ip \" List item .br .ie \\n(.$>=3 .ne \\$3 .el .ne 3 .IP "\\$1" \\$2 .. -.de Vb +.de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. -.de Ve +.de Ve \" End verbatim text .ft R .fi .. -''' -''' -''' Set up \*(-- to give an unbreakable dash; -''' string Tr holds user defined translation string. -''' Bell System Logo is used as a dummy character. -''' +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. | will give a +.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used +.\" to do unbreakable dashes and therefore won't be available. \*(C` and +.\" \*(C' expand to `' in nroff, nothing in troff, for use with C<> .tr \(*W-|\(bv\*(Tr +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ -.ds -- \(*W- -.ds PI pi -.if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -.if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -.ds L" "" -.ds R" "" -''' \*(M", \*(S", \*(N" and \*(T" are the equivalent of -''' \*(L" and \*(R", except that they are used on ".xx" lines, -''' such as .IP and .SH, which do another additional levels of -''' double-quote interpretation -.ds M" """ -.ds S" """ -.ds N" """"" -.ds T" """"" -.ds L' ' -.ds R' ' -.ds M' ' -.ds S' ' -.ds N' ' -.ds T' ' +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` ` +. ds C' ' 'br\} .el\{\ -.ds -- \(em\| -.tr \*(Tr -.ds L" `` -.ds R" '' -.ds M" `` -.ds S" '' -.ds N" `` -.ds T" '' -.ds L' ` -.ds R' ' -.ds M' ` -.ds S' ' -.ds N' ` -.ds T' ' -.ds PI \(*p +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' 'br\} -.\" If the F register is turned on, we'll generate -.\" index entries out stderr for the following things: -.\" TH Title -.\" SH Header -.\" Sh Subsection -.\" Ip Item -.\" X<> Xref (embedded -.\" Of course, you have to process the output yourself -.\" in some meaninful fashion. -.if \nF \{ -.de IX -.tm Index:\\$1\t\\n%\t"\\$2" -.. -.nr % 0 -.rr F -.\} -.TH PTH-CONFIG 1 "18-Aug-2000" "GNU Pth 1.4a3" "GNU Portable Threads" -.UC -.if n .hy 0 +.\" +.\" If the F register is turned on, we'll generate index entries on stderr +.\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and +.\" index entries marked with X<> in POD. Of course, you'll have to process +.\" the output yourself in some meaningful fashion. +.if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +. . +. nr % 0 +. rr F +.\} +.\" +.\" For nroff, turn off justification. Always turn off hyphenation; it +.\" makes way too many mistakes in technical documents. +.hy 0 .if n .na -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.de CQ \" put $1 in typewriter font -.ft CW -'if n "\c -'if t \\&\\$1\c -'if n \\&\\$1\c -'if n \&" -\\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7 -'.ft R -.. -.\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2 -. \" AM - accent mark definitions +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. .bd B 3 -. \" fudge factors for nroff and troff +. \" fudge factors for nroff and troff .if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP .\} .if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& .\} -. \" simple accents for nroff and troff +. \" simple accents for nroff and troff .if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds ? ? -. ds ! ! -. ds / -. ds q +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / .\} .if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10' -. ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -. ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10' +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} -. \" troff and (daisy-wheel) nroff accents +. \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#] -.ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u' -.ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u' -.ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#] .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' @@ -165,95 +118,110 @@ .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E -.ds oe o\h'-(\w'o'u*4/10)'e -.ds Oe O\h'-(\w'O'u*4/10)'E -. \" corrections for vroff +. \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) +. \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ -. ds : e -. ds 8 ss -. ds v \h'-1'\o'\(aa\(ga' -. ds _ \h'-1'^ -. ds . \h'-1'. -. ds 3 3 -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -. ds oe oe -. ds Oe OE +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE .\} .rm #[ #] #H #V #F C +.\" ====================================================================== +.\" +.IX Title "PTH-CONFIG 1" +.TH PTH-CONFIG 1 "18-Aug-2000" "GNU Pth 1.4a3" "GNU Portable Threads" +.UC .SH "NAME" -\fBpth-config\fR \- Pth library build utility +\&\fBpth-config\fR \- Pth library build utility .SH "VERSION" -GNU Pth 1.4a3 (18-Aug-2000) +.IX Header "VERSION" +\&\s-1GNU\s0 Pth \s-11.4a3 (18-Aug-2000)\s0 .SH "SYNOPSIS" -\fBpth-config\fR -[\fB--help\fR] -[\fB--version\fR] -[\fB--all\fR] -[\fB--prefix\fR] -[\fB--exec-prefix\fR] -[\fB--bindir\fR] -[\fB--libdir\fR] -[\fB--includedir\fR] -[\fB--mandir\fR] -[\fB--datadir\fR] -[\fB--acdir\fR] -[\fB--cflags\fR] -[\fB--ldflags\fR] -[\fB--libs\fR] +.IX Header "SYNOPSIS" +\&\fBpth-config\fR +[\fB\*(--help\fR] +[\fB\*(--version\fR] +[\fB\*(--all\fR] +[\fB\*(--prefix\fR] +[\fB\*(--exec-prefix\fR] +[\fB\*(--bindir\fR] +[\fB\*(--libdir\fR] +[\fB\*(--includedir\fR] +[\fB\*(--mandir\fR] +[\fB\*(--datadir\fR] +[\fB\*(--acdir\fR] +[\fB\*(--cflags\fR] +[\fB\*(--ldflags\fR] +[\fB\*(--libs\fR] .SH "DESCRIPTION" +.IX Header "DESCRIPTION" The \fBpth-config\fR program is a little helper utility for easy configuring and building applications based on the \fIpth\fR\|(3) library. It can be used to query the C compiler and linker flags which are required to correctly compile and link the application against the \fIpth\fR\|(3) library. .SH "OPTIONS" -\fBpth-config\fR accepts the following options: -.Ip "\fB--help\fR" 4 +.IX Header "OPTIONS" +\&\fBpth-config\fR accepts the following options: +.Ip "\fB\*(--help\fR" 4 +.IX Item "help" Prints the short usage information. -.Ip "\fB--version\fR" 4 +.Ip "\fB\*(--version\fR" 4 +.IX Item "version" Prints the version number and date of the installed \fIpth\fR\|(3) library. -.Ip "\fB--all\fR" 4 +.Ip "\fB\*(--all\fR" 4 +.IX Item "all" Forces the output of all flags, that is, including extra flags which are not -\fBPth\fR specific. -.Ip "\fB--prefix\fR" 4 +\&\fBPth\fR specific. +.Ip "\fB\*(--prefix\fR" 4 +.IX Item "prefix" Prints the installation prefix of architecture independent files -.Ip "\fB--exec-prefix\fR" 4 +.Ip "\fB\*(--exec-prefix\fR" 4 +.IX Item "exec-prefix" Prints the installation prefix of architecture dependent files. -.Ip "\fB--bindir\fR" 4 +.Ip "\fB\*(--bindir\fR" 4 +.IX Item "bindir" Prints the installation directory of binaries. -.Ip "\fB--libdir\fR" 4 +.Ip "\fB\*(--libdir\fR" 4 +.IX Item "libdir" Prints the installation directory of libraries. -.Ip "\fB--includedir\fR" 4 +.Ip "\fB\*(--includedir\fR" 4 +.IX Item "includedir" Prints the installation directory of include headers. -.Ip "\fB--mandir\fR" 4 +.Ip "\fB\*(--mandir\fR" 4 +.IX Item "mandir" Prints the installation directory of manual pages. -.Ip "\fB--datadir\fR" 4 +.Ip "\fB\*(--datadir\fR" 4 +.IX Item "datadir" Prints the installation directory of shared data. -.Ip "\fB--acdir\fR" 4 +.Ip "\fB\*(--acdir\fR" 4 +.IX Item "acdir" Prints the installation directory of \fBautoconf\fR data. -.Ip "\fB--cflags\fR" 4 +.Ip "\fB\*(--cflags\fR" 4 +.IX Item "cflags" Prints the C compiler flags which are needed to compile the \fIpth\fR\|(3)\-based -application. The output is usually added to the \f(CWCFLAGS\fR variable of the -applications \f(CWMakefile\fR. -.Ip "\fB--ldflags\fR" 4 -Prints the linker flags (\f(CW-L\fR) which are needed to link the application with -the \fIpth\fR\|(3) library. The output is usually added to the \f(CWLDFLAGS\fR variable of -the applications \f(CWMakefile\fR. -.Ip "\fB--libs\fR" 4 -Prints the library flags (\f(CW-l\fR) which are needed to link the application with -the \fIpth\fR\|(3) library. The output is usually added to the \f(CWLIBS\fR variable of the -applications \f(CWMakefile\fR. +application. The output is usually added to the \f(CW\*(C`CFLAGS\*(C'\fR variable of the +applications \f(CW\*(C`Makefile\*(C'\fR. +.Ip "\fB\*(--ldflags\fR" 4 +.IX Item "ldflags" +Prints the linker flags (\f(CW\*(C`\-L\*(C'\fR) which are needed to link the application with +the \fIpth\fR\|(3) library. The output is usually added to the \f(CW\*(C`LDFLAGS\*(C'\fR variable of +the applications \f(CW\*(C`Makefile\*(C'\fR. +.Ip "\fB\*(--libs\fR" 4 +.IX Item "libs" +Prints the library flags (\f(CW\*(C`\-l\*(C'\fR) which are needed to link the application with +the \fIpth\fR\|(3) library. The output is usually added to the \f(CW\*(C`LIBS\*(C'\fR variable of the +applications \f(CW\*(C`Makefile\*(C'\fR. .SH "EXAMPLE" -.PP +.IX Header "EXAMPLE" .Vb 4 \& CC = cc \& CFLAGS = -O `pth-config --cflags` @@ -268,60 +236,12 @@ \& $(CC) $(CFLAGS) -c foo.c .Ve .SH "SEE ALSO" -\fIpth\fR\|(3), \fIcc\fR\|(1). +.IX Header "SEE ALSO" +\&\fIpth\fR\|(3), \fIcc\fR\|(1). .SH "AUTHOR" -.PP +.IX Header "AUTHOR" .Vb 3 \& Ralf S. Engelschall \& rse@engelschall.com \& www.engelschall.com .Ve - -.rn }` '' -.IX Title "PTH-CONFIG 1" -.IX Name "B - Pth library build utility" - -.IX Header "NAME" - -.IX Header "VERSION" - -.IX Header "SYNOPSIS" - -.IX Header "DESCRIPTION" - -.IX Header "OPTIONS" - -.IX Item "\fB--help\fR" - -.IX Item "\fB--version\fR" - -.IX Item "\fB--all\fR" - -.IX Item "\fB--prefix\fR" - -.IX Item "\fB--exec-prefix\fR" - -.IX Item "\fB--bindir\fR" - -.IX Item "\fB--libdir\fR" - -.IX Item "\fB--includedir\fR" - -.IX Item "\fB--mandir\fR" - -.IX Item "\fB--datadir\fR" - -.IX Item "\fB--acdir\fR" - -.IX Item "\fB--cflags\fR" - -.IX Item "\fB--ldflags\fR" - -.IX Item "\fB--libs\fR" - -.IX Header "EXAMPLE" - -.IX Header "SEE ALSO" - -.IX Header "AUTHOR" - Index: ossp-pkg/pth/pth.3 RCS File: /v/ossp/cvs/ossp-pkg/pth/Attic/pth.3,v rcsdiff -q -kk '-r1.223' '-r1.224' -u '/v/ossp/cvs/ossp-pkg/pth/Attic/pth.3,v' 2>/dev/null --- pth.3 2000/08/18 08:47:51 1.223 +++ pth.3 2000/09/30 08:00:18 1.224 @@ -1,12 +1,9 @@ -.rn '' }` -''' $RCSfile$$Revision$$Date$ -''' -''' $Log$ -''' Revision 1.223 2000/08/18 08:47:51 rse -''' *** empty log message *** -''' -''' -.de Sh +.\" Automatically generated by Pod::Man version 1.02 +.\" Sat Sep 30 09:59:07 2000 +.\" +.\" Standard preamble: +.\" ====================================================================== +.de Sh \" Subsection heading .br .if t .Sp .ne 5 @@ -14,150 +11,106 @@ \fB\\$1\fR .PP .. -.de Sp +.de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. -.de Ip +.de Ip \" List item .br .ie \\n(.$>=3 .ne \\$3 .el .ne 3 .IP "\\$1" \\$2 .. -.de Vb +.de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. -.de Ve +.de Ve \" End verbatim text .ft R .fi .. -''' -''' -''' Set up \*(-- to give an unbreakable dash; -''' string Tr holds user defined translation string. -''' Bell System Logo is used as a dummy character. -''' +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. | will give a +.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used +.\" to do unbreakable dashes and therefore won't be available. \*(C` and +.\" \*(C' expand to `' in nroff, nothing in troff, for use with C<> .tr \(*W-|\(bv\*(Tr +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ -.ds -- \(*W- -.ds PI pi -.if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch -.if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch -.ds L" "" -.ds R" "" -''' \*(M", \*(S", \*(N" and \*(T" are the equivalent of -''' \*(L" and \*(R", except that they are used on ".xx" lines, -''' such as .IP and .SH, which do another additional levels of -''' double-quote interpretation -.ds M" """ -.ds S" """ -.ds N" """"" -.ds T" """"" -.ds L' ' -.ds R' ' -.ds M' ' -.ds S' ' -.ds N' ' -.ds T' ' +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` ` +. ds C' ' 'br\} .el\{\ -.ds -- \(em\| -.tr \*(Tr -.ds L" `` -.ds R" '' -.ds M" `` -.ds S" '' -.ds N" `` -.ds T" '' -.ds L' ` -.ds R' ' -.ds M' ` -.ds S' ' -.ds N' ` -.ds T' ' -.ds PI \(*p +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' 'br\} -.\" If the F register is turned on, we'll generate -.\" index entries out stderr for the following things: -.\" TH Title -.\" SH Header -.\" Sh Subsection -.\" Ip Item -.\" X<> Xref (embedded -.\" Of course, you have to process the output yourself -.\" in some meaninful fashion. -.if \nF \{ -.de IX -.tm Index:\\$1\t\\n%\t"\\$2" -.. -.nr % 0 -.rr F +.\" +.\" If the F register is turned on, we'll generate index entries on stderr +.\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and +.\" index entries marked with X<> in POD. Of course, you'll have to process +.\" the output yourself in some meaningful fashion. +.if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +. . +. nr % 0 +. rr F .\} -.TH pth 3 "18-Aug-2000" "GNU Pth 1.4a3" "GNU Portable Threads" -.UC -.if n .hy 0 +.\" +.\" For nroff, turn off justification. Always turn off hyphenation; it +.\" makes way too many mistakes in technical documents. +.hy 0 .if n .na -.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' -.de CQ \" put $1 in typewriter font -.ft CW -'if n "\c -'if t \\&\\$1\c -'if n \\&\\$1\c -'if n \&" -\\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7 -'.ft R -.. -.\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2 -. \" AM - accent mark definitions +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. .bd B 3 -. \" fudge factors for nroff and troff +. \" fudge factors for nroff and troff .if n \{\ -. ds #H 0 -. ds #V .8m -. ds #F .3m -. ds #[ \f1 -. ds #] \fP +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP .\} .if t \{\ -. ds #H ((1u-(\\\\n(.fu%2u))*.13m) -. ds #V .6m -. ds #F 0 -. ds #[ \& -. ds #] \& +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& .\} -. \" simple accents for nroff and troff +. \" simple accents for nroff and troff .if n \{\ -. ds ' \& -. ds ` \& -. ds ^ \& -. ds , \& -. ds ~ ~ -. ds ? ? -. ds ! ! -. ds / -. ds q +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / .\} .if t \{\ -. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" -. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' -. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' -. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' -. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' -. ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10' -. ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m' -. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' -. ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10' +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} -. \" troff and (daisy-wheel) nroff accents +. \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' -.ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#] -.ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u' -.ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u' -.ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#] .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' @@ -165,42 +118,43 @@ .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E -.ds oe o\h'-(\w'o'u*4/10)'e -.ds Oe O\h'-(\w'O'u*4/10)'E -. \" corrections for vroff +. \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' -. \" for low resolution devices (crt and lpr) +. \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ -. ds : e -. ds 8 ss -. ds v \h'-1'\o'\(aa\(ga' -. ds _ \h'-1'^ -. ds . \h'-1'. -. ds 3 3 -. ds o a -. ds d- d\h'-1'\(ga -. ds D- D\h'-1'\(hy -. ds th \o'bp' -. ds Th \o'LP' -. ds ae ae -. ds Ae AE -. ds oe oe -. ds Oe OE +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE .\} .rm #[ #] #H #V #F C +.\" ====================================================================== +.\" +.IX Title "pth 3" +.TH pth 3 "18-Aug-2000" "GNU Pth 1.4a3" "GNU Portable Threads" +.UC .SH "NAME" -\fBpth\fR \- GNU Portable Threads +\&\fBpth\fR \- \s-1GNU\s0 Portable Threads .SH "VERSION" -GNU Pth 1.4a3 (18-Aug-2000) +.IX Header "VERSION" +\&\s-1GNU\s0 Pth \s-11.4a3 (18-Aug-2000)\s0 .SH "SYNOPSIS" +.IX Header "SYNOPSIS" .Ip "\fBGlobal Library Management\fR" 4 +.IX Item "Global Library Management" pth_init, pth_kill, pth_ctrl, pth_version. .Ip "\fBThread Attribute Handling\fR" 4 +.IX Item "Thread Attribute Handling" pth_attr_of, pth_attr_new, pth_attr_init, @@ -208,6 +162,7 @@ pth_attr_get, pth_attr_destroy. .Ip "\fBThread Control\fR" 4 +.IX Item "Thread Control" pth_spawn, pth_once, pth_self, @@ -222,14 +177,17 @@ pth_join, pth_exit. .Ip "\fBUtilities\fR" 4 +.IX Item "Utilities" pth_fdmode, pth_time, pth_timeout, pth_sfiodisc. .Ip "\fBCancellation Management\fR" 4 +.IX Item "Cancellation Management" pth_cancel_point, pth_cancel_state. .Ip "\fBEvent Handling\fR" 4 +.IX Item "Event Handling" pth_event, pth_event_typeof, pth_event_extract, @@ -239,11 +197,13 @@ pth_event_occurred, pth_event_free. .Ip "\fBKey-Based Storage\fR" 4 +.IX Item "Key-Based Storage" pth_key_create, pth_key_delete, pth_key_setdata, pth_key_getdata. .Ip "\fBMessage Port Communication\fR" 4 +.IX Item "Message Port Communication" pth_msgport_create, pth_msgport_destroy, pth_msgport_find, @@ -252,13 +212,16 @@ pth_msgport_get, pth_msgport_reply. .Ip "\fBThread Cleanups\fR" 4 +.IX Item "Thread Cleanups" pth_cleanup_push, pth_cleanup_pop. .Ip "\fBProcess Forking\fR" 4 +.IX Item "Process Forking" pth_atfork_push, pth_atfork_pop, pth_fork. .Ip "\fBSynchronization\fR" 4 +.IX Item "Synchronization" pth_mutex_init, pth_mutex_acquire, pth_mutex_release, @@ -271,6 +234,7 @@ pth_barrier_init, pth_barrier_reach. .Ip "\fBGeneralized \s-1POSIX\s0 Replacement \s-1API\s0\fR" 4 +.IX Item "Generalized POSIX Replacement API" pth_sigwait_ev, pth_accept_ev, pth_connect_ev, @@ -285,6 +249,7 @@ pth_send_ev, pth_sendto_ev. .Ip "\fBStandard \s-1POSIX\s0 Replacement \s-1API\s0\fR" 4 +.IX Item "Standard POSIX Replacement API" pth_usleep, pth_sleep, pth_waitpid, @@ -305,7 +270,7 @@ pth_send, pth_sendto. .SH "DESCRIPTION" -.PP +.IX Header "DESCRIPTION" .Vb 5 \& ____ _ _ \& | _ \e| |_| |__ @@ -313,11 +278,11 @@ \& | __/| |_| | | | the absurd can achieve \& |_| \e__|_| |_| the impossible.'' .Ve -\fBPth\fR is a very portable POSIX/ANSI\-C based library for Unix platforms which +\&\fBPth\fR is a very portable \s-1POSIX/ANSI-C\s0 based library for Unix platforms which provides non-preemptive priority-based scheduling for multiple threads of execution (aka `multithreading') inside event-driven applications. All threads run in the same address space of the application process, but each thread has -its own individual program counter, run-time stack, signal mask and \f(CWerrno\fR +its own individual program counter, run-time stack, signal mask and \f(CW\*(C`errno\*(C'\fR variable. .PP The thread scheduling itself is done in a cooperative way, i.e., the threads @@ -329,15 +294,16 @@ elapsed timers, pending I/O on message ports, thread and process termination, and even results of customized callback functions. .PP -\fBPth\fR also provides an optional emulation API for POSIX.1c threads +\&\fBPth\fR also provides an optional emulation \s-1API\s0 for \s-1POSIX\s0.1c threads (`Pthreads') which can be used for backward compatibility to existing multithreaded applications. See \fBPth\fR's \fIpthread\fR\|(3) manual page for details. .Sh "Threading Background" +.IX Subsection "Threading Background" When programming event-driven applications, usually servers, lots of regular jobs and one-shot requests have to be processed in parallel. To efficiently simulate this parallel processing on uniprocessor -machines, we use `multitasking\*(R' -- that is, we have the application +machines, we use `multitasking' \*(-- that is, we have the application ask the operating system to spawn multiple instances of itself. On Unix, typically the kernel implements multitasking in a preemptive and priority-based way through heavy-weight processes spawned with \fIfork\fR\|(2). @@ -372,12 +338,14 @@ at least event-driven server applications usually benefit greatly from using threads. .Sh "The World of Threading" +.IX Subsection "The World of Threading" Even though lots of documents exists which describe and define the world of threading, to understand \fBPth\fR, you need only basic knowledge about threading. The following definitions of thread-related terms should at least help you understand thread programming enough to allow you to use -\fBPth\fR. +\&\fBPth\fR. .Ip "\fBo\fR \fBprocess\fR vs. \fBthread\fR" 2 +.IX Item "o process vs. thread" A process on Unix systems consists of at least the following fundamental ingredients: \fIvirtual memory table\fR, \fIprogram code\fR, \fIprogram counter\fR, \fIheap memory\fR, \fIstack memory\fR, \fIstack pointer\fR, \fIfile @@ -388,6 +356,7 @@ particular the virtual memory, it shares with the other threads of the same process. .Ip "\fBo\fR \fBkernel-space\fR vs. \fBuser-space\fR threading" 2 +.IX Item "o kernel-space vs. user-space threading" Threads on a Unix platform traditionally can be implemented either inside kernel-space or user-space. When threads are implemented by the kernel, the thread context switches are performed by the kernel without @@ -400,33 +369,36 @@ .Sp User-space threads are usually more portable and can perform faster and cheaper context switches (for instance via \fIswapcontext\fR\|(2) or -\fIsetjmp\fR\|(3)/\fIlongjmp\fR\|(3)) than kernel based threads. On the other hand, +\&\fIsetjmp\fR\|(3)/\fIlongjmp\fR\|(3)) than kernel based threads. On the other hand, kernel-space threads can take advantage of multiprocessor machines and don't have any inherent I/O blocking problems. Kernel-space threads are usually scheduled in preemptive way side-by-side with the underlying processes. User-space threads on the other hand use either preemptive or non-preemptive scheduling. .Ip "\fBo\fR \fBpreemptive\fR vs. \fBnon-preemptive\fR thread scheduling" 2 +.IX Item "o preemptive vs. non-preemptive thread scheduling" In preemptive scheduling, the scheduler lets a thread execute until a blocking situation occurs (usually a function call which would block) or the assigned timeslice elapses. Then it detracts control from the thread without a chance for the thread to object. This is usually realized by interrupting the thread through a hardware interrupt signal (for kernel-space threads) or a software interrupt signal (for -user-space threads), like \f(CWSIGALRM\fR or \f(CWSIGVTALRM\fR. In non-preemptive +user-space threads), like \f(CW\*(C`SIGALRM\*(C'\fR or \f(CW\*(C`SIGVTALRM\*(C'\fR. In non-preemptive scheduling, once a thread received control from the scheduler it keeps it until either a blocking situation occurs (again a function call which would block and instead switches back to the scheduler) or the thread explicitly yields control back to the scheduler in a cooperative way. .Ip "\fBo\fR \fBconcurrency\fR vs. \fBparallelism\fR" 2 +.IX Item "o concurrency vs. parallelism" Concurrency exists when at least two threads are \fIin progress\fR at the same time. Parallelism arises when at least two threads are \fIexecuting\fR simultaneously. Real parallelism can be only achieved on multiprocessor machines, of course. But one also usually speaks of parallelism or -\fIhigh concurrency\fR in the context of preemptive thread scheduling +\&\fIhigh concurrency\fR in the context of preemptive thread scheduling and of \fIlow concurrency\fR in the context of non-preemptive thread scheduling. .Ip "\fBo\fR \fBresponsiveness\fR" 2 +.IX Item "o responsiveness" The responsiveness of a system can be described by the user visible delay until the system responses to an external request. When this delay is small enough and the user doesn't recognize a noticeable delay, @@ -434,6 +406,7 @@ recognizes or is even annoyed by the delay, the responsiveness of the system is considered bad. .Ip "\fBo\fR \fBreentrant\fR, \fBthread-safe\fR and \fBasynchronous-safe\fR functions" 2 +.IX Item "o reentrant, thread-safe and asynchronous-safe functions" A reentrant function is one that behaves correctly if it is called simultaneously by several threads and then also executes simultaneously. Functions that access global state, such as memory or files, of course, @@ -466,10 +439,12 @@ be asynchronous-safe. Asynchronous-safe functions usually have to be already reentrant. .Sh "User-Space Threads" +.IX Subsection "User-Space Threads" User-space threads can be implemented in various way. The two traditional approaches are: .Ip "\fB1.\fR" 3 -\fBMatrix-based explicit dispatching between small units of execution:\fR +.IX Item "1." +\&\fBMatrix-based explicit dispatching between small units of execution:\fR .Sp Here the global procedures of the application are split into small execution units (each is required to not run for more than a few @@ -497,7 +472,8 @@ often nasty, because one cannot switch between threads in the middle of a function. Thus the scheduling borders are the function borders. .Ip "\fB2.\fR" 3 -\fBContext-based implicit scheduling between threads of execution:\fR +.IX Item "2." +\&\fBContext-based implicit scheduling between threads of execution:\fR .Sp Here the idea is that one programs the application as with forked processes, i.e., one spawns a thread of execution and this runs from the @@ -521,7 +497,7 @@ scheduling does usually a lot more context switches (every user-space context switch costs some overhead even when it is a lot cheaper than a kernel-level context switch) than the explicit cooperative/non-preemptive scheduling. -Finally, there is no really portable \s-1POSIX/ANSI\s0\-C based way to implement +Finally, there is no really portable \s-1POSIX/ANSI-C\s0 based way to implement user-space preemptive threading. Either the platform already has threads, or one has to hope that some semi-portable package exists for it. And even those semi-portable packages usually have to deal with assembler @@ -533,6 +509,7 @@ but suffers from synchronization and portability problems caused by its preemptive nature. .Sh "The Compromise of Pth" +.IX Subsection "The Compromise of Pth" But why not combine the good aspects of both approaches while avoiding their bad aspects? That's the goal of \fBPth\fR. \fBPth\fR implements easy-to-program threads of execution, but avoids the problems of @@ -543,32 +520,35 @@ working with \fBPth\fR. The following list summarizes a few essential points: .Ip "\fBo\fR" 2 -\fBPth provides maximum portability, but \s-1NOT\s0 the fanciest features\fR. +.IX Item "o" +\&\fBPth provides maximum portability, but \s-1NOT\s0 the fanciest features\fR. .Sp -This is, because it uses a nifty and portable \s-1POSIX/ANSI\s0\-C approach for +This is, because it uses a nifty and portable \s-1POSIX/ANSI-C\s0 approach for thread creation (and this way doesn't require any platform dependent assembler hacks) and schedules the threads in non-preemptive way (which -doesn't require unportable facilities like \f(CWSIGVTALRM\fR). On the other +doesn't require unportable facilities like \f(CW\*(C`SIGVTALRM\*(C'\fR). On the other hand, this way not all fancy threading features can be implemented. Nevertheless the available facilities are enough to provide a robust and full-featured threading system. .Ip "\fBo\fR" 2 -\fBPth increases the responsiveness and concurrency of an event-driven +.IX Item "o" +\&\fBPth increases the responsiveness and concurrency of an event-driven application, but \s-1NOT\s0 the concurrency of number-crunching applications\fR. .Sp The reason is the non-preemptive scheduling. Number-crunching applications usually require preemptive scheduling to achieve concurrency because of their long \s-1CPU\s0 bursts. For them, non-preemptive scheduling (even together with explicit yielding) provides only the old -concept of `coroutines\*(R'. On the other hand, event driven applications +concept of `coroutines'. On the other hand, event driven applications benefit greatly from non-preemptive scheduling. They have only short -\s-1CPU\s0 bursts and lots of events to wait on, and this way run faster under +\&\s-1CPU\s0 bursts and lots of events to wait on, and this way run faster under non-preemptive scheduling because no unnecessary context switching occurs, as it is the case for preemptive scheduling. That's why \fBPth\fR is mainly intended for server type applications, although there is no technical restriction. .Ip "\fBo\fR" 2 -\fBPth requires thread-safe functions, but \s-1NOT\s0 reentrant functions\fR. +.IX Item "o" +\&\fBPth requires thread-safe functions, but \s-1NOT\s0 reentrant functions\fR. .Sp This nice fact exists again because of the nature of non-preemptive scheduling, where a function isn't interrupted and this way cannot be @@ -578,7 +558,8 @@ third-party libraries can be used without side-effects than its the case for other threading systems. .Ip "\fBo\fR" 2 -\fBPth doesn't require any kernel support, but can \s-1NOT\s0 +.IX Item "o" +\&\fBPth doesn't require any kernel support, but can \s-1NOT\s0 benefit from multiprocessor machines\fR. .Sp This means that \fBPth\fR runs on almost all Unix kernels, because the @@ -589,6 +570,7 @@ multiprocessor systems are rare, and portability is almost more important than highest concurrency. .Sh "The life cycle of a thread" +.IX Subsection "The life cycle of a thread" To understand the \fBPth\fR Application Programming Interface (\s-1API\s0), it helps to first understand the life cycle of a thread in the \fBPth\fR threading system. It can be illustrated with the following directed @@ -612,10 +594,10 @@ containing all threads which want to perform a \s-1CPU\s0 burst. There they are queued in priority order. On each dispatching step, the scheduler always removes the thread with the highest priority only. It then increases the -priority of all remaining threads by 1, to prevent them from `starving\*(R'. +priority of all remaining threads by 1, to prevent them from `starving'. .PP The thread which was removed from the \fB\s-1READY\s0\fR queue is the new -\fB\s-1RUNNING\s0\fR thread (there is always just one \fB\s-1RUNNING\s0\fR thread, of +\&\fB\s-1RUNNING\s0\fR thread (there is always just one \fB\s-1RUNNING\s0\fR thread, of course). The \fB\s-1RUNNING\s0\fR thread is assigned execution control. After this thread yields execution (either explicitly by yielding execution or implicitly by calling a function which would block) there are three @@ -625,7 +607,7 @@ bursts and immediately enters the \fB\s-1READY\s0\fR queue again. .PP Before the next thread is taken out of the \fB\s-1READY\s0\fR queue, the -\fB\s-1WAITING\s0\fR queue is checked for pending events. If one or more events +\&\fB\s-1WAITING\s0\fR queue is checked for pending events. If one or more events occurred, the threads that are waiting on them are immediately moved to the \fB\s-1READY\s0\fR queue. .PP @@ -639,7 +621,7 @@ The purpose of the \fB\s-1DEAD\s0\fR queue is to support thread joining. When a thread is marked to be unjoinable, it is directly kicked out of the system after it terminated. But when it is joinable, it enters the -\fB\s-1DEAD\s0\fR queue. There it remains until another thread joins it. +\&\fB\s-1DEAD\s0\fR queue. There it remains until another thread joins it. .PP Finally, there is a special separated queue named \fB\s-1SUSPENDED\s0\fR, to where threads can be manually moved from the \fB\s-1NEW\s0\fR, \fB\s-1READY\s0\fR or \fB\s-1WAITING\s0\fR @@ -651,60 +633,68 @@ from where it originally came and this way again enters the schedulers scope. .SH "APPLICATION PROGRAMMING INTERFACE (API)" -In the following the \fBPth\fR \fIApplication Programming Interface\fR (API) +.IX Header "APPLICATION PROGRAMMING INTERFACE (API)" +In the following the \fBPth\fR \fIApplication Programming Interface\fR (\s-1API\s0) is discussed in detail. With the knowledge given above, it should be -now easy to understand how to program threads with this API. In good -Unix tradition, \fBPth\fR functions use special return values (\f(CWNULL\fR -in pointer context, \f(CWFALSE\fR in boolean context and \f(CW-1\fR in integer +now easy to understand how to program threads with this \s-1API\s0. In good +Unix tradition, \fBPth\fR functions use special return values (\f(CW\*(C`NULL\*(C'\fR +in pointer context, \f(CW\*(C`FALSE\*(C'\fR in boolean context and \f(CW\*(C`\-1\*(C'\fR in integer context) to indicate an error condition and set (or pass through) the -\f(CWerrno\fR system variable to pass more details about the error to the +\&\f(CW\*(C`errno\*(C'\fR system variable to pass more details about the error to the caller. .Sh "Global Library Management" +.IX Subsection "Global Library Management" The following functions act on the library as a whole. They are used to initialize and shutdown the scheduler and fetch information from it. .Ip "int \fBpth_init\fR(void);" 4 +.IX Item "int pth_init(void);" This initializes the \fBPth\fR library. It has to be the first \fBPth\fR \s-1API\s0 function call in an application, and is mandatory. It's usually done at the begin of the \fImain()\fR function of the application. This implicitly spawns the internal scheduler thread and transforms the single execution -unit of the current process into a thread (the `main\*(R' thread). It -returns \f(CWTRUE\fR on success and \f(CWFALSE\fR on error. +unit of the current process into a thread (the `main' thread). It +returns \f(CW\*(C`TRUE\*(C'\fR on success and \f(CW\*(C`FALSE\*(C'\fR on error. .Ip "int \fBpth_kill\fR(void);" 4 +.IX Item "int pth_kill(void);" This kills the \fBPth\fR library. It should be the last \fBPth\fR \s-1API\s0 function call in an application, but is not really required. It's usually done at the end of the main function of the application. At least, it has to be called from within the main thread. It implicitly kills all threads and transforms back the calling thread into the single execution unit of the underlying process. The usual way to terminate a \fBPth\fR application is either a simple -`\f(CWpth_exit(0);\fR\*(R' in the main thread (which waits for all other threads to +`\f(CW\*(C`pth_exit(0);\*(C'\fR' in the main thread (which waits for all other threads to terminate, kills the threading system and then terminates the process) or a -`\f(CWpth_kill(); exit(0)\fR\*(R' (which immediately kills the threading system and +`\f(CW\*(C`pth_kill(); exit(0)\*(C'\fR' (which immediately kills the threading system and terminates the process). The \fIpth_kill()\fR return immediately with a return -code of \f(CWFALSE\fR if it is called not from within the main thread. Else -kills the threading system and returns \f(CWTRUE\fR. +code of \f(CW\*(C`FALSE\*(C'\fR if it is called not from within the main thread. Else +kills the threading system and returns \f(CW\*(C`TRUE\*(C'\fR. .Ip "long \fBpth_ctrl\fR(unsigned long \fIquery\fR, ...);" 4 +.IX Item "long pth_ctrl(unsigned long query, ...);" This is a generalized query/control function for the \fBPth\fR library. The -argument \fIquery\fR is a bitmask formed out of one or more \f(CWPTH_CTRL_\fR\fI\s-1XXXX\s0\fR +argument \fIquery\fR is a bitmask formed out of one or more \f(CW\*(C`PTH_CTRL_\*(C'\fR\fI\s-1XXXX\s0\fR queries. Currently the following queries are supported: -.Ip "\f(CWPTH_CTRL_GETTHREADS\fR" 8 +.RS 4 +.Ip "\f(CW\*(C`PTH_CTRL_GETTHREADS\*(C'\fR" 4 +.IX Item "PTH_CTRL_GETTHREADS" This returns the total number of threads currently in existence. This query actually is formed out of the combination of queries for threads in a -particular state, i.e., the \f(CWPTH_CTRL_GETTHREADS\fR query is equal to the -\s-1OR\s0\-combination of all the following specialized queries: +particular state, i.e., the \f(CW\*(C`PTH_CTRL_GETTHREADS\*(C'\fR query is equal to the +OR-combination of all the following specialized queries: .Sp -\f(CWPTH_CTRL_GETTHREADS_NEW\fR for the number of threads in the +\&\f(CW\*(C`PTH_CTRL_GETTHREADS_NEW\*(C'\fR for the number of threads in the new queue (threads created via \fIpth_spawn\fR\|(3) but still not -scheduled once), \f(CWPTH_CTRL_GETTHREADS_READY\fR for the number of +scheduled once), \f(CW\*(C`PTH_CTRL_GETTHREADS_READY\*(C'\fR for the number of threads in the ready queue (threads who want to do \s-1CPU\s0 bursts), -\f(CWPTH_CTRL_GETTHREADS_RUNNING\fR for the number of running threads -(always just one thread!), \f(CWPTH_CTRL_GETTHREADS_WAITING\fR for +\&\f(CW\*(C`PTH_CTRL_GETTHREADS_RUNNING\*(C'\fR for the number of running threads +(always just one thread!), \f(CW\*(C`PTH_CTRL_GETTHREADS_WAITING\*(C'\fR for the number of threads in the waiting queue (threads waiting for -events), \f(CWPTH_CTRL_GETTHREADS_SUSPENDED\fR for the number of +events), \f(CW\*(C`PTH_CTRL_GETTHREADS_SUSPENDED\*(C'\fR for the number of threads in the suspended queue (threads waiting to be resumed) and -\f(CWPTH_CTRL_GETTHREADS_DEAD\fR for the number of threads in the new queue +\&\f(CW\*(C`PTH_CTRL_GETTHREADS_DEAD\*(C'\fR for the number of threads in the new queue (terminated threads waiting for a join). -.Ip "\f(CWPTH_CTRL_GETAVLOAD\fR" 8 -This requires a second argument of type `\f(CWfloat *\fR\*(R' (pointer to a floating +.Ip "\f(CW\*(C`PTH_CTRL_GETAVLOAD\*(C'\fR" 4 +.IX Item "PTH_CTRL_GETAVLOAD" +This requires a second argument of type `\f(CW\*(C`float *\*(C'\fR' (pointer to a floating point variable). It stores a floating point value describing the exponential averaged load of the scheduler in this variable. The load is a function from the number of threads in the ready queue of the schedulers dispatching unit. @@ -712,96 +702,122 @@ situation when the application has no high load). A higher load value means there a more threads ready who want to do \s-1CPU\s0 bursts. The average load value updates once per second only. The return value for this query is always 0. -.Ip "\f(CWPTH_CTRL_GETPRIO\fR" 8 -This requires a second argument of type `\f(CWpth_t\fR\*(R' which identifies a -thread. It returns the priority (ranging from \f(CWPTH_PRIO_MIN\fR to -\f(CWPTH_PRIO_MAX\fR) of the given thread. -.Ip "\f(CWPTH_CTRL_GETNAME\fR" 8 -This requires a second argument of type `\f(CWpth_t\fR\*(R' which identifies a +.Ip "\f(CW\*(C`PTH_CTRL_GETPRIO\*(C'\fR" 4 +.IX Item "PTH_CTRL_GETPRIO" +This requires a second argument of type `\f(CW\*(C`pth_t\*(C'\fR' which identifies a +thread. It returns the priority (ranging from \f(CW\*(C`PTH_PRIO_MIN\*(C'\fR to +\&\f(CW\*(C`PTH_PRIO_MAX\*(C'\fR) of the given thread. +.Ip "\f(CW\*(C`PTH_CTRL_GETNAME\*(C'\fR" 4 +.IX Item "PTH_CTRL_GETNAME" +This requires a second argument of type `\f(CW\*(C`pth_t\*(C'\fR' which identifies a thread. It returns the name of the given thread, i.e., the return value of -\fIpth_ctrl\fR\|(3) should be casted to a `\f(CWchar *\fR\*(R'. -.Ip "\f(CWPTH_CTRL_DUMPSTATE\fR" 8 -This requires a second argument of type `\f(CWFILE *\fR\*(R' to which a summary +\&\fIpth_ctrl\fR\|(3) should be casted to a `\f(CW\*(C`char *\*(C'\fR'. +.Ip "\f(CW\*(C`PTH_CTRL_DUMPSTATE\*(C'\fR" 4 +.IX Item "PTH_CTRL_DUMPSTATE" +This requires a second argument of type `\f(CW\*(C`FILE *\*(C'\fR' to which a summary of the internal \fBPth\fR library state is written to. The main information which is currently written out is the current state of the thread pool. +.RE +.RS 4 .Sp -The function returns \f(CW-1\fR on error. +The function returns \f(CW\*(C`\-1\*(C'\fR on error. +.RE .Ip "long \fBpth_version\fR(void);" 4 -This function returns a hex-value `0x\fIV\fR\fI\s-1RR\s0\fR\fIT\fR\fI\s-1LL\s0\fR\*(R' which describes the +.IX Item "long pth_version(void);" +This function returns a hex-value `0x\fIV\fR\fI\s-1RR\s0\fR\fIT\fR\fI\s-1LL\s0\fR' which describes the current \fBPth\fR library version. \fIV\fR is the version, \fI\s-1RR\s0\fR the revisions, -\fI\s-1LL\s0\fR the level and \fIT\fR the type of the level (alphalevel=0, betalevel=1, +\&\fI\s-1LL\s0\fR the level and \fIT\fR the type of the level (alphalevel=0, betalevel=1, patchlevel=2, etc). For instance \fBPth\fR version 1.0b1 is encoded as 0x100101. The reason for this unusual mapping is that this way the version number is steadily \fIincreasing\fR. The same value is also available under compile time as -\f(CWPTH_VERSION\fR. +\&\f(CW\*(C`PTH_VERSION\*(C'\fR. .Sh "Thread Attribute Handling" +.IX Subsection "Thread Attribute Handling" Attribute objects are used in \fBPth\fR for two things: First stand-alone/unbound attribute objects are used to store attributes for to be spawned threads. Bounded attribute objects are used to modify attributes of already existing threads. The following attribute fields exists in attribute objects: -.Ip "\f(CWPTH_ATTR_PRIO\fR (read-write) [\f(CWint\fR]" 4 -Thread Priority between \f(CWPTH_PRIO_MIN\fR and \f(CWPTH_PRIO_MAX\fR. -The default is \f(CWPTH_PRIO_STD\fR. -.Ip "\f(CWPTH_ATTR_NAME\fR (read-write) [\f(CWchar *\fR]" 4 +.Ip "\f(CW\*(C`PTH_ATTR_PRIO\*(C'\fR (read-write) [\f(CW\*(C`int\*(C'\fR]" 4 +.IX Item "PTH_ATTR_PRIO (read-write) [int]" +Thread Priority between \f(CW\*(C`PTH_PRIO_MIN\*(C'\fR and \f(CW\*(C`PTH_PRIO_MAX\*(C'\fR. +The default is \f(CW\*(C`PTH_PRIO_STD\*(C'\fR. +.Ip "\f(CW\*(C`PTH_ATTR_NAME\*(C'\fR (read-write) [\f(CW\*(C`char *\*(C'\fR]" 4 +.IX Item "PTH_ATTR_NAME (read-write) [char *]" Name of thread (up to 40 characters are stored only), mainly for debugging purposes. -.Ip "\f(CWPTH_ATTR_JOINABLE\fR (read-write> [\f(CWint\fR]" 4 -The thread detachment type, \f(CWTRUE\fR indicates a joinable thread, \f(CWFALSE\fR +.Ip "\f(CW\*(C`PTH_ATTR_JOINABLE\*(C'\fR (read-write> [\f(CW\*(C`int\*(C'\fR]" 4 +.IX Item "PTH_ATTR_JOINABLE (read-write> [int]" +The thread detachment type, \f(CW\*(C`TRUE\*(C'\fR indicates a joinable thread, \f(CW\*(C`FALSE\*(C'\fR indicates a detached thread. When a the is detached after termination it is immediately kicked out of the system instead of inserted into the dead queue. -.Ip "\f(CWPTH_ATTR_CANCEL_STATE\fR (read-write) [\f(CWunsigned int\fR]" 4 -The thread cancellation state, i.e., a combination of \f(CWPTH_CANCEL_ENABLE\fR or -\f(CWPTH_CANCEL_DISABLE\fR and \f(CWPTH_CANCEL_DEFERRED\fR or -\f(CWPTH_CANCEL_ASYNCHRONOUS\fR. -.Ip "\f(CWPTH_ATTR_STACK_SIZE\fR (read-write) [\f(CWunsigned int\fR]" 4 +.Ip "\f(CW\*(C`PTH_ATTR_CANCEL_STATE\*(C'\fR (read-write) [\f(CW\*(C`unsigned int\*(C'\fR]" 4 +.IX Item "PTH_ATTR_CANCEL_STATE (read-write) [unsigned int]" +The thread cancellation state, i.e., a combination of \f(CW\*(C`PTH_CANCEL_ENABLE\*(C'\fR or +\&\f(CW\*(C`PTH_CANCEL_DISABLE\*(C'\fR and \f(CW\*(C`PTH_CANCEL_DEFERRED\*(C'\fR or +\&\f(CW\*(C`PTH_CANCEL_ASYNCHRONOUS\*(C'\fR. +.Ip "\f(CW\*(C`PTH_ATTR_STACK_SIZE\*(C'\fR (read-write) [\f(CW\*(C`unsigned int\*(C'\fR]" 4 +.IX Item "PTH_ATTR_STACK_SIZE (read-write) [unsigned int]" The thread stack size in bytes. Use lower values than 64 \s-1KB\s0 with great care! -.Ip "\f(CWPTH_ATTR_STACK_ADDR\fR (read-write) [\f(CWchar *\fR]" 4 +.Ip "\f(CW\*(C`PTH_ATTR_STACK_ADDR\*(C'\fR (read-write) [\f(CW\*(C`char *\*(C'\fR]" 4 +.IX Item "PTH_ATTR_STACK_ADDR (read-write) [char *]" A pointer to the lower address of a chunk of \fImalloc\fR\|(3)'ed memory for the stack. -.Ip "\f(CWPTH_ATTR_TIME_SPAWN\fR (read-only) [\f(CWpth_time_t\fR]" 4 +.Ip "\f(CW\*(C`PTH_ATTR_TIME_SPAWN\*(C'\fR (read-only) [\f(CW\*(C`pth_time_t\*(C'\fR]" 4 +.IX Item "PTH_ATTR_TIME_SPAWN (read-only) [pth_time_t]" The time when the thread was spawned. This can be queried only when the attribute object is bound to a thread. -.Ip "\f(CWPTH_ATTR_TIME_LAST\fR (read-only) [\f(CWpth_time_t\fR]" 4 +.Ip "\f(CW\*(C`PTH_ATTR_TIME_LAST\*(C'\fR (read-only) [\f(CW\*(C`pth_time_t\*(C'\fR]" 4 +.IX Item "PTH_ATTR_TIME_LAST (read-only) [pth_time_t]" The time when the thread was last dispatched. This can be queried only when the attribute object is bound to a thread. -.Ip "\f(CWPTH_ATTR_TIME_RAN\fR (read-only) [\f(CWpth_time_t\fR]" 4 +.Ip "\f(CW\*(C`PTH_ATTR_TIME_RAN\*(C'\fR (read-only) [\f(CW\*(C`pth_time_t\*(C'\fR]" 4 +.IX Item "PTH_ATTR_TIME_RAN (read-only) [pth_time_t]" The total time the thread was running. This can be queried only when the attribute object is bound to a thread. -.Ip "\f(CWPTH_ATTR_START_FUNC\fR (read-only) [\f(CWvoid *(*)(void *)\fR]" 4 +.Ip "\f(CW\*(C`PTH_ATTR_START_FUNC\*(C'\fR (read-only) [\f(CW\*(C`void *(*)(void *)\*(C'\fR]" 4 +.IX Item "PTH_ATTR_START_FUNC (read-only) [void *(*)(void *)]" The thread start function. This can be queried only when the attribute object is bound to a thread. -.Ip "\f(CWPTH_ATTR_START_ARG\fR (read-only) [\f(CWvoid *\fR]" 4 +.Ip "\f(CW\*(C`PTH_ATTR_START_ARG\*(C'\fR (read-only) [\f(CW\*(C`void *\*(C'\fR]" 4 +.IX Item "PTH_ATTR_START_ARG (read-only) [void *]" The thread start argument. This can be queried only when the attribute object is bound to a thread. -.Ip "\f(CWPTH_ATTR_STATE\fR (read-only) [\f(CWpth_state_t\fR]" 4 -The scheduling state of the thread, i.e., either \f(CWPTH_STATE_NEW\fR, -\f(CWPTH_STATE_READY\fR, \f(CWPTH_STATE_WAITING\fR, or \f(CWPTH_STATE_DEAD\fR +.Ip "\f(CW\*(C`PTH_ATTR_STATE\*(C'\fR (read-only) [\f(CW\*(C`pth_state_t\*(C'\fR]" 4 +.IX Item "PTH_ATTR_STATE (read-only) [pth_state_t]" +The scheduling state of the thread, i.e., either \f(CW\*(C`PTH_STATE_NEW\*(C'\fR, +\&\f(CW\*(C`PTH_STATE_READY\*(C'\fR, \f(CW\*(C`PTH_STATE_WAITING\*(C'\fR, or \f(CW\*(C`PTH_STATE_DEAD\*(C'\fR This can be queried only when the attribute object is bound to a thread. -.Ip "\f(CWPTH_ATTR_EVENTS\fR (read-only) [\f(CWpth_event_t\fR]" 4 +.Ip "\f(CW\*(C`PTH_ATTR_EVENTS\*(C'\fR (read-only) [\f(CW\*(C`pth_event_t\*(C'\fR]" 4 +.IX Item "PTH_ATTR_EVENTS (read-only) [pth_event_t]" The event ring the thread is waiting for. This can be queried only when the attribute object is bound to a thread. -.Ip "\f(CWPTH_ATTR_BOUND\fR (read-only) [\f(CWint\fR]" 4 -Whether the attribute object is bound (\f(CWTRUE\fR) to a thread or not (\f(CWFALSE\fR). +.Ip "\f(CW\*(C`PTH_ATTR_BOUND\*(C'\fR (read-only) [\f(CW\*(C`int\*(C'\fR]" 4 +.IX Item "PTH_ATTR_BOUND (read-only) [int]" +Whether the attribute object is bound (\f(CW\*(C`TRUE\*(C'\fR) to a thread or not (\f(CW\*(C`FALSE\*(C'\fR). .PP The following \s-1API\s0 functions exists to handle the attribute objects: .Ip "pth_attr_t \fBpth_attr_of\fR(pth_t \fItid\fR);" 4 +.IX Item "pth_attr_t pth_attr_of(pth_t tid);" This returns a new attribute object \fIbound\fR to thread \fItid\fR. Any queries on this object directly fetch attributes from \fItid\fR. And attribute modifications directly change \fItid\fR. Use such attribute objects to modify existing threads. .Ip "pth_attr_t \fBpth_attr_new\fR(void);" 4 +.IX Item "pth_attr_t pth_attr_new(void);" This returns a new \fIunbound\fR attribute object. An implicit \fIpth_attr_init()\fR is done on it. Any queries on this object just fetch stored attributes from it. And attribute modifications just change the stored attributes. Use such attribute objects to pre-configure attributes for to be spawned threads. .Ip "int \fBpth_attr_init\fR(pth_attr_t \fIattr\fR);" 4 +.IX Item "int pth_attr_init(pth_attr_t attr);" This initializes an attribute object \fIattr\fR to the default values: -\f(CWPTH_ATTR_PRIO\fR := \f(CWPTH_PRIO_STD\fR, \f(CWPTH_ATTR_NAME\fR := `\f(CWunknown\fR\*(R', -\f(CWPTH_ATTR_JOINABLE\fR := \f(CWTRUE\fR, \f(CWPTH_ATTR_CANCELSTATE\fR := -\f(CWPTH_CANCEL_DEFAULT\fR, \f(CWPTH_ATTR_STACK_SIZE\fR := 64*1024 and -\f(CWPTH_ATTR_STACK_ADDR\fR := \f(CWNULL\fR. All other \f(CWPTH_ATTR_*\fR attributes are +\&\f(CW\*(C`PTH_ATTR_PRIO\*(C'\fR := \f(CW\*(C`PTH_PRIO_STD\*(C'\fR, \f(CW\*(C`PTH_ATTR_NAME\*(C'\fR := `\f(CW\*(C`unknown\*(C'\fR', +\&\f(CW\*(C`PTH_ATTR_JOINABLE\*(C'\fR := \f(CW\*(C`TRUE\*(C'\fR, \f(CW\*(C`PTH_ATTR_CANCELSTATE\*(C'\fR := +\&\f(CW\*(C`PTH_CANCEL_DEFAULT\*(C'\fR, \f(CW\*(C`PTH_ATTR_STACK_SIZE\*(C'\fR := 64*1024 and +\&\f(CW\*(C`PTH_ATTR_STACK_ADDR\*(C'\fR := \f(CW\*(C`NULL\*(C'\fR. All other \f(CW\*(C`PTH_ATTR_*\*(C'\fR attributes are read-only attributes and don't receive default values in \fIattr\fR, because they exists only for bounded attribute objects. .Ip "int \fBpth_attr_set\fR(pth_attr_t \fIattr\fR, int \fIfield\fR, ...);" 4 +.IX Item "int pth_attr_set(pth_attr_t attr, int field, ...);" This sets the attribute field \fIfield\fR in \fIattr\fR to a value specified as an additional argument on the variable argument list. The following attribute \fIfields\fR and argument pairs can @@ -816,6 +832,7 @@ \& PTH_ATTR_STACK_ADDR char * .Ve .Ip "int \fBpth_attr_get\fR(pth_attr_t \fIattr\fR, int \fIfield\fR, ...);" 4 +.IX Item "int pth_attr_get(pth_attr_t attr, int field, ...);" This retrieves the attribute field \fIfield\fR in \fIattr\fR and stores its value in the variable specified through a pointer in an additional argument on the variable argument list. The following \fIfields\fR and @@ -838,61 +855,70 @@ \& PTH_ATTR_BOUND int * .Ve .Ip "int \fBpth_attr_destroy\fR(pth_attr_t \fIattr\fR);" 4 +.IX Item "int pth_attr_destroy(pth_attr_t attr);" This destroys a attribute object \fIattr\fR. After this \fIattr\fR is no longer a valid attribute object. .Sh "Thread Control" +.IX Subsection "Thread Control" The following functions control the threading itself and form the main \s-1API\s0 of the \fBPth\fR library. .Ip "pth_t \fBpth_spawn\fR(pth_attr_t \fIattr\fR, void *(*\fIentry\fR)(void *), void *\fIarg\fR);" 4 +.IX Item "pth_t pth_spawn(pth_attr_t attr, void *(*entry)(void *), void *arg);" This spawns a new thread with the attributes given in \fIattr\fR (or -\f(CWPTH_ATTR_DEFAULT\fR for default attributes \- which means that thread priority, +\&\f(CW\*(C`PTH_ATTR_DEFAULT\*(C'\fR for default attributes \- which means that thread priority, joinability and cancel state are inherited from the current thread) with the starting point at routine \fIentry\fR. This entry routine is called as -`\fIpth_exit\fR\|(\fIentry\fR(\fIarg\fR))\*(R' inside the new thread unit, i.e., \fIentry\fR's +`pth_exit(\fIentry\fR(\fIarg\fR))' inside the new thread unit, i.e., \fIentry\fR's return value is fed to an implicit \fIpth_exit\fR\|(3). So the thread usually can exit by just returning. Nevertheless the thread can also exit explicitly at any time by calling \fIpth_exit\fR\|(3). But keep in mind that calling the \s-1POSIX\s0 function -\fIexit\fR\|(3) still terminates the complete process and not just the current thread. +\&\fIexit\fR\|(3) still terminates the complete process and not just the current thread. .Sp There is no \fBPth\fR\-internal limit on the number of threads one can spawn, except the limit implied by the available virtual memory. \fBPth\fR internally keeps track of thread in dynamic data structures. The function returns -\f(CWNULL\fR on error. +\&\f(CW\*(C`NULL\*(C'\fR on error. .Ip "int \fBpth_once\fR(pth_once_t *\fIctrlvar\fR, void (*\fIfunc\fR)(void *), void *\fIarg\fR);" 4 +.IX Item "int pth_once(pth_once_t *ctrlvar, void (*func)(void *), void *arg);" This is a convenience function which uses a control variable of type -\f(CWpth_once_t\fR to make sure a constructor function \fIfunc\fR is called only once -as `\fIfunc\fR(\fIarg\fR)\*(R' in the system. In other words: Only the first call to -\fIpth_once\fR\|(3) by any thread in the system succeeds. The variable referenced via -\fIctrlvar\fR should be declared as `\f(CWpth_once_t\fR \fIvariable-name\fR = -\f(CWPTH_ONCE_INIT\fR;\*(R' before calling this function. +\&\f(CW\*(C`pth_once_t\*(C'\fR to make sure a constructor function \fIfunc\fR is called only once +as `\fIfunc\fR(\fIarg\fR)' in the system. In other words: Only the first call to +\&\fIpth_once\fR\|(3) by any thread in the system succeeds. The variable referenced via +\&\fIctrlvar\fR should be declared as `\f(CW\*(C`pth_once_t\*(C'\fR \fIvariable-name\fR = +\&\f(CW\*(C`PTH_ONCE_INIT\*(C'\fR;' before calling this function. .Ip "pth_t \fBpth_self\fR(void);" 4 +.IX Item "pth_t pth_self(void);" This just returns the unique thread handle of the currently running thread. This handle itself has to be treated as an opaque entity by the application. It's usually used as an argument to other functions who require an argument of -type \f(CWpth_t\fR. +type \f(CW\*(C`pth_t\*(C'\fR. .Ip "int \fBpth_suspend\fR(pth_t \fItid\fR);" 4 +.IX Item "int pth_suspend(pth_t tid);" This suspends a thread \fItid\fR until it is manually resumed again via -\fIpth_resume\fR\|(3). For this, the thread is moved to the \fB\s-1SUSPENDED\s0\fR queue +\&\fIpth_resume\fR\|(3). For this, the thread is moved to the \fB\s-1SUSPENDED\s0\fR queue and this way is completely out of the scheduler's event handling and thread dispatching scope. Suspending the current thread is not allowed. -The function returns \f(CWTRUE\fR on success and \f(CWFALSE\fR on errors. +The function returns \f(CW\*(C`TRUE\*(C'\fR on success and \f(CW\*(C`FALSE\*(C'\fR on errors. .Ip "int \fBpth_resume\fR(pth_t \fItid\fR);" 4 +.IX Item "int pth_resume(pth_t tid);" This function resumes a previously suspended thread \fItid\fR, i.e. \fItid\fR has to stay on the \fB\s-1SUSPENDED\s0\fR queue. The thread is moved to the -\fB\s-1NEW\s0\fR, \fB\s-1READY\s0\fR or \fB\s-1WAITING\s0\fR queue (dependent on what its state was +\&\fB\s-1NEW\s0\fR, \fB\s-1READY\s0\fR or \fB\s-1WAITING\s0\fR queue (dependent on what its state was when the \fIpth_suspend\fR\|(3) call were made) and this way again enters the event handling and thread dispatching scope of the scheduler. The -function returns \f(CWTRUE\fR on success and \f(CWFALSE\fR on errors. +function returns \f(CW\*(C`TRUE\*(C'\fR on success and \f(CW\*(C`FALSE\*(C'\fR on errors. .Ip "int \fBpth_raise\fR(pth_t \fItid\fR, int \fIsig\fR)" 4 +.IX Item "int pth_raise(pth_t tid, int sig)" This function raises a signal for delivery to thread \fItid\fR only. When one just raises a signal via \fIraise\fR\|(3) or \fIkill\fR\|(2), its delivered to an arbitrary thread which has this signal not blocked. With \fIpth_raise\fR\|(3) one can send a signal to a thread and its guarantees that only this thread gets the signal delivered. But keep in mind that nevertheless the signals \fIaction\fR is still configured \fIprocess\fR\-wide. When \fIsig\fR is 0 plain thread checking is -performed, i.e., `\f(CWpth_raise(tid, 0)\fR\*(R' returns \f(CWTRUE\fR when thread \fItid\fR +performed, i.e., `\f(CW\*(C`pth_raise(tid, 0)\*(C'\fR' returns \f(CW\*(C`TRUE\*(C'\fR when thread \fItid\fR still exists in the \fB\s-1PTH\s0\fR system but doesn't send any signal to it. .Ip "int \fBpth_yield\fR(pth_t \fItid\fR);" 4 +.IX Item "int pth_yield(pth_t tid);" This explicitly yields back the execution control to the scheduler thread. Usually the execution is implicitly transferred back to the scheduler when a thread waits for an event. But when a thread has to do larger \s-1CPU\s0 bursts, it @@ -903,22 +929,23 @@ times the threads should be cooperative, i.e., when they should split their \s-1CPU\s0 bursts into smaller units with this call. .Sp -Usually one specifies \fItid\fR as \f(CWNULL\fR to indicate to the scheduler that it +Usually one specifies \fItid\fR as \f(CW\*(C`NULL\*(C'\fR to indicate to the scheduler that it can freely decide which thread to dispatch next. But if one wants to indicate to the scheduler that a particular thread should be favored on the next dispatching step, one can specify this thread explicitly. This allows the usage of the old concept of \fIcoroutines\fR where a thread/routine switches to a -particular cooperating thread. If \fItid\fR is not \f(CWNULL\fR and points to a \fInew\fR +particular cooperating thread. If \fItid\fR is not \f(CW\*(C`NULL\*(C'\fR and points to a \fInew\fR or \fIready\fR thread, it is guaranteed that this thread receives execution control on the next dispatching step. If \fItid\fR is in a different state (that -is, not in \f(CWPTH_STATE_NEW\fR or \f(CWPTH_STATE_READY\fR) an error is reported. +is, not in \f(CW\*(C`PTH_STATE_NEW\*(C'\fR or \f(CW\*(C`PTH_STATE_READY\*(C'\fR) an error is reported. .Sp -The function usually returns \f(CWTRUE\fR for success and only \f(CWFALSE\fR (with -\f(CWerrno\fR set to \f(CWEINVAL\fR) if \fItid\fR specified and invalid or still not +The function usually returns \f(CW\*(C`TRUE\*(C'\fR for success and only \f(CW\*(C`FALSE\*(C'\fR (with +\&\f(CW\*(C`errno\*(C'\fR set to \f(CW\*(C`EINVAL\*(C'\fR) if \fItid\fR specified and invalid or still not new or ready thread. .Ip "int \fBpth_nap\fR(pth_time_t \fInaptime\fR);" 4 +.IX Item "int pth_nap(pth_time_t naptime);" This functions suspends the execution of the current thread until \fInaptime\fR -is elapsed. \fInaptime\fR is of type \f(CWpth_time_t\fR and this way has theoretically +is elapsed. \fInaptime\fR is of type \f(CW\*(C`pth_time_t\*(C'\fR and this way has theoretically a resolution of one microsecond. In practice you should neither rely on this nor that the thread is awakened exactly after \fInaptime\fR has elapsed. It's only guarantees that the thread will sleep at least \fInaptime\fR. But because @@ -928,6 +955,7 @@ resolution of 10 microseconds or larger. But usually this isn't important for an application unless it tries to use this facility for real time tasks. .Ip "int \fBpth_wait\fR(pth_event_t \fIev\fR);" 4 +.IX Item "int pth_wait(pth_event_t ev);" This is the link between the scheduler and the event facility (see below for the various \fIpth_event_xxx()\fR functions). It's modeled like \fIselect\fR\|(2), i.e., one gives this function one or more events (in the event ring specified by \fIev\fR) @@ -937,107 +965,124 @@ tagging. \fIpth_wait\fR\|(3) returns the number of occurred events and the application can use \fIpth_event_occurred\fR\|(3) to test which events occurred. .Ip "int \fBpth_cancel\fR(pth_t \fItid\fR);" 4 +.IX Item "int pth_cancel(pth_t tid);" This cancels a thread \fItid\fR. How the cancellation is done depends on the cancellation state of \fItid\fR which the thread can configure itself. When its -state is \f(CWPTH_CANCEL_DISABLE\fR a cancellation request is just made pending. -When it is \f(CWPTH_CANCEL_ENABLE\fR it depends on the cancellation type what is -performed. When its \f(CWPTH_CANCEL_DEFERRED\fR again the cancellation request is -just made pending. But when its \f(CWPTH_CANCEL_ASYNCHRONOUS\fR the thread is +state is \f(CW\*(C`PTH_CANCEL_DISABLE\*(C'\fR a cancellation request is just made pending. +When it is \f(CW\*(C`PTH_CANCEL_ENABLE\*(C'\fR it depends on the cancellation type what is +performed. When its \f(CW\*(C`PTH_CANCEL_DEFERRED\*(C'\fR again the cancellation request is +just made pending. But when its \f(CW\*(C`PTH_CANCEL_ASYNCHRONOUS\*(C'\fR the thread is immediately canceled before \fIpth_cancel\fR\|(3) returns. The effect of a thread cancellation is equal to implicitly forcing the thread to call -`\f(CWpth_exit(PTH_CANCELED)\fR\*(R' at one of his cancellation points. In \fBPth\fR +`\f(CW\*(C`pth_exit(PTH_CANCELED)\*(C'\fR' at one of his cancellation points. In \fBPth\fR thread enter a cancellation point either explicitly via \fIpth_cancel_point\fR\|(3) or implicitly by waiting for an event. .Ip "int \fBpth_abort\fR(pth_t \fItid\fR);" 4 +.IX Item "int pth_abort(pth_t tid);" This is the cruel way to cancel a thread \fItid\fR. When it's already dead and -waits to be joined it just joins it (via `\f(CWpth_join(\fR\fItid\fR\f(CW, NULL)\fR') and +waits to be joined it just joins it (via `\f(CW\*(C`pth_join(\*(C'\fR\fItid\fR\f(CW\*(C`, NULL)\*(C'\fR') and this way kicks it out of the system. Else it forces the thread to be not joinable and to allow asynchronous cancellation and then cancels it via -`\f(CWpth_cancel(\fR\fItid\fR\f(CW)\fR\*(R'. +`\f(CW\*(C`pth_cancel(\*(C'\fR\fItid\fR\f(CW\*(C`)\*(C'\fR'. .Ip "int \fBpth_join\fR(pth_t \fItid\fR, void **\fIvalue\fR);" 4 +.IX Item "int pth_join(pth_t tid, void **value);" This joins the current thread with the thread specified via \fItid\fR. It first suspends the current thread until the \fItid\fR thread has terminated. Then it is awakened and stores the value of \fItid\fR's \fIpth_exit\fR\|(3) call into *\fIvalue\fR (if -\fIvalue\fR and not \f(CWNULL\fR) and returns to the caller. A thread can be joined -only when it was \fInot\fR spawned with \f(CWPTH_FLAG_NOJOIN\fR. A thread can only be +\&\fIvalue\fR and not \f(CW\*(C`NULL\*(C'\fR) and returns to the caller. A thread can be joined +only when it was \fInot\fR spawned with \f(CW\*(C`PTH_FLAG_NOJOIN\*(C'\fR. A thread can only be joined once, i.e., after the \fIpth_join\fR\|(3) call the thread \fItid\fR is removed from the system. .Ip "void \fBpth_exit\fR(void *\fIvalue\fR);" 4 +.IX Item "void pth_exit(void *value);" This terminates the current thread. Whether it's immediately removed from the system or inserted into the dead queue of the scheduler depends on its join type which was specified at spawning time. When it was spawned with -\f(CWPTH_FLAG_NOJOIN\fR it's immediately removed and \fIvalue\fR is ignored. +\&\f(CW\*(C`PTH_FLAG_NOJOIN\*(C'\fR it's immediately removed and \fIvalue\fR is ignored. Else the thread is inserted into the dead queue and \fIvalue\fR remembered for a \fIpth_join\fR\|(3) call by another thread. .Sh "Utilities" +.IX Subsection "Utilities" The following functions are utility functions. .Ip "int \fBpth_fdmode\fR(int \fIfd\fR, int \fImode\fR);" 4 +.IX Item "int pth_fdmode(int fd, int mode);" This switches the non-blocking mode flag on file descriptor \fIfd\fR. The -argument \fImode\fR can be \f(CWPTH_FDMODE_BLOCK\fR for switching \fIfd\fR into blocking -I/O mode, \f(CWPTH_FDMODE_NONBLOCK\fR for switching \fIfd\fR into non-blocking I/O -mode or \f(CWPTH_FDMODE_POLL\fR for just polling the current mode. The current mode -is returned (either \f(CWPTH_FDMODE_BLOCK\fR or \f(CWPTH_FDMODE_NONBLOCK\fR) or -\f(CWPTH_FDMODE_ERROR\fR on error. Keep in mind that since \fBPth\fR 1.1 there is no +argument \fImode\fR can be \f(CW\*(C`PTH_FDMODE_BLOCK\*(C'\fR for switching \fIfd\fR into blocking +I/O mode, \f(CW\*(C`PTH_FDMODE_NONBLOCK\*(C'\fR for switching \fIfd\fR into non-blocking I/O +mode or \f(CW\*(C`PTH_FDMODE_POLL\*(C'\fR for just polling the current mode. The current mode +is returned (either \f(CW\*(C`PTH_FDMODE_BLOCK\*(C'\fR or \f(CW\*(C`PTH_FDMODE_NONBLOCK\*(C'\fR) or +\&\f(CW\*(C`PTH_FDMODE_ERROR\*(C'\fR on error. Keep in mind that since \fBPth\fR 1.1 there is no longer a requirement to manually switch a file descriptor into non-blocking mode in order to use it. This is automatically done temporarily inside \fBPth\fR. Instead when you now switch a file descriptor explicitly into non-blocking mode, \fIpth_read\fR\|(3) or \fIpth_write\fR\|(3) will never block the current thread. .Ip "pth_time_t \fBpth_time\fR(long \fIsec\fR, long \fIusec\fR);" 4 -This is a constructor for a \f(CWpth_time_t\fR structure which is a convenient +.IX Item "pth_time_t pth_time(long sec, long usec);" +This is a constructor for a \f(CW\*(C`pth_time_t\*(C'\fR structure which is a convenient function to avoid temporary structure values. It returns a \fIpth_time_t\fR structure which holds the absolute time value specified by \fIsec\fR and \fIusec\fR. .Ip "pth_time_t \fBpth_timeout\fR(long \fIsec\fR, long \fIusec\fR);" 4 -This is a constructor for a \f(CWpth_time_t\fR structure which is a convenient +.IX Item "pth_time_t pth_timeout(long sec, long usec);" +This is a constructor for a \f(CW\*(C`pth_time_t\*(C'\fR structure which is a convenient function to avoid temporary structure values. It returns a \fIpth_time_t\fR structure which holds the absolute time value calculated by adding \fIsec\fR and -\fIusec\fR to the current time. +\&\fIusec\fR to the current time. .Ip "Sfdisc_t *\fBpth_sfiodisc\fR(void);" 4 +.IX Item "Sfdisc_t *pth_sfiodisc(void);" This functions is always available, but only reasonably usable when \fBPth\fR -was built with \fBSfio\fR support (\f(CW--with-sfio\fR option) and \f(CWPTH_EXT_SFIO\fR is -then defined by \f(CWpth.h\fR. It is useful for applications which want to use the +was built with \fBSfio\fR support (\f(CW\*(C`\-\-with\-sfio\*(C'\fR option) and \f(CW\*(C`PTH_EXT_SFIO\*(C'\fR is +then defined by \f(CW\*(C`pth.h\*(C'\fR. It is useful for applications which want to use the comprehensive \fBSfio\fR I/O library with the \fBPth\fR threading library. Then this -function can be used to get an \fBSfio\fR discipline structure (\f(CWSfdisc_t\fR) -which can be pushed onto \fBSfio\fR streams (\f(CWSfio_t\fR) in order to let this +function can be used to get an \fBSfio\fR discipline structure (\f(CW\*(C`Sfdisc_t\*(C'\fR) +which can be pushed onto \fBSfio\fR streams (\f(CW\*(C`Sfio_t\*(C'\fR) in order to let this stream use \fIpth_read\fR\|(3)/\fIpth_write\fR\|(2) instead of \fIread\fR\|(2)/\fIwrite\fR\|(2). The benefit is that this way I/O on the \fBSfio\fR stream does only block the current thread -instead of the whole process. The application has to \fIfree\fR\|(3) the \f(CWSfdisc_t\fR +instead of the whole process. The application has to \fIfree\fR\|(3) the \f(CW\*(C`Sfdisc_t\*(C'\fR structure when it is no longer needed. The Sfio package can be found at http://www.research.att.com/sw/tools/sfio/. .Sh "Cancellation Management" -\fBPth\fR supports \s-1POSIX\s0 style thread cancellation via \fIpth_cancel\fR\|(3) and the +.IX Subsection "Cancellation Management" +\&\fBPth\fR supports \s-1POSIX\s0 style thread cancellation via \fIpth_cancel\fR\|(3) and the following two related functions: .Ip "void \fBpth_cancel_state\fR(int \fInewstate\fR, int *\fIoldstate\fR);" 4 +.IX Item "void pth_cancel_state(int newstate, int *oldstate);" This manages the cancellation state of the current thread. When \fIoldstate\fR -is not \f(CWNULL\fR the function stores the old cancellation state under the -variable pointed to by \fIoldstate\fR. When \fInewstate\fR is not \f(CW0\fR it sets the +is not \f(CW\*(C`NULL\*(C'\fR the function stores the old cancellation state under the +variable pointed to by \fIoldstate\fR. When \fInewstate\fR is not \f(CW\*(C`0\*(C'\fR it sets the new cancellation state. \fIoldstate\fR is created before \fInewstate\fR is set. A -state is a combination of \f(CWPTH_CANCEL_ENABLE\fR or \f(CWPTH_CANCEL_DISABLE\fR and -\f(CWPTH_CANCEL_DEFERRED\fR or \f(CWPTH_CANCEL_ASYNCHRONOUS\fR. -\f(CWPTH_CANCEL_ENABLE|PTH_CANCEL_DEFERRED\fR (or \f(CWPTH_CANCEL_DEFAULT\fR) is the +state is a combination of \f(CW\*(C`PTH_CANCEL_ENABLE\*(C'\fR or \f(CW\*(C`PTH_CANCEL_DISABLE\*(C'\fR and +\&\f(CW\*(C`PTH_CANCEL_DEFERRED\*(C'\fR or \f(CW\*(C`PTH_CANCEL_ASYNCHRONOUS\*(C'\fR. +\&\f(CW\*(C`PTH_CANCEL_ENABLE|PTH_CANCEL_DEFERRED\*(C'\fR (or \f(CW\*(C`PTH_CANCEL_DEFAULT\*(C'\fR) is the default state where cancellation is possible but only at cancellation points. -Use \f(CWPTH_CANCEL_DISABLE\fR to complete disable cancellation for a thread and -\f(CWPTH_CANCEL_ASYNCHRONOUS\fR for allowing asynchronous cancellations, i.e., +Use \f(CW\*(C`PTH_CANCEL_DISABLE\*(C'\fR to complete disable cancellation for a thread and +\&\f(CW\*(C`PTH_CANCEL_ASYNCHRONOUS\*(C'\fR for allowing asynchronous cancellations, i.e., cancellations which can happen at any time. .Ip "void \fBpth_cancel_point\fR(void);" 4 +.IX Item "void pth_cancel_point(void);" This explicitly enter a cancellation point. When the current cancellation -state is \f(CWPTH_CANCEL_DISABLE\fR or no cancellation request is pending, this has +state is \f(CW\*(C`PTH_CANCEL_DISABLE\*(C'\fR or no cancellation request is pending, this has no side-effect and returns immediately. Else it calls -`\f(CWpth_exit(PTH_CANCELED)\fR\*(R'. +`\f(CW\*(C`pth_exit(PTH_CANCELED)\*(C'\fR'. .Sh "Event Handling" -\fBPth\fR has a very flexible event facility which is linked into the scheduler +.IX Subsection "Event Handling" +\&\fBPth\fR has a very flexible event facility which is linked into the scheduler through the \fIpth_wait\fR\|(3) function. The following functions provide the handling of event rings. .Ip "pth_event_t \fBpth_event\fR(unsigned long \fIspec\fR, ...);" 4 +.IX Item "pth_event_t pth_event(unsigned long spec, ...);" This creates a new event ring consisting of a single initial event. The type of the generated event is specified by \fIspec\fR. The following types are available: -.Ip "\f(CWPTH_EVENT_FD\fR" 8 -This is a file descriptor event. One or more of \f(CWPTH_UNTIL_FD_READABLE\fR, -\f(CWPTH_UNTIL_FD_WRITEABLE\fR or \f(CWPTH_UNTIL_FD_EXECPTION\fR have to be \s-1OR\s0\-ed into -\fIspec\fR to specify on which state of the file descriptor you want to wait. The +.RS 4 +.Ip "\f(CW\*(C`PTH_EVENT_FD\*(C'\fR" 4 +.IX Item "PTH_EVENT_FD" +This is a file descriptor event. One or more of \f(CW\*(C`PTH_UNTIL_FD_READABLE\*(C'\fR, +\&\f(CW\*(C`PTH_UNTIL_FD_WRITEABLE\*(C'\fR or \f(CW\*(C`PTH_UNTIL_FD_EXECPTION\*(C'\fR have to be OR-ed into +\&\fIspec\fR to specify on which state of the file descriptor you want to wait. The file descriptor itself has to be given as an additional argument. Example: -`\f(CWpth_event(PTH_EVENT_FD|PTH_UNTIL_FD_READABLE, fd)\fR\*(R'. -.Ip "\f(CWPTH_EVENT_SELECT\fR" 8 +`\f(CW\*(C`pth_event(PTH_EVENT_FD|PTH_UNTIL_FD_READABLE, fd)\*(C'\fR'. +.Ip "\f(CW\*(C`PTH_EVENT_SELECT\*(C'\fR" 4 +.IX Item "PTH_EVENT_SELECT" This is a multiple file descriptor event modeled directly after the \fIselect\fR\|(2) call (actually it is also used to implement \fIpth_select\fR\|(3) internally). It's a convenient way to wait for a large set of file descriptors at once and at each @@ -1045,163 +1090,198 @@ side-effect one receives the number of file descriptors which causes the event to be occurred (using \s-1BSD\s0 semantics, i.e., when a file descriptor occurred in two sets it's counted twice). The arguments correspond directly to the -\fIselect\fR\|(2) function arguments except that there is no timeout argument (because -timeouts already can be handled via \f(CWPTH_EVENT_TIME\fR events). +\&\fIselect\fR\|(2) function arguments except that there is no timeout argument (because +timeouts already can be handled via \f(CW\*(C`PTH_EVENT_TIME\*(C'\fR events). .Sp -Example: `\f(CWpth_event(PTH_EVENT_SELECT, &rc, nfd, rfds, wfds, efds)\fR\*(R' where -\f(CWrc\fR has to be of type `\f(CWint *\fR\*(R', \f(CWnfd\fR has to be of type `\f(CWint\fR\*(R' and -\f(CWrfds\fR, \f(CWwfds\fR and \f(CWefds\fR have to be of type `\f(CWfd_set *\fR\*(R' (see -\fIselect\fR\|(2)). The number of occurred file descriptors are stored in \f(CWrc\fR. -.Ip "\f(CWPTH_EVENT_SIGS\fR" 8 +Example: `\f(CW\*(C`pth_event(PTH_EVENT_SELECT, &rc, nfd, rfds, wfds, efds)\*(C'\fR' where +\&\f(CW\*(C`rc\*(C'\fR has to be of type `\f(CW\*(C`int *\*(C'\fR', \f(CW\*(C`nfd\*(C'\fR has to be of type `\f(CW\*(C`int\*(C'\fR' and +\&\f(CW\*(C`rfds\*(C'\fR, \f(CW\*(C`wfds\*(C'\fR and \f(CW\*(C`efds\*(C'\fR have to be of type `\f(CW\*(C`fd_set *\*(C'\fR' (see +\&\fIselect\fR\|(2)). The number of occurred file descriptors are stored in \f(CW\*(C`rc\*(C'\fR. +.Ip "\f(CW\*(C`PTH_EVENT_SIGS\*(C'\fR" 4 +.IX Item "PTH_EVENT_SIGS" This is a signal set event. The two additional arguments have to be a pointer -to a signal set (type `\f(CWsigset_t *\fR') and a pointer to a signal number -variable (type `\f(CWint *\fR'). This event waits until one of the signals in +to a signal set (type `\f(CW\*(C`sigset_t *\*(C'\fR') and a pointer to a signal number +variable (type `\f(CW\*(C`int *\*(C'\fR'). This event waits until one of the signals in the signal set occurred. As a result the occurred signal number is stored in the second additional argument. Keep in mind that the \fBPth\fR scheduler doesn't block signals automatically. So when you want to wait for a signal with this event you've to block it via \fIsigprocmask\fR\|(2) or it will be delivered without -your notice. Example: `\f(CWsigemptyset(&set); sigaddset(&set, SIGINT); -pth_event(PTH_EVENT_SIG, &set, &sig);\fR\*(R'. -.Ip "\f(CWPTH_EVENT_TIME\fR" 8 +your notice. Example: `\f(CW\*(C`sigemptyset(&set); sigaddset(&set, SIGINT); +pth_event(PTH_EVENT_SIG, &set, &sig);\*(C'\fR'. +.Ip "\f(CW\*(C`PTH_EVENT_TIME\*(C'\fR" 4 +.IX Item "PTH_EVENT_TIME" This is a time point event. The additional argument has to be of type -\f(CWpth_time_t\fR (usually on-the-fly generated via \fIpth_time\fR\|(3)). This events +\&\f(CW\*(C`pth_time_t\*(C'\fR (usually on-the-fly generated via \fIpth_time\fR\|(3)). This events waits until the specified time point has elapsed. Keep in mind that the value is an absolute time point and not an offset. When you want to wait for a specified amount of time, you've to add the current time to the offset (usually on-the-fly achieved via \fIpth_timeout\fR\|(3)). Example: -`\f(CWpth_event(PTH_EVENT_TIME, pth_timeout(2,0))\fR\*(R'. -.Ip "\f(CWPTH_EVENT_MSG\fR" 8 +`\f(CW\*(C`pth_event(PTH_EVENT_TIME, pth_timeout(2,0))\*(C'\fR'. +.Ip "\f(CW\*(C`PTH_EVENT_MSG\*(C'\fR" 4 +.IX Item "PTH_EVENT_MSG" This is a message port event. The additional argument has to be of type -\f(CWpth_msgport_t\fR. This events waits until one or more messages were received -on the specified message port. Example: `\f(CWpth_event(PTH_EVENT_MSG, mp)\fR\*(R'. -.Ip "\f(CWPTH_EVENT_TID\fR" 8 -This is a thread event. The additional argument has to be of type \f(CWpth_t\fR. -One of \f(CWPTH_UNTIL_TID_NEW\fR, \f(CWPTH_UNTIL_TID_READY\fR, \f(CWPTH_UNTIL_TID_WAITING\fR -or \f(CWPTH_UNTIL_TID_DEAD\fR has to be \s-1OR\s0\-ed into \fIspec\fR to specify on which +\&\f(CW\*(C`pth_msgport_t\*(C'\fR. This events waits until one or more messages were received +on the specified message port. Example: `\f(CW\*(C`pth_event(PTH_EVENT_MSG, mp)\*(C'\fR'. +.Ip "\f(CW\*(C`PTH_EVENT_TID\*(C'\fR" 4 +.IX Item "PTH_EVENT_TID" +This is a thread event. The additional argument has to be of type \f(CW\*(C`pth_t\*(C'\fR. +One of \f(CW\*(C`PTH_UNTIL_TID_NEW\*(C'\fR, \f(CW\*(C`PTH_UNTIL_TID_READY\*(C'\fR, \f(CW\*(C`PTH_UNTIL_TID_WAITING\*(C'\fR +or \f(CW\*(C`PTH_UNTIL_TID_DEAD\*(C'\fR has to be OR-ed into \fIspec\fR to specify on which state of the thread you want to wait. Example: -`\f(CWpth_event(PTH_EVENT_TID|PTH_UNTIL_TID_DEAD, tid)\fR\*(R'. -.Ip "\f(CWPTH_EVENT_FUNC\fR" 8 +`\f(CW\*(C`pth_event(PTH_EVENT_TID|PTH_UNTIL_TID_DEAD, tid)\*(C'\fR'. +.Ip "\f(CW\*(C`PTH_EVENT_FUNC\*(C'\fR" 4 +.IX Item "PTH_EVENT_FUNC" This is a custom callback function event. Three additional arguments -have to be given with the following types: `\f(CWint (*)(void *)\fR\*(R', -`\f(CWvoid *\fR\*(R' and `\f(CWpth_time_t\fR\*(R'. The first is a function pointer to +have to be given with the following types: `\f(CW\*(C`int (*)(void *)\*(C'\fR', +`\f(CW\*(C`void *\*(C'\fR' and `\f(CW\*(C`pth_time_t\*(C'\fR'. The first is a function pointer to a check function and the second argument is a user-supplied context value which is passed to this function. The scheduler calls this function on a regular basis (on his own scheduler stack, so be very careful!) and the thread is kept sleeping while the function returns -\f(CWFALSE\fR. Once it returned \f(CWTRUE\fR the thread will be awakened. The +\&\f(CW\*(C`FALSE\*(C'\fR. Once it returned \f(CW\*(C`TRUE\*(C'\fR the thread will be awakened. The check interval is defined by the third argument, i.e., the check function is polled again not until this amount of time elapsed. Example: -`\f(CWpth_event(PTH_EVENT_FUNC, func, arg, pth_time(0,500000))\fR\*(R'. +`\f(CW\*(C`pth_event(PTH_EVENT_FUNC, func, arg, pth_time(0,500000))\*(C'\fR'. +.RE +.RS 4 +.RE .Ip "unsigned long \fBpth_event_typeof\fR(pth_event_t \fIev\fR);" 4 +.IX Item "unsigned long pth_event_typeof(pth_event_t ev);" This returns the type of event \fIev\fR. It's a combination of the describing -\f(CWPTH_EVENT_XX\fR and \f(CWPTH_UNTIL_XX\fR value. This is especially useful to know +\&\f(CW\*(C`PTH_EVENT_XX\*(C'\fR and \f(CW\*(C`PTH_UNTIL_XX\*(C'\fR value. This is especially useful to know which arguments have to be supplied to the \fIpth_event_extract\fR\|(3) function. .Ip "int \fBpth_event_extract\fR(pth_event_t \fIev\fR, ...);" 4 +.IX Item "int pth_event_extract(pth_event_t ev, ...);" When \fIpth_event\fR\|(3) is treated like \fIsprintf\fR\|(3), then this function is -\fIsscanf\fR\|(3), i.e., it is the inverse operation of \fIpth_event\fR\|(3). This means that +\&\fIsscanf\fR\|(3), i.e., it is the inverse operation of \fIpth_event\fR\|(3). This means that it can be used to extract the ingredients of an event. The ingredients are stored into variables which are given as pointers on the variable argument list. Which pointers have to be present depends on the event type and has to be determined by the caller before via \fIpth_event_typeof\fR\|(3). .Sp -To make it clear, when you constructed \fIev\fR via `\f(CWev = -pth_event(PTH_EVENT_FD, fd);\fR\*(R' you have to extract it via -`\f(CWpth_event_extract(ev, &fd)\fR\*(R', etc. For multiple arguments of an event the +To make it clear, when you constructed \fIev\fR via `\f(CW\*(C`ev = +pth_event(PTH_EVENT_FD, fd);\*(C'\fR' you have to extract it via +`\f(CW\*(C`pth_event_extract(ev, &fd)\*(C'\fR', etc. For multiple arguments of an event the order of the pointer arguments is the same as for \fIpth_event\fR\|(3). But always keep in mind that you have to always supply \fIpointers\fR to \fIvariables\fR and these variables have to be of the same type as the argument of \fIpth_event\fR\|(3) required. .Ip "pth_event_t \fBpth_event_concat\fR(pth_event_t \fIev\fR, ...);" 4 +.IX Item "pth_event_t pth_event_concat(pth_event_t ev, ...);" This concatenates one or more additional event rings to the event ring \fIev\fR and returns \fIev\fR. The end of the argument list has to be marked with a -\f(CWNULL\fR argument. Use this function to create real events rings out of the +\&\f(CW\*(C`NULL\*(C'\fR argument. Use this function to create real events rings out of the single-event rings created by \fIpth_event\fR\|(3). .Ip "pth_event_t \fBpth_event_isolate\fR(pth_event_t \fIev\fR);" 4 +.IX Item "pth_event_t pth_event_isolate(pth_event_t ev);" This isolates the event \fIev\fR from possibly appended events in the event ring. -When in \fIev\fR only one event exists, this returns \f(CWNULL\fR. When remaining +When in \fIev\fR only one event exists, this returns \f(CW\*(C`NULL\*(C'\fR. When remaining events exists, they form a new event ring which is returned. .Ip "pth_event_t \fBpth_event_walk\fR(pth_event_t \fIev\fR, int \fIdirection\fR);" 4 -This walks to the next (when \fIdirection\fR is \f(CWPTH_WALK_NEXT\fR) or previews -(when \fIdirection\fR is \f(CWPTH_WALK_PREV\fR) event in the event ring \fIev\fR and -returns this new reached event. Additionally \f(CWPTH_UNTIL_OCCURRED\fR can be -\s-1OR\s0\-ed into \fIdirection\fR to walk to the next/previous occurred event in the +.IX Item "pth_event_t pth_event_walk(pth_event_t ev, int direction);" +This walks to the next (when \fIdirection\fR is \f(CW\*(C`PTH_WALK_NEXT\*(C'\fR) or previews +(when \fIdirection\fR is \f(CW\*(C`PTH_WALK_PREV\*(C'\fR) event in the event ring \fIev\fR and +returns this new reached event. Additionally \f(CW\*(C`PTH_UNTIL_OCCURRED\*(C'\fR can be +OR-ed into \fIdirection\fR to walk to the next/previous occurred event in the ring \fIev\fR. .Ip "int \fBpth_event_occurred\fR(pth_event_t \fIev\fR);" 4 +.IX Item "int pth_event_occurred(pth_event_t ev);" This checks whether the event \fIev\fR occurred. This is a fast operation because only a tag on \fIev\fR is checked which was either set or still not set by the scheduler. In other words: This doesn't check the event itself, it just checks the last knowledge of the scheduler. .Ip "int \fBpth_event_free\fR(pth_event_t \fIev\fR, int \fImode\fR);" 4 -This deallocates the event \fIev\fR (when \fImode\fR is \f(CWPTH_FREE_THIS\fR) or all +.IX Item "int pth_event_free(pth_event_t ev, int mode);" +This deallocates the event \fIev\fR (when \fImode\fR is \f(CW\*(C`PTH_FREE_THIS\*(C'\fR) or all events appended to the event ring under \fIev\fR (when \fImode\fR is -\f(CWPTH_FREE_ALL\fR). +\&\f(CW\*(C`PTH_FREE_ALL\*(C'\fR). .Sh "Key-Based Storage" +.IX Subsection "Key-Based Storage" The following functions provide thread-local storage through unique keys similar to the \s-1POSIX\s0 \fBPthread\fR \s-1API\s0. Use this for thread specific global data. .Ip "int \fBpth_key_create\fR(pth_key_t *\fIkey\fR, void (*\fIfunc\fR)(void *));" 4 +.IX Item "int pth_key_create(pth_key_t *key, void (*func)(void *));" This created a new unique key and stores it in \fIkey\fR. Additionally \fIfunc\fR can specify a destructor function which is called on the current threads termination with the \fIkey\fR. .Ip "int \fBpth_key_delete\fR(pth_key_t \fIkey\fR);" 4 +.IX Item "int pth_key_delete(pth_key_t key);" This explicitly destroys a key \fIkey\fR. .Ip "int \fBpth_key_setdata\fR(pth_key_t \fIkey\fR, const void *\fIvalue\fR);" 4 +.IX Item "int pth_key_setdata(pth_key_t key, const void *value);" This stores \fIvalue\fR under \fIkey\fR. .Ip "void *\fBpth_key_getdata\fR(pth_key_t \fIkey\fR);" 4 +.IX Item "void *pth_key_getdata(pth_key_t key);" This retrieves the value under \fIkey\fR. .Sh "Message Port Communication" +.IX Subsection "Message Port Communication" The following functions provide message ports which can be used for efficient and flexible inter-thread communication. .Ip "pth_msgport_t \fBpth_msgport_create\fR(const char *\fIname\fR);" 4 +.IX Item "pth_msgport_t pth_msgport_create(const char *name);" This returns a pointer to a new message port with name \fIname\fR. The \fIname\fR can be used by other threads via \fIpth_msgport_find\fR\|(3) to find the message port in case they do not know directly the pointer to the message port. .Ip "void \fBpth_msgport_destroy\fR(pth_msgport_t \fImp\fR);" 4 +.IX Item "void pth_msgport_destroy(pth_msgport_t mp);" This destroys a message port \fImp\fR. Before all pending messages on it are replied to their origin message port. .Ip "pth_msgport_t \fBpth_msgport_find\fR(const char *\fIname\fR);" 4 +.IX Item "pth_msgport_t pth_msgport_find(const char *name);" This finds a message port in the system by \fIname\fR and returns the pointer to it. .Ip "int \fBpth_msgport_pending\fR(pth_msgport_t \fImp\fR);" 4 +.IX Item "int pth_msgport_pending(pth_msgport_t mp);" This returns the number of pending messages on message port \fImp\fR. .Ip "int \fBpth_msgport_put\fR(pth_msgport_t \fImp\fR, pth_message_t *\fIm\fR);" 4 +.IX Item "int pth_msgport_put(pth_msgport_t mp, pth_message_t *m);" This puts (or sends) a message \fIm\fR to message port \fImp\fR. .Ip "pth_message_t *\fBpth_msgport_get\fR(pth_msgport_t \fImp\fR);" 4 +.IX Item "pth_message_t *pth_msgport_get(pth_msgport_t mp);" This gets (or receives) the top message from message port \fImp\fR. Incoming messages are always kept in a queue, so there can be more pending messages, of course. .Ip "int \fBpth_msgport_reply\fR(pth_message_t *\fIm\fR);" 4 +.IX Item "int pth_msgport_reply(pth_message_t *m);" This replies a message \fIm\fR to the message port of the sender. .Sh "Thread Cleanups" +.IX Subsection "Thread Cleanups" The following functions provide per-thread cleanup functions. .Ip "int \fBpth_cleanup_push\fR(void (*\fIhandler\fR)(void *), void *\fIarg\fR);" 4 +.IX Item "int pth_cleanup_push(void (*handler)(void *), void *arg);" This pushes the routine \fIhandler\fR onto the stack of cleanup routines for the current thread. These routines are called in \s-1LIFO\s0 order when the thread terminates. .Ip "int \fBpth_cleanup_pop\fR(int \fIexecute\fR);" 4 +.IX Item "int pth_cleanup_pop(int execute);" This pops the top-most routine from the stack of cleanup routines for the -current thread. When \fIexecute\fR is \f(CWTRUE\fR the routine is additionally called. +current thread. When \fIexecute\fR is \f(CW\*(C`TRUE\*(C'\fR the routine is additionally called. .Sh "Process Forking" +.IX Subsection "Process Forking" The following functions provide some special support for process forking situations inside the threading environment. .Ip "int \fBpth_atfork_push\fR(void (*\fIprepare\fR)(void *), void (*)(void *\fIparent\fR), void (*)(void *\fIchild\fR), void *\fIarg\fR);" 4 +.IX Item "int pth_atfork_push(void (*prepare)(void *), void (*)(void *parent), void (*)(void *child), void *arg);" This function declares forking handlers to be called before and after -\fIpth_fork\fR\|(3), in the context of the thread that called \fIpth_fork\fR\|(3). The -\fIprepare\fR handler is called before \fIfork\fR\|(2) processing commences. The -\fIparent\fR handler is called after \fIfork\fR\|(2) processing completes in the parent +\&\fIpth_fork\fR\|(3), in the context of the thread that called \fIpth_fork\fR\|(3). The +\&\fIprepare\fR handler is called before \fIfork\fR\|(2) processing commences. The +\&\fIparent\fR handler is called after \fIfork\fR\|(2) processing completes in the parent process. The \fIchild\fR handler is called after \fIfork\fR\|(2) processing completed in the child process. If no handling is desired at one or more of these three -points, the corresponding handler can be given as \f(CWNULL\fR. Each handler is +points, the corresponding handler can be given as \f(CW\*(C`NULL\*(C'\fR. Each handler is called with \fIarg\fR as the argument. .Sp The order of calls to \fIpth_atfork_push\fR\|(3) is significant. The \fIparent\fR and -\fIchild\fR handlers are called in the order in which they were established by +\&\fIchild\fR handlers are called in the order in which they were established by calls to \fIpth_atfork_push\fR\|(3), i.e., \s-1FIFO\s0. The \fIprepare\fR fork handlers are called in the opposite order, i.e., \s-1LIFO\s0. .Ip "int \fBpth_atfork_pop\fR(void);" 4 +.IX Item "int pth_atfork_pop(void);" This removes the top-most handlers on the forking handler stack which were -established with the last \fIpth_atfork_push\fR\|(3) call. It returns \f(CWFALSE\fR when no +established with the last \fIpth_atfork_push\fR\|(3) call. It returns \f(CW\*(C`FALSE\*(C'\fR when no more handlers couldn't be removed from the stack. .Ip "pid_t \fBpth_fork\fR(void);" 4 +.IX Item "pid_t pth_fork(void);" This is a variant of \fIfork\fR\|(2) with the difference that the current thread only is forked into a separate process, i.e., in the parent process nothing changes while in the child process all threads are gone except for the scheduler and @@ -1210,6 +1290,7 @@ reasonable. Additionally this function takes care of forking handlers as established by \fIpth_fork_push\fR\|(3). .Sh "Synchronization" +.IX Subsection "Synchronization" The following functions provide synchronization support via mutual exclusion locks (\fBmutex\fR), read-write locks (\fBrwlock\fR), condition variables (\fBcond\fR) and barriers (\fBbarrier\fR). Keep in mind that in a non-preemptive threading @@ -1224,152 +1305,179 @@ especially true for critical code sections which implicitly or explicitly use the event mechanism. .Ip "int \fBpth_mutex_init\fR(pth_mutex_t *\fImutex\fR);" 4 -This dynamically initializes a mutex variable of type `\f(CWpth_mutex_t\fR\*(R'. -Alternatively one can also use static initialization via `\f(CWpth_mutex_t -mutex = PTH_MUTEX_INIT\fR\*(R'. +.IX Item "int pth_mutex_init(pth_mutex_t *mutex);" +This dynamically initializes a mutex variable of type `\f(CW\*(C`pth_mutex_t\*(C'\fR'. +Alternatively one can also use static initialization via `\f(CW\*(C`pth_mutex_t +mutex = PTH_MUTEX_INIT\*(C'\fR'. .Ip "int \fBpth_mutex_acquire\fR(pth_mutex_t *\fImutex\fR, int \fItry\fR, pth_event_t \fIev\fR);" 4 +.IX Item "int pth_mutex_acquire(pth_mutex_t *mutex, int try, pth_event_t ev);" This acquires a mutex \fImutex\fR. If the mutex is already locked by another thread, the current threads execution is suspended until the mutex is unlocked again or additionally the extra events in \fIev\fR occurred (when \fIev\fR is not -\f(CWNULL\fR). Recursive locking is explicitly supported, i.e., a thread is allowed +\&\f(CW\*(C`NULL\*(C'\fR). Recursive locking is explicitly supported, i.e., a thread is allowed to acquire a mutex more than once before its released. But it then also has be released the same number of times until the mutex is again lockable by others. -When \fItry\fR is \f(CWTRUE\fR this function never suspends execution. Instead it -returns \f(CWFALSE\fR with \f(CWerrno\fR set to \f(CWEBUSY\fR. +When \fItry\fR is \f(CW\*(C`TRUE\*(C'\fR this function never suspends execution. Instead it +returns \f(CW\*(C`FALSE\*(C'\fR with \f(CW\*(C`errno\*(C'\fR set to \f(CW\*(C`EBUSY\*(C'\fR. .Ip "int \fBpth_mutex_release\fR(pth_mutex_t *\fImutex\fR);" 4 +.IX Item "int pth_mutex_release(pth_mutex_t *mutex);" This decrements the recursion locking count on \fImutex\fR and when it is zero it releases the mutex \fImutex\fR. .Ip "int \fBpth_rwlock_init\fR(pth_rwlock_t *\fIrwlock\fR);" 4 +.IX Item "int pth_rwlock_init(pth_rwlock_t *rwlock);" This dynamically initializes a read-write lock variable of type -`\f(CWpth_rwlock_t\fR\*(R'. Alternatively one can also use static initialization -via `\f(CWpth_rwlock_t rwlock = PTH_RWLOCK_INIT\fR\*(R'. +`\f(CW\*(C`pth_rwlock_t\*(C'\fR'. Alternatively one can also use static initialization +via `\f(CW\*(C`pth_rwlock_t rwlock = PTH_RWLOCK_INIT\*(C'\fR'. .Ip "int \fBpth_rwlock_acquire\fR(pth_rwlock_t *\fIrwlock\fR, int \fIop\fR, int \fItry\fR, pth_event_t \fIev\fR);" 4 -This acquires a read-only (when \fIop\fR is \f(CWPTH_RWLOCK_RD\fR) or a read-write -(when \fIop\fR is \f(CWPTH_RWLOCK_RW\fR) lock \fIrwlock\fR. When the lock is only locked +.IX Item "int pth_rwlock_acquire(pth_rwlock_t *rwlock, int op, int try, pth_event_t ev);" +This acquires a read-only (when \fIop\fR is \f(CW\*(C`PTH_RWLOCK_RD\*(C'\fR) or a read-write +(when \fIop\fR is \f(CW\*(C`PTH_RWLOCK_RW\*(C'\fR) lock \fIrwlock\fR. When the lock is only locked by other threads in read-only mode, the lock succeeds. But when one thread holds a read-write lock, all locking attempts suspend the current thread until this lock is released again. Additionally in \fIev\fR events can be given to let -the locking timeout, etc. When \fItry\fR is \f(CWTRUE\fR this function never suspends -execution. Instead it returns \f(CWFALSE\fR with \f(CWerrno\fR set to \f(CWEBUSY\fR. +the locking timeout, etc. When \fItry\fR is \f(CW\*(C`TRUE\*(C'\fR this function never suspends +execution. Instead it returns \f(CW\*(C`FALSE\*(C'\fR with \f(CW\*(C`errno\*(C'\fR set to \f(CW\*(C`EBUSY\*(C'\fR. .Ip "int \fBpth_rwlock_release\fR(pth_rwlock_t *\fIrwlock\fR);" 4 +.IX Item "int pth_rwlock_release(pth_rwlock_t *rwlock);" This releases a previously acquired (read-only or read-write) lock. .Ip "int \fBpth_cond_init\fR(pth_cond_t *\fIcond\fR);" 4 +.IX Item "int pth_cond_init(pth_cond_t *cond);" This dynamically initializes a condition variable variable of type -`\f(CWpth_cond_t\fR\*(R'. Alternatively one can also use static initialization via -`\f(CWpth_cond_t cond = PTH_COND_INIT\fR\*(R'. +`\f(CW\*(C`pth_cond_t\*(C'\fR'. Alternatively one can also use static initialization via +`\f(CW\*(C`pth_cond_t cond = PTH_COND_INIT\*(C'\fR'. .Ip "int \fBpth_cond_await\fR(pth_cond_t *\fIcond\fR, pth_mutex_t *\fImutex\fR, pth_event_t \fIev\fR);" 4 +.IX Item "int pth_cond_await(pth_cond_t *cond, pth_mutex_t *mutex, pth_event_t ev);" This awaits a condition situation. The caller has to follow the semantics of the \s-1POSIX\s0 condition variables: \fImutex\fR has to be acquired before this function is called. The execution of the current thread is then suspended -either until the events in \fIev\fR occurred (when \fIev\fR is not \f(CWNULL\fR) or -\fIcond\fR was notified by another thread via \fIpth_cond_notify\fR\|(3). While the +either until the events in \fIev\fR occurred (when \fIev\fR is not \f(CW\*(C`NULL\*(C'\fR) or +\&\fIcond\fR was notified by another thread via \fIpth_cond_notify\fR\|(3). While the thread is waiting, \fImutex\fR is released. Before it returns \fImutex\fR is reacquired. .Ip "int \fBpth_cond_notify\fR(pth_cond_t *\fIcond\fR, int \fIbroadcast\fR);" 4 +.IX Item "int pth_cond_notify(pth_cond_t *cond, int broadcast);" This notified one or all threads which are waiting on \fIcond\fR. When -\fIbroadcast\fR is \f(CWTRUE\fR all thread are notified, else only a single +\&\fIbroadcast\fR is \f(CW\*(C`TRUE\*(C'\fR all thread are notified, else only a single (unspecified) one. -.Ip "int \fBpth_barrier_init\fR(pth_barrier_t *\fIbarrier\fR, int I - GNU Portable Threads" - -.IX Header "NAME" - -.IX Header "VERSION" - -.IX Header "SYNOPSIS" - -.IX Item "\fBGlobal Library Management\fR" - -.IX Item "\fBThread Attribute Handling\fR" - -.IX Item "\fBThread Control\fR" - -.IX Item "\fBUtilities\fR" - -.IX Item "\fBCancellation Management\fR" - -.IX Item "\fBEvent Handling\fR" - -.IX Item "\fBKey-Based Storage\fR" - -.IX Item "\fBMessage Port Communication\fR" - -.IX Item "\fBThread Cleanups\fR" - -.IX Item "\fBProcess Forking\fR" - -.IX Item "\fBSynchronization\fR" - -.IX Item "\fBGeneralized \s-1POSIX\s0 Replacement \s-1API\s0\fR" - -.IX Item "\fBStandard \s-1POSIX\s0 Replacement \s-1API\s0\fR" - -.IX Header "DESCRIPTION" - -.IX Subsection "Threading Background" - -.IX Subsection "The World of Threading" - -.IX Item "\fBo\fR \fBprocess\fR vs. \fBthread\fR" - -.IX Item "\fBo\fR \fBkernel-space\fR vs. \fBuser-space\fR threading" - -.IX Item "\fBo\fR \fBpreemptive\fR vs. \fBnon-preemptive\fR thread scheduling" - -.IX Item "\fBo\fR \fBconcurrency\fR vs. \fBparallelism\fR" - -.IX Item "\fBo\fR \fBresponsiveness\fR" - -.IX Item "\fBo\fR \fBreentrant\fR, \fBthread-safe\fR and \fBasynchronous-safe\fR functions" - -.IX Subsection "User-Space Threads" - -.IX Item "\fB1.\fR" - -.IX Item "\fB2.\fR" - -.IX Subsection "The Compromise of Pth" - -.IX Item "\fBo\fR" - -.IX Item "\fBo\fR" - -.IX Item "\fBo\fR" - -.IX Item "\fBo\fR" - -.IX Subsection "The life cycle of a thread" - -.IX Header "APPLICATION PROGRAMMING INTERFACE (API)" - -.IX Subsection "Global Library Management" - -.IX Item "int \fBpth_init\fR(void);" - -.IX Item "int \fBpth_kill\fR(void);" - -.IX Item "long \fBpth_ctrl\fR(unsigned long \fIquery\fR, ...);" - -.IX Item "\f(CWPTH_CTRL_GETTHREADS\fR" - -.IX Item "\f(CWPTH_CTRL_GETAVLOAD\fR" - -.IX Item "\f(CWPTH_CTRL_GETPRIO\fR" - -.IX Item "\f(CWPTH_CTRL_GETNAME\fR" - -.IX Item "\f(CWPTH_CTRL_DUMPSTATE\fR" - -.IX Item "long \fBpth_version\fR(void);" - -.IX Subsection "Thread Attribute Handling" - -.IX Item "\f(CWPTH_ATTR_PRIO\fR (read-write) [\f(CWint\fR]" - -.IX Item "\f(CWPTH_ATTR_NAME\fR (read-write) [\f(CWchar *\fR]" - -.IX Item "\f(CWPTH_ATTR_JOINABLE\fR (read-write> [\f(CWint\fR]" - -.IX Item "\f(CWPTH_ATTR_CANCEL_STATE\fR (read-write) [\f(CWunsigned int\fR]" - -.IX Item "\f(CWPTH_ATTR_STACK_SIZE\fR (read-write) [\f(CWunsigned int\fR]" - -.IX Item "\f(CWPTH_ATTR_STACK_ADDR\fR (read-write) [\f(CWchar *\fR]" - -.IX Item "\f(CWPTH_ATTR_TIME_SPAWN\fR (read-only) [\f(CWpth_time_t\fR]" - -.IX Item "\f(CWPTH_ATTR_TIME_LAST\fR (read-only) [\f(CWpth_time_t\fR]" - -.IX Item "\f(CWPTH_ATTR_TIME_RAN\fR (read-only) [\f(CWpth_time_t\fR]" - -.IX Item "\f(CWPTH_ATTR_START_FUNC\fR (read-only) [\f(CWvoid *(*)(void *)\fR]" - -.IX Item "\f(CWPTH_ATTR_START_ARG\fR (read-only) [\f(CWvoid *\fR]" - -.IX Item "\f(CWPTH_ATTR_STATE\fR (read-only) [\f(CWpth_state_t\fR]" - -.IX Item "\f(CWPTH_ATTR_EVENTS\fR (read-only) [\f(CWpth_event_t\fR]" - -.IX Item "\f(CWPTH_ATTR_BOUND\fR (read-only) [\f(CWint\fR]" - -.IX Item "pth_attr_t \fBpth_attr_of\fR(pth_t \fItid\fR);" - -.IX Item "pth_attr_t \fBpth_attr_new\fR(void);" - -.IX Item "int \fBpth_attr_init\fR(pth_attr_t \fIattr\fR);" - -.IX Item "int \fBpth_attr_set\fR(pth_attr_t \fIattr\fR, int \fIfield\fR, ...);" - -.IX Item "int \fBpth_attr_get\fR(pth_attr_t \fIattr\fR, int \fIfield\fR, ...);" - -.IX Item "int \fBpth_attr_destroy\fR(pth_attr_t \fIattr\fR);" - -.IX Subsection "Thread Control" - -.IX Item "pth_t \fBpth_spawn\fR(pth_attr_t \fIattr\fR, void *(*\fIentry\fR)(void *), void *\fIarg\fR);" - -.IX Item "int \fBpth_once\fR(pth_once_t *\fIctrlvar\fR, void (*\fIfunc\fR)(void *), void *\fIarg\fR);" - -.IX Item "pth_t \fBpth_self\fR(void);" - -.IX Item "int \fBpth_suspend\fR(pth_t \fItid\fR);" - -.IX Item "int \fBpth_resume\fR(pth_t \fItid\fR);" - -.IX Item "int \fBpth_raise\fR(pth_t \fItid\fR, int \fIsig\fR)" - -.IX Item "int \fBpth_yield\fR(pth_t \fItid\fR);" - -.IX Item "int \fBpth_nap\fR(pth_time_t \fInaptime\fR);" - -.IX Item "int \fBpth_wait\fR(pth_event_t \fIev\fR);" - -.IX Item "int \fBpth_cancel\fR(pth_t \fItid\fR);" - -.IX Item "int \fBpth_abort\fR(pth_t \fItid\fR);" - -.IX Item "int \fBpth_join\fR(pth_t \fItid\fR, void **\fIvalue\fR);" - -.IX Item "void \fBpth_exit\fR(void *\fIvalue\fR);" - -.IX Subsection "Utilities" - -.IX Item "int \fBpth_fdmode\fR(int \fIfd\fR, int \fImode\fR);" - -.IX Item "pth_time_t \fBpth_time\fR(long \fIsec\fR, long \fIusec\fR);" - -.IX Item "pth_time_t \fBpth_timeout\fR(long \fIsec\fR, long \fIusec\fR);" - -.IX Item "Sfdisc_t *\fBpth_sfiodisc\fR(void);" - -.IX Subsection "Cancellation Management" - -.IX Item "void \fBpth_cancel_state\fR(int \fInewstate\fR, int *\fIoldstate\fR);" - -.IX Item "void \fBpth_cancel_point\fR(void);" - -.IX Subsection "Event Handling" - -.IX Item "pth_event_t \fBpth_event\fR(unsigned long \fIspec\fR, ...);" - -.IX Item "\f(CWPTH_EVENT_FD\fR" - -.IX Item "\f(CWPTH_EVENT_SELECT\fR" - -.IX Item "\f(CWPTH_EVENT_SIGS\fR" - -.IX Item "\f(CWPTH_EVENT_TIME\fR" - -.IX Item "\f(CWPTH_EVENT_MSG\fR" - -.IX Item "\f(CWPTH_EVENT_TID\fR" - -.IX Item "\f(CWPTH_EVENT_FUNC\fR" - -.IX Item "unsigned long \fBpth_event_typeof\fR(pth_event_t \fIev\fR);" - -.IX Item "int \fBpth_event_extract\fR(pth_event_t \fIev\fR, ...);" - -.IX Item "pth_event_t \fBpth_event_concat\fR(pth_event_t \fIev\fR, ...);" - -.IX Item "pth_event_t \fBpth_event_isolate\fR(pth_event_t \fIev\fR);" - -.IX Item "pth_event_t \fBpth_event_walk\fR(pth_event_t \fIev\fR, int \fIdirection\fR);" - -.IX Item "int \fBpth_event_occurred\fR(pth_event_t \fIev\fR);" - -.IX Item "int \fBpth_event_free\fR(pth_event_t \fIev\fR, int \fImode\fR);" - -.IX Subsection "Key-Based Storage" - -.IX Item "int \fBpth_key_create\fR(pth_key_t *\fIkey\fR, void (*\fIfunc\fR)(void *));" - -.IX Item "int \fBpth_key_delete\fR(pth_key_t \fIkey\fR);" - -.IX Item "int \fBpth_key_setdata\fR(pth_key_t \fIkey\fR, const void *\fIvalue\fR);" - -.IX Item "void *\fBpth_key_getdata\fR(pth_key_t \fIkey\fR);" - -.IX Subsection "Message Port Communication" - -.IX Item "pth_msgport_t \fBpth_msgport_create\fR(const char *\fIname\fR);" - -.IX Item "void \fBpth_msgport_destroy\fR(pth_msgport_t \fImp\fR);" - -.IX Item "pth_msgport_t \fBpth_msgport_find\fR(const char *\fIname\fR);" - -.IX Item "int \fBpth_msgport_pending\fR(pth_msgport_t \fImp\fR);" - -.IX Item "int \fBpth_msgport_put\fR(pth_msgport_t \fImp\fR, pth_message_t *\fIm\fR);" - -.IX Item "pth_message_t *\fBpth_msgport_get\fR(pth_msgport_t \fImp\fR);" - -.IX Item "int \fBpth_msgport_reply\fR(pth_message_t *\fIm\fR);" - -.IX Subsection "Thread Cleanups" - -.IX Item "int \fBpth_cleanup_push\fR(void (*\fIhandler\fR)(void *), void *\fIarg\fR);" - -.IX Item "int \fBpth_cleanup_pop\fR(int \fIexecute\fR);" - -.IX Subsection "Process Forking" - -.IX Item "int \fBpth_atfork_push\fR(void (*\fIprepare\fR)(void *), void (*)(void *\fIparent\fR), void (*)(void *\fIchild\fR), void *\fIarg\fR);" - -.IX Item "int \fBpth_atfork_pop\fR(void);" - -.IX Item "pid_t \fBpth_fork\fR(void);" - -.IX Subsection "Synchronization" - -.IX Item "int \fBpth_mutex_init\fR(pth_mutex_t *\fImutex\fR);" - -.IX Item "int \fBpth_mutex_acquire\fR(pth_mutex_t *\fImutex\fR, int \fItry\fR, pth_event_t \fIev\fR);" - -.IX Item "int \fBpth_mutex_release\fR(pth_mutex_t *\fImutex\fR);" - -.IX Item "int \fBpth_rwlock_init\fR(pth_rwlock_t *\fIrwlock\fR);" - -.IX Item "int \fBpth_rwlock_acquire\fR(pth_rwlock_t *\fIrwlock\fR, int \fIop\fR, int \fItry\fR, pth_event_t \fIev\fR);" - -.IX Item "int \fBpth_rwlock_release\fR(pth_rwlock_t *\fIrwlock\fR);" - -.IX Item "int \fBpth_cond_init\fR(pth_cond_t *\fIcond\fR);" - -.IX Item "int \fBpth_cond_await\fR(pth_cond_t *\fIcond\fR, pth_mutex_t *\fImutex\fR, pth_event_t \fIev\fR);" - -.IX Item "int \fBpth_cond_notify\fR(pth_cond_t *\fIcond\fR, int \fIbroadcast\fR);" - -.IX Item "int \fBpth_barrier_init\fR(pth_barrier_t *\fIbarrier\fR, int I/dev/null --- pth.pod 2000/08/18 08:47:51 1.141 +++ pth.pod 2000/09/30 08:00:18 1.142 @@ -1478,7 +1478,7 @@ This is equal to pth_connect(3) (see below), but has an additional event argument I. When pth_connect(3) suspends the current threads execution it -usually only uses the I/O event on I to awake. With this function any +usually only uses the I/O event on I to awake. With this function any number of extra events can be used to awake the current thread (remember that I actually is an event I). @@ -1486,7 +1486,7 @@ This is equal to pth_accept(3) (see below), but has an additional event argument I. When pth_accept(3) suspends the current threads execution it -usually only uses the I/O event on I to awake. With this function any +usually only uses the I/O event on I to awake. With this function any number of extra events can be used to awake the current thread (remember that I actually is an event I).