pth.3 131 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 1651 1652 1653 1654 1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 1687 1688 1689 1690 1691 1692 1693 1694 1695 1696 1697 1698 1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726 1727 1728 1729 1730 1731 1732 1733 1734 1735 1736 1737 1738 1739 1740 1741 1742 1743 1744 1745 1746 1747 1748 1749 1750 1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 1761 1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 1794 1795 1796 1797 1798 1799 1800 1801 1802 1803 1804 1805 1806 1807 1808 1809 1810 1811 1812 1813 1814 1815 1816 1817 1818 1819 1820 1821 1822 1823 1824 1825 1826 1827 1828 1829 1830 1831 1832 1833 1834 1835 1836 1837 1838 1839 1840 1841 1842 1843 1844 1845 1846 1847 1848 1849 1850 1851 1852 1853 1854 1855 1856 1857 1858 1859 1860 1861 1862 1863 1864 1865 1866 1867 1868 1869 1870 1871 1872 1873 1874 1875 1876 1877 1878 1879 1880 1881 1882 1883 1884 1885 1886 1887 1888 1889 1890 1891 1892 1893 1894 1895 1896 1897 1898 1899 1900 1901 1902 1903 1904 1905 1906 1907 1908 1909 1910 1911 1912 1913 1914 1915 1916 1917 1918 1919 1920 1921 1922 1923 1924 1925 1926 1927 1928 1929 1930 1931 1932 1933 1934 1935 1936 1937 1938 1939 1940 1941 1942 1943 1944 1945 1946 1947 1948 1949 1950 1951 1952 1953 1954 1955 1956 1957 1958 1959 1960 1961 1962 1963 1964 1965 1966 1967 1968 1969 1970 1971 1972 1973 1974 1975 1976 1977 1978 1979 1980 1981 1982 1983 1984 1985 1986 1987 1988 1989 1990 1991 1992 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 2010 2011 2012 2013 2014 2015 2016 2017 2018 2019 2020 2021 2022 2023 2024 2025 2026 2027 2028 2029 2030 2031 2032 2033 2034 2035 2036 2037 2038 2039 2040 2041 2042 2043 2044 2045 2046 2047 2048 2049 2050 2051 2052 2053 2054 2055 2056 2057 2058 2059 2060 2061 2062 2063 2064 2065 2066 2067 2068 2069 2070 2071 2072 2073 2074 2075 2076 2077 2078 2079 2080 2081 2082 2083 2084 2085 2086 2087 2088 2089 2090 2091 2092 2093 2094 2095 2096 2097 2098 2099 2100 2101 2102 2103 2104 2105 2106 2107 2108 2109 2110 2111 2112 2113 2114 2115 2116 2117 2118 2119 2120 2121 2122 2123 2124 2125 2126 2127 2128 2129 2130 2131 2132 2133 2134 2135 2136 2137 2138 2139 2140 2141 2142 2143 2144 2145 2146 2147 2148 2149 2150 2151 2152 2153 2154 2155 2156 2157 2158 2159 2160 2161 2162 2163 2164 2165 2166 2167 2168 2169 2170 2171 2172 2173 2174 2175 2176 2177 2178 2179 2180 2181 2182 2183 2184 2185 2186 2187 2188 2189 2190 2191 2192 2193 2194 2195 2196 2197 2198 2199 2200 2201 2202 2203 2204 2205 2206 2207 2208 2209 2210 2211 2212 2213 2214 2215 2216 2217 2218 2219 2220 2221 2222 2223 2224 2225 2226 2227 2228 2229 2230 2231 2232 2233 2234 2235 2236 2237 2238 2239 2240 2241 2242 2243 2244 2245 2246 2247 2248 2249 2250 2251 2252 2253 2254 2255 2256 2257 2258 2259 2260 2261 2262 2263 2264 2265 2266 2267 2268 2269 2270 2271 2272 2273 2274 2275 2276 2277 2278 2279 2280 2281 2282 2283 2284 2285 2286 2287 2288 2289 2290 2291 2292 2293 2294 2295 2296 2297 2298 2299 2300 2301 2302 2303 2304 2305 2306 2307 2308 2309 2310 2311 2312 2313 2314 2315 2316 2317 2318 2319 2320 2321 2322 2323 2324 2325 2326 2327 2328 2329 2330 2331 2332 2333 2334 2335 2336 2337 2338 2339 2340 2341 2342 2343 2344 2345 2346 2347 2348 2349 2350 2351 2352 2353 2354 2355 2356 2357 2358 2359 2360 2361 2362 2363 2364 2365 2366 2367 2368 2369 2370 2371 2372 2373 2374 2375 2376 2377 2378 2379 2380 2381 2382 2383 2384 2385 2386 2387 2388 2389 2390 2391 2392 2393 2394 2395 2396 2397 2398 2399 2400 2401 2402 2403 2404 2405 2406 2407 2408 2409 2410 2411 2412 2413 2414 2415 2416 2417 2418 2419 2420 2421 2422
.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" 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" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" 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
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    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 #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    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 / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" 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 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'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.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
.    \" 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)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    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 "GNU Pth 2.0.7" "08-Jun-2006" "GNU Portable Threads"
.SH "NAME"
\&\fBpthsem\fR \- GNU Portable Threads
.SH "VERSION"
.IX Header "VERSION"
pthsem \s-12.0.7 (08-Jun-2006)\s0
based on \s-1GNU\s0 Pth
.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,
pth_attr_set,
pth_attr_get,
pth_attr_destroy.
.IP "\fBThread Control\fR" 4
.IX Item "Thread Control"
pth_spawn,
pth_once,
pth_self,
pth_suspend,
pth_resume,
pth_yield,
pth_nap,
pth_wait,
pth_cancel,
pth_abort,
pth_raise,
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,
pth_event_concat,
pth_event_isolate,
pth_event_walk,
pth_event_status,
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,
pth_msgport_pending,
pth_msgport_put,
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,
pth_rwlock_init,
pth_rwlock_acquire,
pth_rwlock_release,
pth_cond_init,
pth_cond_await,
pth_cond_notify,
pth_barrier_init,
pth_barrier_reach.
.IP "\fBSemaphore support\fR" 4
.IX Item "Semaphore support"
pth_sem_init,
pth_sem_dec,
pth_sem_dec_value,
pth_sem_inc,
pth_sem_inc_value,
pth_sem_set_value,
pth_sem_get_value.
.IP "\fBUser-Space Context\fR" 4
.IX Item "User-Space Context"
pth_uctx_create,
pth_uctx_make,
pth_uctx_switch,
pth_uctx_destroy.
.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,
pth_select_ev,
pth_poll_ev,
pth_read_ev,
pth_readv_ev,
pth_write_ev,
pth_writev_ev,
pth_recv_ev,
pth_recvfrom_ev,
pth_send_ev,
pth_sendto_ev.
.IP "\fBStandard \s-1POSIX\s0 Replacement \s-1API\s0\fR" 4
.IX Item "Standard POSIX Replacement API"
pth_nanosleep,
pth_usleep,
pth_sleep,
pth_waitpid,
pth_system,
pth_sigmask,
pth_sigwait,
pth_accept,
pth_connect,
pth_select,
pth_pselect,
pth_poll,
pth_read,
pth_readv,
pth_write,
pth_writev,
pth_pread,
pth_pwrite,
pth_recv,
pth_recvfrom,
pth_send,
pth_sendto.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
.Vb 5
\&  ____  _   _
\& |  _ \e| |_| |__
\& | |_) | __| '_ \e         ``Only those who attempt
\& |  __/| |_| | | |          the absurd can achieve
\& |_|    \e__|_| |_|          the impossible.''
.Ve
.PP
\&\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(CW\*(C`errno\*(C'\fR
variable.
.PP
The thread scheduling itself is done in a cooperative way, i.e., the threads
are managed and dispatched by a priority\- and event-driven non-preemptive
scheduler. The intention is that this way both better portability and run-time
performance is achieved than with preemptive scheduling. The event facility
allows threads to wait until various types of internal and external events
occur, including pending I/O on file descriptors, asynchronous signals,
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 \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' \*(-- 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).
These processes usually do \fInot\fR share a common address space. Instead
they are clearly separated from each other, and are created by direct
cloning a process address space (although modern kernels use memory
segment mapping and copy-on-write semantics to avoid unnecessary copying
of physical memory).
.PP
The drawbacks are obvious: Sharing data between the processes is
complicated, and can usually only be done efficiently through shared
memory (but which itself is not very portable). Synchronization is
complicated because of the preemptive nature of the Unix scheduler
(one has to use \fIatomic\fR locks, etc). The machine's resources can be
exhausted very quickly when the server application has to serve too many
long-running requests (heavy\-weight processes cost memory). And when
each request spawns a sub-process to handle it, the server performance
and responsiveness is horrible (heavy\-weight processes cost time to
spawn). Finally, the server application doesn't scale very well with the
load because of these resource problems. In practice, lots of tricks
are usually used to overcome these problems \- ranging from pre-forked
sub-process pools to semi-serialized processing, etc.
.PP
One of the most elegant ways to solve these resource\- and data-sharing
problems is to have multiple \fIlight-weight\fR threads of execution
inside a single (heavy\-weight) process, i.e., to use \fImultithreading\fR.
Those \fIthreads\fR usually improve responsiveness and performance of the
application, often improve and simplify the internal program structure,
and most important, require less system resources than heavy-weight
processes. Threads are neither the optimal run-time facility for all
types of applications, nor can all applications benefit from them. But
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.
.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
descriptor set\fR, \fIsignal table\fR. On every process switch, the kernel
saves and restores these ingredients for the individual processes. On
the other hand, a thread consists of only a private program counter,
stack memory, stack pointer and signal table. All other ingredients, in
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
the application's knowledge. Similarly, when threads are implemented in
user\-space, the thread context switches are performed by an application
library, without the kernel's knowledge. There also are hybrid threading
approaches where, typically, a user-space library binds one or more
user-space threads to one or more kernel-space threads (there usually
called light-weight processes \- or in short LWPs).
.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,
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(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
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,
the responsiveness of the system is considered good. When the user
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,
need to be carefully designed in order to be reentrant. Two traditional
approaches to solve these problems are caller-supplied states and
thread-specific data.
.Sp
Thread-safety is the avoidance of \fIdata races\fR, i.e., situations
in which data is set to either correct or incorrect value depending
upon the (unpredictable) order in which multiple threads access and
modify the data. So a function is thread-safe when it still behaves
semantically correct when called simultaneously by several threads (it
is not required that the functions also execute simultaneously). The
traditional approach to achieve thread-safety is to wrap a function body
with an internal mutual exclusion lock (aka `mutex'). As you should
recognize, reentrant is a stronger attribute than thread\-safe, because
it is harder to achieve and results especially in no run-time contention
between threads. So, a reentrant function is always thread\-safe, but not
vice versa.
.Sp
Additionally there is a related attribute for functions named
asynchronous\-safe, which comes into play in conjunction with signal
handlers. This is very related to the problem of reentrant functions. An
asynchronous-safe function is one that can be called safe and without
side-effects from within a signal handler context. Usually very few
functions are of this type, because an application is very restricted in
what it can perform from within a signal handler (especially what system
functions it is allowed to call). The reason mainly is, because only a
few system functions are officially declared by \s-1POSIX\s0 as guaranteed to
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
.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
milliseconds) and those units are implemented by separate functions.
Then a global matrix is defined which describes the execution (and
perhaps even dependency) order of these functions. The main server
procedure then just dispatches between these units by calling one
function after each other controlled by this matrix. The threads are
created by more than one jump-trail through this matrix and by switching
between these jump-trails controlled by corresponding occurred events.
.Sp
This approach gives the best possible performance, because one can
fine-tune the threads of execution by adjusting the matrix, and the
scheduling is done explicitly by the application itself. It is also very
portable, because the matrix is just an ordinary data structure, and
functions are a standard feature of \s-1ANSI\s0 C.
.Sp
The disadvantage of this approach is that it is complicated to write
large applications with this approach, because in those applications
one quickly gets hundreds(!) of execution units and the control flow
inside such an application is very hard to understand (because it is
interrupted by function borders and one always has to remember the
global dispatching matrix to follow it). Additionally, all threads
operate on the same execution stack. Although this saves memory, it is
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
.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
begin to the end without an interrupted control flow. But the control
flow can be still interrupted \- even in the middle of a function.
Actually in a preemptive way, similar to what the kernel does for the
heavy-weight processes, i.e., every few milliseconds the user-space
scheduler switches between the threads of execution. But the thread
itself doesn't recognize this and usually (except for synchronization
issues) doesn't have to care about this.
.Sp
The advantage of this approach is that it's very easy to program,
because the control flow and context of a thread directly follows
a procedure without forced interrupts through function borders.
Additionally, the programming is very similar to a traditional and well
understood \fIfork\fR\|(2) based approach.
.Sp
The disadvantage is that although the general performance is increased,
compared to using approaches based on heavy-weight processes, it is decreased
compared to the matrix-approach above. Because the implicit preemptive
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\-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
code and other nasty internals and are not easy to port to forthcoming
platforms.
.PP
So, in short: the matrix-dispatching approach is portable and fast, but
nasty to program. The thread scheduling approach is easy to program,
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
preemptive scheduling by using non-preemptive scheduling instead.
.PP
This sounds like, and is, a useful approach. Nevertheless, one has to
keep the implications of non-preemptive thread scheduling in mind when
working with \fBPth\fR. The following list summarizes a few essential
points:
.IP "\fBo\fR" 2
.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\-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(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
.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'. 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
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
.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
reentered before it returned. This is a great portability benefit,
because thread-safety can be achieved more easily than reentrance
possibility. Especially this means that under \fBPth\fR more existing
third-party libraries can be used without side-effects than it's the case
for other threading systems.
.IP "\fBo\fR" 2
.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
kernel does not need to be aware of the \fBPth\fR threads (because they
are implemented entirely in user\-space). On the other hand, it cannot
benefit from the existence of multiprocessors, because for this, kernel
support would be needed. In practice, this is no problem, because
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
graph:
.PP
.Vb 10
\&             NEW
\&              |
\&              V
\&      +\-\-\-> READY \-\-\-+
\&      |       ^      |
\&      |       |      V
\&   WAITING <\-\-+\-\- RUNNING
\&                     |
\&      :              V
\&   SUSPENDED       DEAD
.Ve
.PP
When a new thread is created, it is moved into the \fB\s-1NEW\s0\fR queue of the
scheduler. On the next dispatching for this thread, the scheduler picks
it up from there and moves it to the \fB\s-1READY\s0\fR queue. This is a queue
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'.
.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
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
possibilities: Either it has terminated, then it is moved to the \fB\s-1DEAD\s0\fR
queue, or it has events on which it wants to wait, then it is moved into
the \fB\s-1WAITING\s0\fR queue. Else it is assumed it wants to perform more \s-1CPU\s0
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
occurred, the threads that are waiting on them are immediately moved to
the \fB\s-1READY\s0\fR queue.
.PP
The purpose of the \fB\s-1NEW\s0\fR queue has to do with the fact that in \fBPth\fR
a thread never directly switches to another thread. A thread always
yields execution to the scheduler and the scheduler dispatches to the
next thread. So a freshly spawned thread has to be kept somewhere until
the scheduler gets a chance to pick it up for scheduling. That is
what the \fB\s-1NEW\s0\fR queue is for.
.PP
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.
.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
queues by the application. The purpose of this special queue is to
temporarily absorb suspended threads until they are again resumed by
the application. Suspended threads do not cost scheduling or event
handling resources, because they are temporarily completely out of the
scheduler's scope. If a thread is resumed, it is moved back to the queue
from where it originally came and this way again enters the schedulers
scope.
.SH "APPLICATION PROGRAMMING INTERFACE (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 now
be 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(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' 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(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(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(CW\*(C`FALSE\*(C'\fR if it is not called from within the main thread. Else it
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(CW\*(C`PTH_CTRL_\*(C'\fR\fI\s-1XXXX\s0\fR
queries. Currently the following queries are supported:
.RS 4
.ie n .IP """PTH_CTRL_GETTHREADS""" 4
.el .IP "\f(CWPTH_CTRL_GETTHREADS\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(CW\*(C`PTH_CTRL_GETTHREADS\*(C'\fR query is equal to the
OR-combination of all the following specialized queries:
.Sp
\&\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(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(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(CW\*(C`PTH_CTRL_GETTHREADS_SUSPENDED\*(C'\fR for the number of
threads in the suspended queue (threads waiting to be resumed) and
\&\f(CW\*(C`PTH_CTRL_GETTHREADS_DEAD\*(C'\fR for the number of threads in the new queue
(terminated threads waiting for a join).
.ie n .IP """PTH_CTRL_GETAVLOAD""" 4
.el .IP "\f(CWPTH_CTRL_GETAVLOAD\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.
So a load around 1.0 means there is only one ready thread (the standard
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.
.ie n .IP """PTH_CTRL_GETPRIO""" 4
.el .IP "\f(CWPTH_CTRL_GETPRIO\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.
.ie n .IP """PTH_CTRL_GETNAME""" 4
.el .IP "\f(CWPTH_CTRL_GETNAME\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(CW\*(C`char *\*(C'\fR'.
.ie n .IP """PTH_CTRL_DUMPSTATE""" 4
.el .IP "\f(CWPTH_CTRL_DUMPSTATE\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.
.ie n .IP """PTH_CTRL_FAVOURNEW""" 4
.el .IP "\f(CWPTH_CTRL_FAVOURNEW\fR" 4
.IX Item "PTH_CTRL_FAVOURNEW"
This requires a second argument of type `\f(CW\*(C`int\*(C'\fR' which specified whether
the \fB\s-1GNU\s0 Pth\fR scheduler favours new threads on startup, i.e., whether
they are moved from the new queue to the top (argument is \f(CW\*(C`TRUE\*(C'\fR) or
middle (argument is \f(CW\*(C`FALSE\*(C'\fR) of the ready queue. The default is to
favour new threads to make sure they do not starve already at startup,
although this slightly violates the strict priority based scheduling.
.RE
.RS 4
.Sp
The function returns \f(CW\*(C`\-1\*(C'\fR on error.
.RE
.IP "long \fBpth_version\fR(void);" 4
.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,
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(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:
.ie n .IP """PTH_ATTR_PRIO""\fR (read\-write) [\f(CW""int""]" 4
.el .IP "\f(CWPTH_ATTR_PRIO\fR (read\-write) [\f(CWint\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.
.ie n .IP """PTH_ATTR_NAME""\fR (read\-write) [\f(CW""char *""]" 4
.el .IP "\f(CWPTH_ATTR_NAME\fR (read\-write) [\f(CWchar *\fR]" 4
.IX Item "PTH_ATTR_NAME (read-write) [char *]"
Name of thread (up to 40 characters are stored only), mainly for debugging
purposes.
.ie n .IP """PTH_ATTR_DISPATCHES""\fR (read\-write) [\f(CW""int""]" 4
.el .IP "\f(CWPTH_ATTR_DISPATCHES\fR (read\-write) [\f(CWint\fR]" 4
.IX Item "PTH_ATTR_DISPATCHES (read-write) [int]"
In bounded attribute objects, this field is incremented every time the
context is switched to the associated thread.
.ie n .IP """PTH_ATTR_JOINABLE""\fR (read\-write> [\f(CW""int""]" 4
.el .IP "\f(CWPTH_ATTR_JOINABLE\fR (read\-write> [\f(CWint\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 thread is detached,
after termination it is immediately kicked out of the system instead of
inserted into the dead queue.
.ie n .IP """PTH_ATTR_CANCEL_STATE""\fR (read\-write) [\f(CW""unsigned int""]" 4
.el .IP "\f(CWPTH_ATTR_CANCEL_STATE\fR (read\-write) [\f(CWunsigned int\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.
.ie n .IP """PTH_ATTR_STACK_SIZE""\fR (read\-write) [\f(CW""unsigned int""]" 4
.el .IP "\f(CWPTH_ATTR_STACK_SIZE\fR (read\-write) [\f(CWunsigned int\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!
.ie n .IP """PTH_ATTR_STACK_ADDR""\fR (read\-write) [\f(CW""char *""]" 4
.el .IP "\f(CWPTH_ATTR_STACK_ADDR\fR (read\-write) [\f(CWchar *\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.
.ie n .IP """PTH_ATTR_TIME_SPAWN""\fR (read\-only) [\f(CW""pth_time_t""]" 4
.el .IP "\f(CWPTH_ATTR_TIME_SPAWN\fR (read\-only) [\f(CWpth_time_t\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.
.ie n .IP """PTH_ATTR_TIME_LAST""\fR (read\-only) [\f(CW""pth_time_t""]" 4
.el .IP "\f(CWPTH_ATTR_TIME_LAST\fR (read\-only) [\f(CWpth_time_t\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.
.ie n .IP """PTH_ATTR_TIME_RAN""\fR (read\-only) [\f(CW""pth_time_t""]" 4
.el .IP "\f(CWPTH_ATTR_TIME_RAN\fR (read\-only) [\f(CWpth_time_t\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.
.ie n .IP """PTH_ATTR_START_FUNC""\fR (read\-only) [\f(CW""void *(*)(void *)""]" 4
.el .IP "\f(CWPTH_ATTR_START_FUNC\fR (read\-only) [\f(CWvoid *(*)(void *)\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.
.ie n .IP """PTH_ATTR_START_ARG""\fR (read\-only) [\f(CW""void *""]" 4
.el .IP "\f(CWPTH_ATTR_START_ARG\fR (read\-only) [\f(CWvoid *\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.
.ie n .IP """PTH_ATTR_STATE""\fR (read\-only) [\f(CW""pth_state_t""]" 4
.el .IP "\f(CWPTH_ATTR_STATE\fR (read\-only) [\f(CWpth_state_t\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.
.ie n .IP """PTH_ATTR_EVENTS""\fR (read\-only) [\f(CW""pth_event_t""]" 4
.el .IP "\f(CWPTH_ATTR_EVENTS\fR (read\-only) [\f(CWpth_event_t\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.
.ie n .IP """PTH_ATTR_BOUND""\fR (read\-only) [\f(CW""int""]" 4
.el .IP "\f(CWPTH_ATTR_BOUND\fR (read\-only) [\f(CWint\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 can be used 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(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_DISPATCHES\*(C'\fR := \f(CW0\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
be used:
.Sp
.Vb 7
\& PTH_ATTR_PRIO           int
\& PTH_ATTR_NAME           char *
\& PTH_ATTR_DISPATCHES     int
\& PTH_ATTR_JOINABLE       int
\& PTH_ATTR_CANCEL_STATE   unsigned int
\& PTH_ATTR_STACK_SIZE     unsigned int
\& 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
argument pairs can be used:
.Sp
.Vb 15
\& PTH_ATTR_PRIO           int *
\& PTH_ATTR_NAME           char **
\& PTH_ATTR_DISPATCHES     int *
\& PTH_ATTR_JOINABLE       int *
\& PTH_ATTR_CANCEL_STATE   unsigned int *
\& PTH_ATTR_STACK_SIZE     unsigned int *
\& PTH_ATTR_STACK_ADDR     char **
\& PTH_ATTR_TIME_SPAWN     pth_time_t *
\& PTH_ATTR_TIME_LAST      pth_time_t *
\& PTH_ATTR_TIME_RAN       pth_time_t *
\& PTH_ATTR_START_FUNC     void *(**)(void *)
\& PTH_ATTR_START_ARG      void **
\& PTH_ATTR_STATE          pth_state_t *
\& PTH_ATTR_EVENTS         pth_event_t *
\& 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 make up 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(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; the dispatch count is not inherited from
the current thread if \fIattr\fR is not specified \- rather, it is initialized
to zero.  This entry routine is called as `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 can also 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.
.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(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(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(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
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(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
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(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(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
can be reasonable to interrupt it explicitly by doing a few \fIpth_yield\fR\|(3) calls
to give other threads a chance to execute, too.  This obviously is the
cooperating part of \fBPth\fR.  A thread \fIhas not\fR to yield execution, of
course. But when you want to program a server application with good response
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(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(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(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(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 an 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(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
of the non-preemptive nature of \fBPth\fR it can last longer (when another thread
kept the \s-1CPU\s0 for a long time). Additionally the resolution is dependent of the
implementation of timers by the operating system and these usually have only a
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)
on which the current thread wants to wait. The scheduler awakes the
thread when one ore more of them occurred or failed after tagging
them as such. The \fIev\fR argument is a \fIpointer\fR to an event ring
which isn't changed except for the tagging. \fIpth_wait\fR\|(3) returns the
number of occurred or failed events and the application can use
\&\fIpth_event_status\fR\|(3) to test which events occurred or failed.
.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(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(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(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(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(CW\*(C`NULL\*(C'\fR) and
returns to the caller. A thread can be joined only when it has the
attribute \f(CW\*(C`PTH_ATTR_JOINABLE\*(C'\fR set to \f(CW\*(C`TRUE\*(C'\fR (the default). A thread
can only be joined once, i.e., after the \fIpth_join\fR\|(3) call the thread
\&\fItid\fR is completely 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. If it has the
attribute \f(CW\*(C`PTH_ATTR_JOINABLE\*(C'\fR set to \f(CW\*(C`FALSE\*(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 subsequent \fIpth_join\fR\|(3) call by another
thread.
.Sh "Utilities"
.IX Subsection "Utilities"
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(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
.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
.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.
.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\*(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(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(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"
.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(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(CW0\fR it sets the
new cancellation state. \fIoldstate\fR is created before \fInewstate\fR is set.  A
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(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(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(CW\*(C`pth_exit(PTH_CANCELED)\*(C'\fR'.
.Sh "Event Handling"
.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:
.RS 4
.ie n .IP """PTH_EVENT_FD""" 4
.el .IP "\f(CWPTH_EVENT_FD\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_EXCEPTION\*(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(CW\*(C`pth_event(PTH_EVENT_FD|PTH_UNTIL_FD_READABLE, fd)\*(C'\fR'.
.ie n .IP """PTH_EVENT_SELECT""" 4
.el .IP "\f(CWPTH_EVENT_SELECT\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
file descriptor for a different type of state. Additionally as a nice
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(CW\*(C`PTH_EVENT_TIME\*(C'\fR events).
.Sp
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.
.ie n .IP """PTH_EVENT_SIGS""" 4
.el .IP "\f(CWPTH_EVENT_SIGS\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(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(CW\*(C`sigemptyset(&set); sigaddset(&set, SIGINT);
pth_event(PTH_EVENT_SIG, &set, &sig);\*(C'\fR'.
.ie n .IP """PTH_EVENT_TIME""" 4
.el .IP "\f(CWPTH_EVENT_TIME\fR" 4
.IX Item "PTH_EVENT_TIME"
This is a time point event. The additional argument has to be of type
\&\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(CW\*(C`pth_event(PTH_EVENT_TIME, pth_timeout(2,0))\*(C'\fR'.
.ie n .IP """PTH_EVENT_MSG""" 4
.el .IP "\f(CWPTH_EVENT_MSG\fR" 4
.IX Item "PTH_EVENT_MSG"
This is a message port event. The additional argument has to be of type
\&\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'.
.ie n .IP """PTH_EVENT_TID""" 4
.el .IP "\f(CWPTH_EVENT_TID\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(CW\*(C`pth_event(PTH_EVENT_TID|PTH_UNTIL_TID_DEAD, tid)\*(C'\fR'.
.ie n .IP """PTH_EVENT_FUNC""" 4
.el .IP "\f(CWPTH_EVENT_FUNC\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(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(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(CW\*(C`pth_event(PTH_EVENT_FUNC, func, arg, pth_time(0,500000))\*(C'\fR'.
.ie n .IP """PTH_EVENT_SEM""" 4
.el .IP "\f(CWPTH_EVENT_SEM\fR" 4
.IX Item "PTH_EVENT_SEM"
This is a semaphore event. It waits for a semaphore, until it can be
decremented. By default 1 is used for this, with the flag
\&\f(CW\*(C`PTH_UNTIL_COUNT\*(C'\fR other values can be used. If the flag
\&\f(CW\*(C`PTH_UNTIL_DECREMENT\*(C'\fR is used, the semaphore value is decremented (so
the lock is obtained), else the event is signaled, if it would be
possible. Examples:
.Sp
* pth_event(PTH_EVENT_SEM|PTH_UNTIL_DECREMENT|PTH_UNTIL_COUNT, &sem,2):
event waits, utils the value of the semaphore is >= 2 and subtracts then two from it
.Sp
* pth_event(PTH_EVENT_SEM|PTH_UNTIL_COUNT, &sem,2):
event waits, util the value of the semaphore is >= 2
.Sp
* pth_event(PTH_EVENT_SEM|PTH_UNTIL_DECREMENT, &sem):
event waits, util the value of the semaphore is >= 1 and subtracts then 1 from it
.Sp
* pth_event(\s-1PTH_EVENT_SEM\s0, &sem):
event waits, util the value of the semaphore is >= 1
.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(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
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(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(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(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
.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 "pth_status_t \fBpth_event_status\fR(pth_event_t \fIev\fR);" 4
.IX Item "pth_status_t pth_event_status(pth_event_t ev);"
This returns the status of event \fIev\fR. 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. The
possible returned status codes are: \f(CW\*(C`PTH_STATUS_PENDING\*(C'\fR (event is
still pending), \f(CW\*(C`PTH_STATUS_OCCURRED\*(C'\fR (event successfully occurred),
\&\f(CW\*(C`PTH_STATUS_FAILED\*(C'\fR (event failed).
.IP "int \fBpth_event_free\fR(pth_event_t \fIev\fR, int \fImode\fR);" 4
.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(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. If name \fIname\fR
is not \f(CW\*(C`NULL\*(C'\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"
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(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
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(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
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(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
the calling thread. When you really want to duplicate all threads in the
current process you should use \fIfork\fR\|(2) directly. But this is usually not
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
system like \fBPth\fR this might sound unnecessary at the first look, because a
thread isn't interrupted by the system. Actually when you have a critical code
section which doesn't contain any \fIpth_xxx()\fR functions, you don't need any
mutex to protect it, of course.
.PP
But when your critical code section contains any \fIpth_xxx()\fR function the chance
is high that these temporarily switch to the scheduler. And this way other
threads can make progress and enter your critical code section, too.  This is
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
.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(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(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(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
.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(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(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(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(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 \fIthreshold\fR);" 4
.IX Item "int pth_barrier_init(pth_barrier_t *barrier, int threshold);"
This dynamically initializes a barrier variable of type `\f(CW\*(C`pth_barrier_t\*(C'\fR'.
Alternatively one can also use static initialization via `\f(CW\*(C`pth_barrier_t
barrier = PTH_BARRIER_INIT(\*(C'\fR\fIthreadhold\fR\f(CW\*(C`)\*(C'\fR'.
.IP "int \fBpth_barrier_reach\fR(pth_barrier_t *\fIbarrier\fR);" 4
.IX Item "int pth_barrier_reach(pth_barrier_t *barrier);"
This function reaches a barrier \fIbarrier\fR. If this is the last thread (as
specified by \fIthreshold\fR on init of \fIbarrier\fR) all threads are awakened.
Else the current thread is suspended until the last thread reached the barrier
and this way awakes all threads. The function returns (beside \f(CW\*(C`FALSE\*(C'\fR on
error) the value \f(CW\*(C`TRUE\*(C'\fR for any thread which neither reached the barrier as
the first nor the last thread; \f(CW\*(C`PTH_BARRIER_HEADLIGHT\*(C'\fR for the thread which
reached the barrier as the first thread and \f(CW\*(C`PTH_BARRIER_TAILLIGHT\*(C'\fR for the
thread which reached the barrier as the last thread.
.Sh "Semaphore support"
.IX Subsection "Semaphore support"
The interface provides functions to set/get the value of a semaphore,
increment it with arbitrary values, wait, until the value becomes
bigger than a given value (without or with decrementing, if the
condition becomes true.
.PP
The data-type for the semaphore is names \f(CW\*(C`pth_sem_t\*(C'\fR and it has an
initializer like \f(CW\*(C`pth_cond_t\*(C'\fR.
.IP "int \fBpth_sem_init\fR(pth_sem_t *sem);" 4
.IX Item "int pth_sem_init(pth_sem_t *sem);"
This dynamically initializes a semaphore variable of type `\f(CW\*(C`pth_sem_t\*(C'\fR'.
Alternatively one can also use static initialization via `\f(CW\*(C`pth_sem_t
semaphore = PTH_SEM_INIT\*(C'\fR'.
.IP "int \fBpth_sem_dec\fR(pth_sem_t *sem);" 4
.IX Item "int pth_sem_dec(pth_sem_t *sem);"
waits, until the value of \f(CW\*(C`sem\*(C'\fR is >= 1 and decrement it.
.IP "int \fBpth_sem_dec_value\fR(pth_sem_t *sem, unsigned value);" 4
.IX Item "int pth_sem_dec_value(pth_sem_t *sem, unsigned value);"
waits, until the value of \f(CW\*(C`sem\*(C'\fR is >= \f(CW\*(C`value\*(C'\fR and subtracts \f(CW\*(C`value\*(C'\fR.
.IP "int \fBpth_sem_inc\fR(pth_sem_t *sem, int notify);" 4
.IX Item "int pth_sem_inc(pth_sem_t *sem, int notify);"
increments \f(CW\*(C`sem\*(C'\fR. The scheduler is started, if \f(CW\*(C`notify\*(C'\fR is not null.
.IP "int \fBpth_sem_inc_value\fR(pth_sem_t *sem, unsigned value, int notify);" 4
.IX Item "int pth_sem_inc_value(pth_sem_t *sem, unsigned value, int notify);"
adds value to \f(CW\*(C`sem\*(C'\fR. The scheduler is started, if \f(CW\*(C`notify\*(C'\fR is not null.
.IP "int \fBpth_sem_set_value\fR(pth_sem_t *sem, unsigned value);" 4
.IX Item "int pth_sem_set_value(pth_sem_t *sem, unsigned value);"
sets the value of \f(CW\*(C`sem\*(C'\fR to \f(CW\*(C`value\*(C'\fR.
.IP "int \fBpth_sem_get_value\fR(pth_sem_t *sem, unsigned *value);" 4
.IX Item "int pth_sem_get_value(pth_sem_t *sem, unsigned *value);"
stores the value of \f(CW\*(C`sem\*(C'\fR in *\f(CW\*(C`value\*(C'\fR.
.Sh "User-Space Context"
.IX Subsection "User-Space Context"
The following functions provide a stand-alone sub-API for user-space
context switching. It internally is based on the same underlying machine
context switching mechanism the threads in \fB\s-1GNU\s0 Pth\fR are based on.
Hence these functions you can use for implementing your own simple
user-space threads. The \f(CW\*(C`pth_uctx_t\*(C'\fR context is somewhat modeled after
\&\s-1POSIX\s0 \fIucontext\fR\|(3).
.PP
The time required to create (via \fIpth_uctx_make\fR\|(3)) a user-space context
can range from just a few microseconds up to a more dramatical time
(depending on the machine context switching method which is available on
the platform). On the other hand, the raw performance in switching the
user-space contexts is always very good (nearly independent of the used
machine context switching method). For instance, on an Intel Pentium-III
\&\s-1CPU\s0 with 800Mhz running under FreeBSD 4 one usually achieves about
260,000 user-space context switches (via \fIpth_uctx_switch\fR\|(3)) per second.
.IP "int \fBpth_uctx_create\fR(pth_uctx_t *\fIuctx\fR);" 4
.IX Item "int pth_uctx_create(pth_uctx_t *uctx);"
This function creates a user-space context and stores it into \fIuctx\fR.
There is still no underlying user-space context configured. You still
have to do this with \fIpth_uctx_make\fR\|(3). On success, this function returns
\&\f(CW\*(C`TRUE\*(C'\fR, else \f(CW\*(C`FALSE\*(C'\fR.
.IP "int \fBpth_uctx_make\fR(pth_uctx_t \fIuctx\fR, char *\fIsk_addr\fR, size_t \fIsk_size\fR, const sigset_t *\fIsigmask\fR, void (*\fIstart_func\fR)(void *), void *\fIstart_arg\fR, pth_uctx_t \fIuctx_after\fR);" 4
.IX Item "int pth_uctx_make(pth_uctx_t uctx, char *sk_addr, size_t sk_size, const sigset_t *sigmask, void (*start_func)(void *), void *start_arg, pth_uctx_t uctx_after);"
This function makes a new user-space context in \fIuctx\fR which will
operate on the run-time stack \fIsk_addr\fR (which is of maximum
size \fIsk_size\fR), with the signals in \fIsigmask\fR blocked (if
\&\fIsigmask\fR is not \f(CW\*(C`NULL\*(C'\fR) and starting to execute with the call
\&\fIstart_func\fR(\fIstart_arg\fR). If \fIsk_addr\fR is \f(CW\*(C`NULL\*(C'\fR, a stack
is dynamically allocated. The stack size \fIsk_size\fR has to be at
least 16384 (16KB). If the start function \fIstart_func\fR returns and
\&\fIuctx_after\fR is not \f(CW\*(C`NULL\*(C'\fR, an implicit user-space context switch
to this context is performed. Else (if \fIuctx_after\fR is \f(CW\*(C`NULL\*(C'\fR) the
process is terminated with \fIexit\fR\|(3). This function is somewhat modeled
after \s-1POSIX\s0 \fImakecontext\fR\|(3). On success, this function returns \f(CW\*(C`TRUE\*(C'\fR,
else \f(CW\*(C`FALSE\*(C'\fR.
.IP "int \fBpth_uctx_switch\fR(pth_uctx_t \fIuctx_from\fR, pth_uctx_t \fIuctx_to\fR);" 4
.IX Item "int pth_uctx_switch(pth_uctx_t uctx_from, pth_uctx_t uctx_to);"
This function saves the current user-space context in \fIuctx_from\fR for
later restoring by another call to \fIpth_uctx_switch\fR\|(3) and restores
the new user-space context from \fIuctx_to\fR, which previously had to
be set with either a previous call to \fIpth_uctx_switch\fR\|(3) or initially
by \fIpth_uctx_make\fR\|(3). This function is somewhat modeled after \s-1POSIX\s0
\&\fIswapcontext\fR\|(3). If \fIuctx_from\fR or \fIuctx_to\fR are \f(CW\*(C`NULL\*(C'\fR or if
\&\fIuctx_to\fR contains no valid user-space context, \f(CW\*(C`FALSE\*(C'\fR is returned
instead of \f(CW\*(C`TRUE\*(C'\fR. These are the only errors possible.
.IP "int \fBpth_uctx_destroy\fR(pth_uctx_t \fIuctx\fR);" 4
.IX Item "int pth_uctx_destroy(pth_uctx_t uctx);"
This function destroys the user-space context in \fIuctx\fR. The run-time
stack associated with the user-space context is deallocated only if it
was not given by the application (see \fIsk_addr\fR of \fIpth_uctx_create\fR\|(3)).
If \fIuctx\fR is \f(CW\*(C`NULL\*(C'\fR, \f(CW\*(C`FALSE\*(C'\fR is returned instead of \f(CW\*(C`TRUE\*(C'\fR. This is
the only error possible.
.Sh "Generalized \s-1POSIX\s0 Replacement \s-1API\s0"
.IX Subsection "Generalized POSIX Replacement API"
The following functions are generalized replacements functions for the \s-1POSIX\s0
\&\s-1API\s0, i.e., they are similar to the functions under `\fBStandard \s-1POSIX\s0
Replacement \s-1API\s0\fR' but all have an additional event argument which can be used
for timeouts, etc.
.IP "int \fBpth_sigwait_ev\fR(const sigset_t *\fIset\fR, int *\fIsig\fR, pth_event_t \fIev\fR);" 4
.IX Item "int pth_sigwait_ev(const sigset_t *set, int *sig, pth_event_t ev);"
This is equal to \fIpth_sigwait\fR\|(3) (see below), but has an additional event
argument \fIev\fR. When \fIpth_sigwait\fR\|(3) suspends the current threads execution it
usually only uses the signal event on \fIset\fR to awake. With this function any
number of extra events can be used to awake the current thread (remember that
\&\fIev\fR actually is an event \fIring\fR).
.IP "int \fBpth_connect_ev\fR(int \fIs\fR, const struct sockaddr *\fIaddr\fR, socklen_t \fIaddrlen\fR, pth_event_t \fIev\fR);" 4
.IX Item "int pth_connect_ev(int s, const struct sockaddr *addr, socklen_t addrlen, pth_event_t ev);"
This is equal to \fIpth_connect\fR\|(3) (see below), but has an additional event
argument \fIev\fR. When \fIpth_connect\fR\|(3) suspends the current threads execution it
usually only uses the I/O event on \fIs\fR to awake. With this function any
number of extra events can be used to awake the current thread (remember that
\&\fIev\fR actually is an event \fIring\fR).
.IP "int \fBpth_accept_ev\fR(int \fIs\fR, struct sockaddr *\fIaddr\fR, socklen_t *\fIaddrlen\fR, pth_event_t \fIev\fR);" 4
.IX Item "int pth_accept_ev(int s, struct sockaddr *addr, socklen_t *addrlen, pth_event_t ev);"
This is equal to \fIpth_accept\fR\|(3) (see below), but has an additional event
argument \fIev\fR. When \fIpth_accept\fR\|(3) suspends the current threads execution it
usually only uses the I/O event on \fIs\fR to awake. With this function any
number of extra events can be used to awake the current thread (remember that
\&\fIev\fR actually is an event \fIring\fR).
.IP "int \fBpth_select_ev\fR(int \fInfd\fR, fd_set *\fIrfds\fR, fd_set *\fIwfds\fR, fd_set *\fIefds\fR, struct timeval *\fItimeout\fR, pth_event_t \fIev\fR);" 4
.IX Item "int pth_select_ev(int nfd, fd_set *rfds, fd_set *wfds, fd_set *efds, struct timeval *timeout, pth_event_t ev);"
This is equal to \fIpth_select\fR\|(3) (see below), but has an additional event
argument \fIev\fR. When \fIpth_select\fR\|(3) suspends the current threads execution it
usually only uses the I/O event on \fIrfds\fR, \fIwfds\fR and \fIefds\fR to awake. With
this function any number of extra events can be used to awake the current
thread (remember that \fIev\fR actually is an event \fIring\fR).
.IP "int \fBpth_poll_ev\fR(struct pollfd *\fIfds\fR, unsigned int \fInfd\fR, int \fItimeout\fR, pth_event_t \fIev\fR);" 4
.IX Item "int pth_poll_ev(struct pollfd *fds, unsigned int nfd, int timeout, pth_event_t ev);"
This is equal to \fIpth_poll\fR\|(3) (see below), but has an additional event argument
\&\fIev\fR. When \fIpth_poll\fR\|(3) suspends the current threads execution it usually only
uses the I/O event on \fIfds\fR to awake. With this function any number of extra
events can be used to awake the current thread (remember that \fIev\fR actually
is an event \fIring\fR).
.IP "ssize_t \fBpth_read_ev\fR(int \fIfd\fR, void *\fIbuf\fR, size_t \fInbytes\fR, pth_event_t \fIev\fR);" 4
.IX Item "ssize_t pth_read_ev(int fd, void *buf, size_t nbytes, pth_event_t ev);"
This is equal to \fIpth_read\fR\|(3) (see below), but has an additional event argument
\&\fIev\fR. When \fIpth_read\fR\|(3) suspends the current threads execution it usually only
uses the I/O event on \fIfd\fR to awake. With this function any number of extra
events can be used to awake the current thread (remember that \fIev\fR actually
is an event \fIring\fR).
.IP "ssize_t \fBpth_readv_ev\fR(int \fIfd\fR, const struct iovec *\fIiovec\fR, int \fIiovcnt\fR, pth_event_t \fIev\fR);" 4
.IX Item "ssize_t pth_readv_ev(int fd, const struct iovec *iovec, int iovcnt, pth_event_t ev);"
This is equal to \fIpth_readv\fR\|(3) (see below), but has an additional event
argument \fIev\fR. When \fIpth_readv\fR\|(3) suspends the current threads execution it
usually only uses the I/O event on \fIfd\fR to awake. With this function any
number of extra events can be used to awake the current thread (remember that
\&\fIev\fR actually is an event \fIring\fR).
.IP "ssize_t \fBpth_write_ev\fR(int \fIfd\fR, const void *\fIbuf\fR, size_t \fInbytes\fR, pth_event_t \fIev\fR);" 4
.IX Item "ssize_t pth_write_ev(int fd, const void *buf, size_t nbytes, pth_event_t ev);"
This is equal to \fIpth_write\fR\|(3) (see below), but has an additional event argument
\&\fIev\fR. When \fIpth_write\fR\|(3) suspends the current threads execution it usually
only uses the I/O event on \fIfd\fR to awake. With this function any number of
extra events can be used to awake the current thread (remember that \fIev\fR
actually is an event \fIring\fR).
.IP "ssize_t \fBpth_writev_ev\fR(int \fIfd\fR, const struct iovec *\fIiovec\fR, int \fIiovcnt\fR, pth_event_t \fIev\fR);" 4
.IX Item "ssize_t pth_writev_ev(int fd, const struct iovec *iovec, int iovcnt, pth_event_t ev);"
This is equal to \fIpth_writev\fR\|(3) (see below), but has an additional event
argument \fIev\fR. When \fIpth_writev\fR\|(3) suspends the current threads execution it
usually only uses the I/O event on \fIfd\fR to awake. With this function any
number of extra events can be used to awake the current thread (remember that
\&\fIev\fR actually is an event \fIring\fR).
.IP "ssize_t \fBpth_recv_ev\fR(int \fIfd\fR, void *\fIbuf\fR, size_t \fInbytes\fR, int \fIflags\fR, pth_event_t \fIev\fR);" 4
.IX Item "ssize_t pth_recv_ev(int fd, void *buf, size_t nbytes, int flags, pth_event_t ev);"
This is equal to \fIpth_recv\fR\|(3) (see below), but has an additional event
argument \fIev\fR. When \fIpth_recv\fR\|(3) suspends the current threads execution it
usually only uses the I/O event on \fIfd\fR to awake. With this function any
number of extra events can be used to awake the current thread (remember that
\&\fIev\fR actually is an event \fIring\fR).
.IP "ssize_t \fBpth_recvfrom_ev\fR(int \fIfd\fR, void *\fIbuf\fR, size_t \fInbytes\fR, int \fIflags\fR, struct sockaddr *\fIfrom\fR, socklen_t *\fIfromlen\fR, pth_event_t \fIev\fR);" 4
.IX Item "ssize_t pth_recvfrom_ev(int fd, void *buf, size_t nbytes, int flags, struct sockaddr *from, socklen_t *fromlen, pth_event_t ev);"
This is equal to \fIpth_recvfrom\fR\|(3) (see below), but has an additional event
argument \fIev\fR. When \fIpth_recvfrom\fR\|(3) suspends the current threads execution it
usually only uses the I/O event on \fIfd\fR to awake. With this function any
number of extra events can be used to awake the current thread (remember that
\&\fIev\fR actually is an event \fIring\fR).
.IP "ssize_t \fBpth_send_ev\fR(int \fIfd\fR, const void *\fIbuf\fR, size_t \fInbytes\fR, int \fIflags\fR, pth_event_t \fIev\fR);" 4
.IX Item "ssize_t pth_send_ev(int fd, const void *buf, size_t nbytes, int flags, pth_event_t ev);"
This is equal to \fIpth_send\fR\|(3) (see below), but has an additional event
argument \fIev\fR. When \fIpth_send\fR\|(3) suspends the current threads execution it
usually only uses the I/O event on \fIfd\fR to awake. With this function any
number of extra events can be used to awake the current thread (remember that
\&\fIev\fR actually is an event \fIring\fR).
.IP "ssize_t \fBpth_sendto_ev\fR(int \fIfd\fR, const void *\fIbuf\fR, size_t \fInbytes\fR, int \fIflags\fR, const struct sockaddr *\fIto\fR, socklen_t \fItolen\fR, pth_event_t \fIev\fR);" 4
.IX Item "ssize_t pth_sendto_ev(int fd, const void *buf, size_t nbytes, int flags, const struct sockaddr *to, socklen_t tolen, pth_event_t ev);"
This is equal to \fIpth_sendto\fR\|(3) (see below), but has an additional event
argument \fIev\fR. When \fIpth_sendto\fR\|(3) suspends the current threads execution it
usually only uses the I/O event on \fIfd\fR to awake. With this function any
number of extra events can be used to awake the current thread (remember that
\&\fIev\fR actually is an event \fIring\fR).
.Sh "Standard \s-1POSIX\s0 Replacement \s-1API\s0"
.IX Subsection "Standard POSIX Replacement API"
The following functions are standard replacements functions for the \s-1POSIX\s0 \s-1API\s0.
The difference is mainly that they suspend the current thread only instead of
the whole process in case the file descriptors will block.
.IP "int \fBpth_nanosleep\fR(const struct timespec *\fIrqtp\fR, struct timespec *\fIrmtp\fR);" 4
.IX Item "int pth_nanosleep(const struct timespec *rqtp, struct timespec *rmtp);"
This is a variant of the \s-1POSIX\s0 \fInanosleep\fR\|(3) function. It suspends the
current threads execution until the amount of time in \fIrqtp\fR elapsed.
The thread is guaranteed to not wake up before this time, but because
of the non-preemptive scheduling nature of \fBPth\fR, it can be awakened
later, of course. If \fIrmtp\fR is not \f(CW\*(C`NULL\*(C'\fR, the \f(CW\*(C`timespec\*(C'\fR structure
it references is updated to contain the unslept amount (the request time
minus the time actually slept time). The difference between \fInanosleep\fR\|(3)
and \fIpth_nanosleep\fR\|(3) is that that \fIpth_nanosleep\fR\|(3) suspends only the
execution of the current thread and not the whole process.
.IP "int \fBpth_usleep\fR(unsigned int \fIusec\fR);" 4
.IX Item "int pth_usleep(unsigned int usec);"
This is a variant of the 4.3BSD \fIusleep\fR\|(3) function. It suspends the current
threads execution until \fIusec\fR microseconds (= \fIusec\fR*1/1000000 sec)
elapsed.  The thread is guaranteed to not wake up before this time, but
because of the non-preemptive scheduling nature of \fBPth\fR, it can be awakened
later, of course.  The difference between \fIusleep\fR\|(3) and \fIpth_usleep\fR\|(3) is that
that \fIpth_usleep\fR\|(3) suspends only the execution of the current thread and not
the whole process.
.IP "unsigned int \fBpth_sleep\fR(unsigned int \fIsec\fR);" 4
.IX Item "unsigned int pth_sleep(unsigned int sec);"
This is a variant of the \s-1POSIX\s0 \fIsleep\fR\|(3) function. It suspends the current
threads execution until \fIsec\fR seconds elapsed.  The thread is guaranteed to
not wake up before this time, but because of the non-preemptive scheduling
nature of \fBPth\fR, it can be awakened later, of course.  The difference between
\&\fIsleep\fR\|(3) and \fIpth_sleep\fR\|(3) is that \fIpth_sleep\fR\|(3) suspends only the
execution of the current thread and not the whole process.
.IP "pid_t \fBpth_waitpid\fR(pid_t \fIpid\fR, int *\fIstatus\fR, int \fIoptions\fR);" 4
.IX Item "pid_t pth_waitpid(pid_t pid, int *status, int options);"
This is a variant of the \s-1POSIX\s0 \fIwaitpid\fR\|(2) function. It suspends the
current threads execution until \fIstatus\fR information is available for a
terminated child process \fIpid\fR.  The difference between \fIwaitpid\fR\|(2) and
\&\fIpth_waitpid\fR\|(3) is that \fIpth_waitpid\fR\|(3) suspends only the execution of the
current thread and not the whole process.  For more details about the
arguments and return code semantics see \fIwaitpid\fR\|(2).
.IP "int \fBpth_system\fR(const char *\fIcmd\fR);" 4
.IX Item "int pth_system(const char *cmd);"
This is a variant of the \s-1POSIX\s0 \fIsystem\fR\|(3) function. It executes the
shell command \fIcmd\fR with Bourne Shell (\f(CW\*(C`sh\*(C'\fR) and suspends the current
threads execution until this command terminates. The difference between
\&\fIsystem\fR\|(3) and \fIpth_system\fR\|(3) is that \fIpth_system\fR\|(3) suspends only
the execution of the current thread and not the whole process. For more
details about the arguments and return code semantics see \fIsystem\fR\|(3).
.IP "int \fBpth_sigmask\fR(int \fIhow\fR, const sigset_t *\fIset\fR, sigset_t *\fIoset\fR)" 4
.IX Item "int pth_sigmask(int how, const sigset_t *set, sigset_t *oset)"
This is the \fBPth\fR thread-related equivalent of \s-1POSIX\s0 \fIsigprocmask\fR\|(2) respectively
\&\fIpthread_sigmask\fR\|(3). The arguments \fIhow\fR, \fIset\fR and \fIoset\fR directly relate
to \fIsigprocmask\fR\|(2), because \fBPth\fR internally just uses \fIsigprocmask\fR\|(2) here. So
alternatively you can also directly call \fIsigprocmask\fR\|(2), but for consistency
reasons you should use this function \fIpth_sigmask\fR\|(3).
.IP "int \fBpth_sigwait\fR(const sigset_t *\fIset\fR, int *\fIsig\fR);" 4
.IX Item "int pth_sigwait(const sigset_t *set, int *sig);"
This is a variant of the \s-1POSIX\s0.1c \fIsigwait\fR\|(3) function. It suspends the current
threads execution until a signal in \fIset\fR occurred and stores the signal
number in \fIsig\fR. The important point is that the signal is not delivered to a
signal handler. Instead it's caught by the scheduler only in order to awake
the \fIpth_sigwait()\fR call. The trick and noticeable point here is that this way
you get an asynchronous aware application that is written completely
synchronously. When you think about the problem of \fIasynchronous safe\fR
functions you should recognize that this is a great benefit.
.IP "int \fBpth_connect\fR(int \fIs\fR, const struct sockaddr *\fIaddr\fR, socklen_t \fIaddrlen\fR);" 4
.IX Item "int pth_connect(int s, const struct sockaddr *addr, socklen_t addrlen);"
This is a variant of the 4.2BSD \fIconnect\fR\|(2) function. It establishes a
connection on a socket \fIs\fR to target specified in \fIaddr\fR and \fIaddrlen\fR.
The difference between \fIconnect\fR\|(2) and \fIpth_connect\fR\|(3) is that
\&\fIpth_connect\fR\|(3) suspends only the execution of the current thread and not the
whole process.  For more details about the arguments and return code semantics
see \fIconnect\fR\|(2).
.IP "int \fBpth_accept\fR(int \fIs\fR, struct sockaddr *\fIaddr\fR, socklen_t *\fIaddrlen\fR);" 4
.IX Item "int pth_accept(int s, struct sockaddr *addr, socklen_t *addrlen);"
This is a variant of the 4.2BSD \fIaccept\fR\|(2) function. It accepts a connection on
a socket by extracting the first connection request on the queue of pending
connections, creating a new socket with the same properties of \fIs\fR and
allocates a new file descriptor for the socket (which is returned).  The
difference between \fIaccept\fR\|(2) and \fIpth_accept\fR\|(3) is that \fIpth_accept\fR\|(3)
suspends only the execution of the current thread and not the whole process.
For more details about the arguments and return code semantics see \fIaccept\fR\|(2).
.IP "int \fBpth_select\fR(int \fInfd\fR, fd_set *\fIrfds\fR, fd_set *\fIwfds\fR, fd_set *\fIefds\fR, struct timeval *\fItimeout\fR);" 4
.IX Item "int pth_select(int nfd, fd_set *rfds, fd_set *wfds, fd_set *efds, struct timeval *timeout);"
This is a variant of the 4.2BSD \fIselect\fR\|(2) function.  It examines the I/O
descriptor sets whose addresses are passed in \fIrfds\fR, \fIwfds\fR, and \fIefds\fR to
see if some of their descriptors are ready for reading, are ready for writing,
or have an exceptional condition pending, respectively.  For more details
about the arguments and return code semantics see \fIselect\fR\|(2).
.IP "int \fBpth_pselect\fR(int \fInfd\fR, fd_set *\fIrfds\fR, fd_set *\fIwfds\fR, fd_set *\fIefds\fR, const struct timespec *\fItimeout\fR, const sigset_t *\fIsigmask\fR);" 4
.IX Item "int pth_pselect(int nfd, fd_set *rfds, fd_set *wfds, fd_set *efds, const struct timespec *timeout, const sigset_t *sigmask);"
This is a variant of the \s-1POSIX\s0 \fIpselect\fR\|(2) function, which in turn
is a stronger variant of 4.2BSD \fIselect\fR\|(2). The difference is that
the higher-resolution \f(CW\*(C`struct timespec\*(C'\fR is passed instead of the
lower-resolution \f(CW\*(C`struct timeval\*(C'\fR and that a signal mask is specified
which is temporarily set while waiting for input. For more details about
the arguments and return code semantics see \fIpselect\fR\|(2) and \fIselect\fR\|(2).
.IP "int \fBpth_poll\fR(struct pollfd *\fIfds\fR, unsigned int \fInfd\fR, int \fItimeout\fR);" 4
.IX Item "int pth_poll(struct pollfd *fds, unsigned int nfd, int timeout);"
This is a variant of the SysV \fIpoll\fR\|(2) function. It examines the I/O
descriptors which are passed in the array \fIfds\fR to see if some of them are
ready for reading, are ready for writing, or have an exceptional condition
pending, respectively. For more details about the arguments and return code
semantics see \fIpoll\fR\|(2).
.IP "ssize_t \fBpth_read\fR(int \fIfd\fR, void *\fIbuf\fR, size_t \fInbytes\fR);" 4
.IX Item "ssize_t pth_read(int fd, void *buf, size_t nbytes);"
This is a variant of the \s-1POSIX\s0 \fIread\fR\|(2) function. It reads up to \fInbytes\fR
bytes into \fIbuf\fR from file descriptor \fIfd\fR.  The difference between \fIread\fR\|(2)
and \fIpth_read\fR\|(2) is that \fIpth_read\fR\|(2) suspends execution of the current
thread until the file descriptor is ready for reading. For more details about
the arguments and return code semantics see \fIread\fR\|(2).
.IP "ssize_t \fBpth_readv\fR(int \fIfd\fR, const struct iovec *\fIiovec\fR, int \fIiovcnt\fR);" 4
.IX Item "ssize_t pth_readv(int fd, const struct iovec *iovec, int iovcnt);"
This is a variant of the \s-1POSIX\s0 \fIreadv\fR\|(2) function. It reads data from
file descriptor \fIfd\fR into the first \fIiovcnt\fR rows of the \fIiov\fR vector.  The
difference between \fIreadv\fR\|(2) and \fIpth_readv\fR\|(2) is that \fIpth_readv\fR\|(2)
suspends execution of the current thread until the file descriptor is ready for
reading. For more details about the arguments and return code semantics see
\&\fIreadv\fR\|(2).
.IP "ssize_t \fBpth_write\fR(int \fIfd\fR, const void *\fIbuf\fR, size_t \fInbytes\fR);" 4
.IX Item "ssize_t pth_write(int fd, const void *buf, size_t nbytes);"
This is a variant of the \s-1POSIX\s0 \fIwrite\fR\|(2) function. It writes \fInbytes\fR bytes
from \fIbuf\fR to file descriptor \fIfd\fR.  The difference between \fIwrite\fR\|(2) and
\&\fIpth_write\fR\|(2) is that \fIpth_write\fR\|(2) suspends execution of the current
thread until the file descriptor is ready for writing.  For more details about
the arguments and return code semantics see \fIwrite\fR\|(2).
.IP "ssize_t \fBpth_writev\fR(int \fIfd\fR, const struct iovec *\fIiovec\fR, int \fIiovcnt\fR);" 4
.IX Item "ssize_t pth_writev(int fd, const struct iovec *iovec, int iovcnt);"
This is a variant of the \s-1POSIX\s0 \fIwritev\fR\|(2) function. It writes data to
file descriptor \fIfd\fR from the first \fIiovcnt\fR rows of the \fIiov\fR vector.  The
difference between \fIwritev\fR\|(2) and \fIpth_writev\fR\|(2) is that \fIpth_writev\fR\|(2)
suspends execution of the current thread until the file descriptor is ready for
reading. For more details about the arguments and return code semantics see
\&\fIwritev\fR\|(2).
.IP "ssize_t \fBpth_pread\fR(int \fIfd\fR, void *\fIbuf\fR, size_t \fInbytes\fR, off_t \fIoffset\fR);" 4
.IX Item "ssize_t pth_pread(int fd, void *buf, size_t nbytes, off_t offset);"
This is a variant of the \s-1POSIX\s0 \fIpread\fR\|(3) function.  It performs the same action
as a regular \fIread\fR\|(2), except that it reads from a given position in the file
without changing the file pointer.  The first three arguments are the same as
for \fIpth_read\fR\|(3) with the addition of a fourth argument \fIoffset\fR for the
desired position inside the file.
.IP "ssize_t \fBpth_pwrite\fR(int \fIfd\fR, const void *\fIbuf\fR, size_t \fInbytes\fR, off_t \fIoffset\fR);" 4
.IX Item "ssize_t pth_pwrite(int fd, const void *buf, size_t nbytes, off_t offset);"
This is a variant of the \s-1POSIX\s0 \fIpwrite\fR\|(3) function.  It performs the same
action as a regular \fIwrite\fR\|(2), except that it writes to a given position in the
file without changing the file pointer. The first three arguments are the same
as for \fIpth_write\fR\|(3) with the addition of a fourth argument \fIoffset\fR for the
desired position inside the file.
.IP "ssize_t \fBpth_recv\fR(int \fIfd\fR, void *\fIbuf\fR, size_t \fInbytes\fR, int \fIflags\fR);" 4
.IX Item "ssize_t pth_recv(int fd, void *buf, size_t nbytes, int flags);"
This is a variant of the SUSv2 \fIrecv\fR\|(2) function and equal to
``pth_recvfrom(fd, buf, nbytes, flags, \s-1NULL\s0, 0)''.
.IP "ssize_t \fBpth_recvfrom\fR(int \fIfd\fR, void *\fIbuf\fR, size_t \fInbytes\fR, int \fIflags\fR, struct sockaddr *\fIfrom\fR, socklen_t *\fIfromlen\fR);" 4
.IX Item "ssize_t pth_recvfrom(int fd, void *buf, size_t nbytes, int flags, struct sockaddr *from, socklen_t *fromlen);"
This is a variant of the SUSv2 \fIrecvfrom\fR\|(2) function. It reads up to
\&\fInbytes\fR bytes into \fIbuf\fR from file descriptor \fIfd\fR while using
\&\fIflags\fR and \fIfrom\fR/\fIfromlen\fR. The difference between \fIrecvfrom\fR\|(2) and
\&\fIpth_recvfrom\fR\|(2) is that \fIpth_recvfrom\fR\|(2) suspends execution of the
current thread until the file descriptor is ready for reading. For more
details about the arguments and return code semantics see \fIrecvfrom\fR\|(2).
.IP "ssize_t \fBpth_send\fR(int \fIfd\fR, const void *\fIbuf\fR, size_t \fInbytes\fR, int \fIflags\fR);" 4
.IX Item "ssize_t pth_send(int fd, const void *buf, size_t nbytes, int flags);"
This is a variant of the SUSv2 \fIsend\fR\|(2) function and equal to
``pth_sendto(fd, buf, nbytes, flags, \s-1NULL\s0, 0)''.
.IP "ssize_t \fBpth_sendto\fR(int \fIfd\fR, const void *\fIbuf\fR, size_t \fInbytes\fR, int \fIflags\fR, const struct sockaddr *\fIto\fR, socklen_t \fItolen\fR);" 4
.IX Item "ssize_t pth_sendto(int fd, const void *buf, size_t nbytes, int flags, const struct sockaddr *to, socklen_t tolen);"
This is a variant of the SUSv2 \fIsendto\fR\|(2) function. It writes \fInbytes\fR
bytes from \fIbuf\fR to file descriptor \fIfd\fR while using \fIflags\fR and
\&\fIto\fR/\fItolen\fR. The difference between \fIsendto\fR\|(2) and \fIpth_sendto\fR\|(2) is
that \fIpth_sendto\fR\|(2) suspends execution of the current thread until
the file descriptor is ready for writing. For more details about the
arguments and return code semantics see \fIsendto\fR\|(2).
.SH "EXAMPLE"
.IX Header "EXAMPLE"
The following example is a useless server which does nothing more than
listening on \s-1TCP\s0 port 12345 and displaying the current time to the
socket when a connection was established. For each incoming connection a
thread is spawned. Additionally, to see more multithreading, a useless
ticker thread runs simultaneously which outputs the current time to
\&\f(CW\*(C`stderr\*(C'\fR every 5 seconds. The example contains \fIno\fR error checking and
is \fIonly\fR intended to show you the look and feel of \fBPth\fR.
.PP
.Vb 11
\& #include <stdio.h>
\& #include <stdlib.h>
\& #include <errno.h>
\& #include <sys/types.h>
\& #include <sys/socket.h>
\& #include <netinet/in.h>
\& #include <arpa/inet.h>
\& #include <signal.h>
\& #include <netdb.h>
\& #include <unistd.h>
\& #include "pth.h"
.Ve
.PP
.Vb 1
\& #define PORT 12345
.Ve
.PP
.Vb 6
\& /* the socket connection handler thread */
\& static void *handler(void *_arg)
\& {
\&     int fd = (int)_arg;
\&     time_t now;
\&     char *ct;
.Ve
.PP
.Vb 6
\&     now = time(NULL);
\&     ct = ctime(&now);
\&     pth_write(fd, ct, strlen(ct));
\&     close(fd);
\&     return NULL;
\& }
.Ve
.PP
.Vb 6
\& /* the stderr time ticker thread */
\& static void *ticker(void *_arg)
\& {
\&     time_t now;
\&     char *ct;
\&     float load;
.Ve
.PP
.Vb 9
\&     for (;;) {
\&         pth_sleep(5);
\&         now = time(NULL);
\&         ct = ctime(&now);
\&         ct[strlen(ct)\-1] = '\e0';
\&         pth_ctrl(PTH_CTRL_GETAVLOAD, &load);
\&         printf("ticker: time: %s, average load: %.2f\en", ct, load);
\&     }
\& }
.Ve
.PP
.Vb 10
\& /* the main thread/procedure */
\& int main(int argc, char *argv[])
\& {
\&     pth_attr_t attr;
\&     struct sockaddr_in sar;
\&     struct protoent *pe;
\&     struct sockaddr_in peer_addr;
\&     int peer_len;
\&     int sa, sw;
\&     int port;
.Ve
.PP
.Vb 2
\&     pth_init();
\&     signal(SIGPIPE, SIG_IGN);
.Ve
.PP
.Vb 5
\&     attr = pth_attr_new();
\&     pth_attr_set(attr, PTH_ATTR_NAME, "ticker");
\&     pth_attr_set(attr, PTH_ATTR_STACK_SIZE, 64*1024);
\&     pth_attr_set(attr, PTH_ATTR_JOINABLE, FALSE);
\&     pth_spawn(attr, ticker, NULL);
.Ve
.PP
.Vb 7
\&     pe = getprotobyname("tcp");
\&     sa = socket(AF_INET, SOCK_STREAM, pe\->p_proto);
\&     sar.sin_family = AF_INET;
\&     sar.sin_addr.s_addr = INADDR_ANY;
\&     sar.sin_port = htons(PORT);
\&     bind(sa, (struct sockaddr *)&sar, sizeof(struct sockaddr_in));
\&     listen(sa, 10);
.Ve
.PP
.Vb 7
\&     pth_attr_set(attr, PTH_ATTR_NAME, "handler");
\&     for (;;) {
\&         peer_len = sizeof(peer_addr);
\&         sw = pth_accept(sa, (struct sockaddr *)&peer_addr, &peer_len);
\&         pth_spawn(attr, handler, (void *)sw);
\&     }
\& }
.Ve
.SH "BUILD ENVIRONMENTS"
.IX Header "BUILD ENVIRONMENTS"
In this section we will discuss the canonical ways to establish the build
environment for a \fBPth\fR based program. The possibilities supported by \fBPth\fR
range from very simple environments to rather complex ones.
.Sh "Manual Build Environment (Novice)"
.IX Subsection "Manual Build Environment (Novice)"
As a first example, assume we have the above test program staying in the
source file \f(CW\*(C`foo.c\*(C'\fR. Then we can create a very simple build environment by
just adding the following \f(CW\*(C`Makefile\*(C'\fR:
.PP
.Vb 13
\& $ vi Makefile
\& | CC      = cc
\& | CFLAGS  = `pth\-config \-\-cflags`
\& | LDFLAGS = `pth\-config \-\-ldflags`
\& | LIBS    = `pth\-config \-\-libs`
\& |
\& | all: foo
\& | foo: foo.o
\& |     $(CC) $(LDFLAGS) \-o foo foo.o $(LIBS)
\& | foo.o: foo.c
\& |     $(CC) $(CFLAGS) \-c foo.c
\& | clean:
\& |     rm \-f foo foo.o
.Ve
.PP
This imports the necessary compiler and linker flags on-the-fly from the
\&\fBPth\fR installation via its \f(CW\*(C`pth\-config\*(C'\fR program. This approach is
straight-forward and works fine for small projects.
.Sh "Autoconf Build Environment (Advanced)"
.IX Subsection "Autoconf Build Environment (Advanced)"
The previous approach is simple but inflexible. First, to speed up
building, it would be nice to not expand the compiler and linker flags
every time the compiler is started. Second, it would be useful to
also be able to build against uninstalled \fBPth\fR, that is, against
a \fBPth\fR source tree which was just configured and built, but not
installed. Third, it would be also useful to allow checking of the
\&\fBPth\fR version to make sure it is at least a minimum required version.
And finally, it would be also great to make sure \fBPth\fR works correctly
by first performing some sanity compile and run-time checks. All this
can be done if we use \s-1GNU\s0 \fBautoconf\fR and the \f(CW\*(C`AC_CHECK_PTH\*(C'\fR macro
provided by \fBPth\fR. For this, we establish the following three files:
.PP
First we again need the \f(CW\*(C`Makefile\*(C'\fR, but this time it contains \fBautoconf\fR
placeholders and additional cleanup targets. And we create it under the name
\&\f(CW\*(C`Makefile.in\*(C'\fR, because it is now an input file for \fBautoconf\fR:
.PP
.Vb 17
\& $ vi Makefile.in
\& | CC      = @CC@
\& | CFLAGS  = @CFLAGS@
\& | LDFLAGS = @LDFLAGS@
\& | LIBS    = @LIBS@
\& |
\& | all: foo
\& | foo: foo.o
\& |     $(CC) $(LDFLAGS) \-o foo foo.o $(LIBS)
\& | foo.o: foo.c
\& |     $(CC) $(CFLAGS) \-c foo.c
\& | clean:
\& |     rm \-f foo foo.o
\& | distclean:
\& |     rm \-f foo foo.o
\& |     rm \-f config.log config.status config.cache
\& |     rm \-f Makefile
.Ve
.PP
Because \fBautoconf\fR generates additional files, we added a canonical
\&\f(CW\*(C`distclean\*(C'\fR target which cleans this up. Secondly, we wrote
\&\f(CW\*(C`configure.ac\*(C'\fR, a (minimal) \fBautoconf\fR script specification:
.PP
.Vb 4
\& $ vi configure.ac
\& | AC_INIT(Makefile.in)
\& | AC_CHECK_PTH(1.3.0)
\& | AC_OUTPUT(Makefile)
.Ve
.PP
Then we let \fBautoconf\fR's \f(CW\*(C`aclocal\*(C'\fR program generate for us an \f(CW\*(C`aclocal.m4\*(C'\fR
file containing \fBPth\fR's \f(CW\*(C`AC_CHECK_PTH\*(C'\fR macro. Then we generate the final
\&\f(CW\*(C`configure\*(C'\fR script out of this \f(CW\*(C`aclocal.m4\*(C'\fR file and the \f(CW\*(C`configure.ac\*(C'\fR
file:
.PP
.Vb 2
\& $ aclocal \-\-acdir=`pth\-config \-\-acdir`
\& $ autoconf
.Ve
.PP
After these steps, the working directory should look similar to this:
.PP
.Vb 6
\& $ ls \-l
\& \-rw\-r\-\-r\-\-  1 rse  users    176 Nov  3 11:11 Makefile.in
\& \-rw\-r\-\-r\-\-  1 rse  users  15314 Nov  3 11:16 aclocal.m4
\& \-rwxr\-xr\-x  1 rse  users  52045 Nov  3 11:16 configure
\& \-rw\-r\-\-r\-\-  1 rse  users     63 Nov  3 11:11 configure.ac
\& \-rw\-r\-\-r\-\-  1 rse  users   4227 Nov  3 11:11 foo.c
.Ve
.PP
If we now run \f(CW\*(C`configure\*(C'\fR we get a correct \f(CW\*(C`Makefile\*(C'\fR which
immediately can be used to build \f(CW\*(C`foo\*(C'\fR (assuming that \fBPth\fR is already
installed somewhere, so that \f(CW\*(C`pth\-config\*(C'\fR is in \f(CW$PATH\fR):
.PP
.Vb 16
\& $ ./configure
\& creating cache ./config.cache
\& checking for gcc... gcc
\& checking whether the C compiler (gcc   ) works... yes
\& checking whether the C compiler (gcc   ) is a cross\-compiler... no
\& checking whether we are using GNU C... yes
\& checking whether gcc accepts \-g... yes
\& checking how to run the C preprocessor... gcc \-E
\& checking for GNU Pth... version 1.3.0, installed under /usr/local
\& updating cache ./config.cache
\& creating ./config.status
\& creating Makefile
\& rse@en1:/e/gnu/pth/ac
\& $ make
\& gcc \-g \-O2 \-I/usr/local/include \-c foo.c
\& gcc \-L/usr/local/lib \-o foo foo.o \-lpth
.Ve
.PP
If \fBPth\fR is installed in non-standard locations or \f(CW\*(C`pth\-config\*(C'\fR
is not in \f(CW$PATH\fR, one just has to drop the \f(CW\*(C`configure\*(C'\fR script
a note about the location by running \f(CW\*(C`configure\*(C'\fR with the option
\&\f(CW\*(C`\-\-with\-pth=\*(C'\fR\fIdir\fR (where \fIdir\fR is the argument which was used with
the \f(CW\*(C`\-\-prefix\*(C'\fR option when \fBPth\fR was installed).
.Sh "Autoconf Build Environment with Local Copy of Pth (Expert)"
.IX Subsection "Autoconf Build Environment with Local Copy of Pth (Expert)"
Finally let us assume the \f(CW\*(C`foo\*(C'\fR program stays under either a \fI\s-1GPL\s0\fR or
\&\fI\s-1LGPL\s0\fR distribution license and we want to make it a stand-alone package for
easier distribution and installation.  That is, we don't want to oblige the
end-user to install \fBPth\fR just to allow our \f(CW\*(C`foo\*(C'\fR package to
compile. For this, it is a convenient practice to include the required
libraries (here \fBPth\fR) into the source tree of the package (here \f(CW\*(C`foo\*(C'\fR).
\&\fBPth\fR ships with all necessary support to allow us to easily achieve this
approach. Say, we want \fBPth\fR in a subdirectory named \f(CW\*(C`pth/\*(C'\fR and this
directory should be seamlessly integrated into the configuration and build
process of \f(CW\*(C`foo\*(C'\fR.
.PP
First we again start with the \f(CW\*(C`Makefile.in\*(C'\fR, but this time it is a more
advanced version which supports subdirectory movement:
.PP
.Vb 34
\& $ vi Makefile.in
\& | CC      = @CC@
\& | CFLAGS  = @CFLAGS@
\& | LDFLAGS = @LDFLAGS@
\& | LIBS    = @LIBS@
\& |
\& | SUBDIRS = pth
\& |
\& | all: subdirs_all foo
\& |
\& | subdirs_all:
\& |     @$(MAKE) $(MFLAGS) subdirs TARGET=all
\& | subdirs_clean:
\& |     @$(MAKE) $(MFLAGS) subdirs TARGET=clean
\& | subdirs_distclean:
\& |     @$(MAKE) $(MFLAGS) subdirs TARGET=distclean
\& | subdirs:
\& |     @for subdir in $(SUBDIRS); do \e
\& |         echo "===> $$subdir ($(TARGET))"; \e
\& |         (cd $$subdir; $(MAKE) $(MFLAGS) $(TARGET) || exit 1) || exit 1; \e
\& |         echo "<=== $$subdir"; \e
\& |     done
\& |
\& | foo: foo.o
\& |     $(CC) $(LDFLAGS) \-o foo foo.o $(LIBS)
\& | foo.o: foo.c
\& |     $(CC) $(CFLAGS) \-c foo.c
\& |
\& | clean: subdirs_clean
\& |     rm \-f foo foo.o
\& | distclean: subdirs_distclean
\& |     rm \-f foo foo.o
\& |     rm \-f config.log config.status config.cache
\& |     rm \-f Makefile
.Ve
.PP
Then we create a slightly different \fBautoconf\fR script \f(CW\*(C`configure.ac\*(C'\fR:
.PP
.Vb 6
\& $ vi configure.ac
\& | AC_INIT(Makefile.in)
\& | AC_CONFIG_AUX_DIR(pth)
\& | AC_CHECK_PTH(1.3.0, subdir:pth \-\-disable\-tests)
\& | AC_CONFIG_SUBDIRS(pth)
\& | AC_OUTPUT(Makefile)
.Ve
.PP
Here we provided a default value for \f(CW\*(C`foo\*(C'\fR's \f(CW\*(C`\-\-with\-pth\*(C'\fR option as the
second argument to \f(CW\*(C`AC_CHECK_PTH\*(C'\fR which indicates that \fBPth\fR can be found in
the subdirectory named \f(CW\*(C`pth/\*(C'\fR. Additionally we specified that the
\&\f(CW\*(C`\-\-disable\-tests\*(C'\fR option of \fBPth\fR should be passed to the \f(CW\*(C`pth/\*(C'\fR
subdirectory, because we need only to build the \fBPth\fR library itself. And we
added a \f(CW\*(C`AC_CONFIG_SUBDIR\*(C'\fR call which indicates to \fBautoconf\fR that it should
configure the \f(CW\*(C`pth/\*(C'\fR subdirectory, too. The \f(CW\*(C`AC_CONFIG_AUX_DIR\*(C'\fR directive
was added just to make \fBautoconf\fR happy, because it wants to find a
\&\f(CW\*(C`install.sh\*(C'\fR or \f(CW\*(C`shtool\*(C'\fR script if \f(CW\*(C`AC_CONFIG_SUBDIRS\*(C'\fR is used.
.PP
Now we let \fBautoconf\fR's \f(CW\*(C`aclocal\*(C'\fR program again generate for us an
\&\f(CW\*(C`aclocal.m4\*(C'\fR file with the contents of \fBPth\fR's \f(CW\*(C`AC_CHECK_PTH\*(C'\fR macro.
Finally we generate the \f(CW\*(C`configure\*(C'\fR script out of this \f(CW\*(C`aclocal.m4\*(C'\fR
file and the \f(CW\*(C`configure.ac\*(C'\fR file.
.PP
.Vb 2
\& $ aclocal \-\-acdir=`pth\-config \-\-acdir`
\& $ autoconf
.Ve
.PP
Now we have to create the \f(CW\*(C`pth/\*(C'\fR subdirectory itself. For this, we extract the
\&\fBPth\fR distribution to the \f(CW\*(C`foo\*(C'\fR source tree and just rename it to \f(CW\*(C`pth/\*(C'\fR:
.PP
.Vb 2
\& $ gunzip <pth\-X.Y.Z.tar.gz | tar xvf \-
\& $ mv pth\-X.Y.Z pth
.Ve
.PP
Optionally to reduce the size of the \f(CW\*(C`pth/\*(C'\fR subdirectory, we can strip down
the \fBPth\fR sources to a minimum with the \fIstriptease\fR feature:
.PP
.Vb 4
\& $ cd pth
\& $ ./configure
\& $ make striptease
\& $ cd ..
.Ve
.PP
After this the source tree of \f(CW\*(C`foo\*(C'\fR should look similar to this:
.PP
.Vb 24
\& $ ls \-l
\& \-rw\-r\-\-r\-\-  1 rse  users    709 Nov  3 11:51 Makefile.in
\& \-rw\-r\-\-r\-\-  1 rse  users  16431 Nov  3 12:20 aclocal.m4
\& \-rwxr\-xr\-x  1 rse  users  57403 Nov  3 12:21 configure
\& \-rw\-r\-\-r\-\-  1 rse  users    129 Nov  3 12:21 configure.ac
\& \-rw\-r\-\-r\-\-  1 rse  users   4227 Nov  3 11:11 foo.c
\& drwxr\-xr\-x  2 rse  users   3584 Nov  3 12:36 pth
\& $ ls \-l pth/
\& \-rw\-rw\-r\-\-  1 rse  users   26344 Nov  1 20:12 COPYING
\& \-rw\-rw\-r\-\-  1 rse  users    2042 Nov  3 12:36 Makefile.in
\& \-rw\-rw\-r\-\-  1 rse  users    3967 Nov  1 19:48 README
\& \-rw\-rw\-r\-\-  1 rse  users     340 Nov  3 12:36 README.1st
\& \-rw\-rw\-r\-\-  1 rse  users   28719 Oct 31 17:06 config.guess
\& \-rw\-rw\-r\-\-  1 rse  users   24274 Aug 18 13:31 config.sub
\& \-rwxrwxr\-x  1 rse  users  155141 Nov  3 12:36 configure
\& \-rw\-rw\-r\-\-  1 rse  users  162021 Nov  3 12:36 pth.c
\& \-rw\-rw\-r\-\-  1 rse  users   18687 Nov  2 15:19 pth.h.in
\& \-rw\-rw\-r\-\-  1 rse  users    5251 Oct 31 12:46 pth_acdef.h.in
\& \-rw\-rw\-r\-\-  1 rse  users    2120 Nov  1 11:27 pth_acmac.h.in
\& \-rw\-rw\-r\-\-  1 rse  users    2323 Nov  1 11:27 pth_p.h.in
\& \-rw\-rw\-r\-\-  1 rse  users     946 Nov  1 11:27 pth_vers.c
\& \-rw\-rw\-r\-\-  1 rse  users   26848 Nov  1 11:27 pthread.c
\& \-rw\-rw\-r\-\-  1 rse  users   18772 Nov  1 11:27 pthread.h.in
\& \-rwxrwxr\-x  1 rse  users   26188 Nov  3 12:36 shtool
.Ve
.PP
Now when we configure and build the \f(CW\*(C`foo\*(C'\fR package it looks similar to this:
.PP
.Vb 31
\& $ ./configure
\& creating cache ./config.cache
\& checking for gcc... gcc
\& checking whether the C compiler (gcc   ) works... yes
\& checking whether the C compiler (gcc   ) is a cross\-compiler... no
\& checking whether we are using GNU C... yes
\& checking whether gcc accepts \-g... yes
\& checking how to run the C preprocessor... gcc \-E
\& checking for GNU Pth... version 1.3.0, local under pth
\& updating cache ./config.cache
\& creating ./config.status
\& creating Makefile
\& configuring in pth
\& running /bin/sh ./configure  \-\-enable\-subdir \-\-enable\-batch
\& \-\-disable\-tests \-\-cache\-file=.././config.cache \-\-srcdir=.
\& loading cache .././config.cache
\& checking for gcc... (cached) gcc
\& checking whether the C compiler (gcc   ) works... yes
\& checking whether the C compiler (gcc   ) is a cross\-compiler... no
\& [...]
\& $ make
\& ===> pth (all)
\& ./shtool scpp \-o pth_p.h \-t pth_p.h.in \-Dcpp \-Cintern \-M '==#==' pth.c
\& pth_vers.c
\& gcc \-c \-I. \-O2 \-pipe pth.c
\& gcc \-c \-I. \-O2 \-pipe pth_vers.c
\& ar rc libpth.a pth.o pth_vers.o
\& ranlib libpth.a
\& <=== pth
\& gcc \-g \-O2 \-Ipth \-c foo.c
\& gcc \-Lpth \-o foo foo.o \-lpth
.Ve
.PP
As you can see, \fBautoconf\fR now automatically configures the local
(stripped down) copy of \fBPth\fR in the subdirectory \f(CW\*(C`pth/\*(C'\fR and the
\&\f(CW\*(C`Makefile\*(C'\fR automatically builds the subdirectory, too.
.SH "SYSTEM CALL WRAPPER FACILITY"
.IX Header "SYSTEM CALL WRAPPER FACILITY"
\&\fBPth\fR per default uses an explicit \s-1API\s0, including the system calls. For
instance you've to explicitly use \fIpth_read\fR\|(3) when you need a thread-aware
\&\fIread\fR\|(3) and cannot expect that by just calling \fIread\fR\|(3) only the current thread
is blocked. Instead with the standard \fIread\fR\|(3) call the whole process will be
blocked. But because for some applications (mainly those consisting of lots of
third-party stuff) this can be inconvenient.  Here it's required that a call
to \fIread\fR\|(3) `magically' means \fIpth_read\fR\|(3). The problem here is that such
magic \fBPth\fR cannot provide per default because it's not really portable.
Nevertheless \fBPth\fR provides a two step approach to solve this problem:
.Sh "Soft System Call Mapping"
.IX Subsection "Soft System Call Mapping"
This variant is available on all platforms and can \fIalways\fR be enabled by
building \fBPth\fR with \f(CW\*(C`\-\-enable\-syscall\-soft\*(C'\fR. This then triggers some
\&\f(CW\*(C`#define\*(C'\fR's in the \f(CW\*(C`pth.h\*(C'\fR header which map for instance \fIread\fR\|(3) to
\&\fIpth_read\fR\|(3), etc. Currently the following functions are mapped: \fIfork\fR\|(2),
\&\fInanosleep\fR\|(3), \fIusleep\fR\|(3), \fIsleep\fR\|(3), \fIsigwait\fR\|(3), \fIwaitpid\fR\|(2), \fIsystem\fR\|(3),
\&\fIselect\fR\|(2), \fIpoll\fR\|(2), \fIconnect\fR\|(2), \fIaccept\fR\|(2), \fIread\fR\|(2), \fIwrite\fR\|(2), \fIrecv\fR\|(2),
\&\fIsend\fR\|(2), \fIrecvfrom\fR\|(2), \fIsendto\fR\|(2).
.PP
The drawback of this approach is just that really all source files
of the application where these function calls occur have to include
\&\f(CW\*(C`pth.h\*(C'\fR, of course. And this also means that existing libraries,
including the vendor's \fBstdio\fR, usually will still block the whole
process if one of its I/O functions block.
.Sh "Hard System Call Mapping"
.IX Subsection "Hard System Call Mapping"
This variant is available only on those platforms where the \fIsyscall\fR\|(2)
function exists and there it can be enabled by building \fBPth\fR with
\&\f(CW\*(C`\-\-enable\-syscall\-hard\*(C'\fR. This then builds wrapper functions (for instances
\&\fIread\fR\|(3)) into the \fBPth\fR library which internally call the real \fBPth\fR
replacement functions (\fIpth_read\fR\|(3)). Currently the following functions
are mapped: \fIfork\fR\|(2), \fInanosleep\fR\|(3), \fIusleep\fR\|(3), \fIsleep\fR\|(3), \fIwaitpid\fR\|(2),
\&\fIsystem\fR\|(3), \fIselect\fR\|(2), \fIpoll\fR\|(2), \fIconnect\fR\|(2), \fIaccept\fR\|(2), \fIread\fR\|(2), \fIwrite\fR\|(2).
.PP
The drawback of this approach is that it depends on \fIsyscall\fR\|(2) interface
and prototype conflicts can occur while building the wrapper functions
due to different function signatures in the vendor C header files.
But the advantage of this mapping variant is that the source files of
the application where these function calls occur have not to include
\&\f(CW\*(C`pth.h\*(C'\fR and that existing libraries, including the vendor's \fBstdio\fR,
magically become thread-aware (and then block only the current thread).
.SH "IMPLEMENTATION NOTES"
.IX Header "IMPLEMENTATION NOTES"
\&\fBPth\fR is very portable because it has only one part which perhaps has
to be ported to new platforms (the machine context initialization). But
it is written in a way which works on mostly all Unix platforms which
support \fImakecontext\fR\|(2) or at least \fIsigstack\fR\|(2) or \fIsigaltstack\fR\|(2) [see
\&\f(CW\*(C`pth_mctx.c\*(C'\fR for details]. Any other \fBPth\fR code is \s-1POSIX\s0 and \s-1ANSI\s0 C
based only.
.PP
The context switching is done via either SUSv2 \fImakecontext\fR\|(2) or \s-1POSIX\s0
make[sig]\fIsetjmp\fR\|(3) and [sig]\fIlongjmp\fR\|(3). Here all \s-1CPU\s0 registers, the
program counter and the stack pointer are switched. Additionally the
\&\fBPth\fR dispatcher switches also the global Unix \f(CW\*(C`errno\*(C'\fR variable [see
\&\f(CW\*(C`pth_mctx.c\*(C'\fR for details] and the signal mask (either implicitly via
\&\fIsigsetjmp\fR\|(3) or in an emulated way via explicit \fIsetprocmask\fR\|(2) calls).
.PP
The \fBPth\fR event manager is mainly \fIselect\fR\|(2) and \fIgettimeofday\fR\|(2) based,
i.e., the current time is fetched via \fIgettimeofday\fR\|(2) once per context
switch for time calculations and all I/O events are implemented via a
single central \fIselect\fR\|(2) call [see \f(CW\*(C`pth_sched.c\*(C'\fR for details].
.PP
The thread control block management is done via virtual priority
queues without any additional data structure overhead. For this, the
queue linkage attributes are part of the thread control blocks and the
queues are actually implemented as rings with a selected element as the
entry point [see \f(CW\*(C`pth_tcb.h\*(C'\fR and \f(CW\*(C`pth_pqueue.c\*(C'\fR for details].
.PP
Most time critical code sections (especially the dispatcher and event
manager) are speeded up by inline functions (implemented as \s-1ANSI\s0 C
pre-processor macros). Additionally any debugging code is \fIcompletely\fR
removed from the source when not built with \f(CW\*(C`\-DPTH_DEBUG\*(C'\fR (see Autoconf
\&\f(CW\*(C`\-\-enable\-debug\*(C'\fR option), i.e., not only stub functions remain [see
\&\f(CW\*(C`pth_debug.c\*(C'\fR for details].
.SH "RESTRICTIONS"
.IX Header "RESTRICTIONS"
\&\fBPth\fR (intentionally) provides no replacements for non-thread-safe
functions (like \fIstrtok\fR\|(3) which uses a static internal buffer) or
synchronous system functions (like \fIgethostbyname\fR\|(3) which doesn't
provide an asynchronous mode where it doesn't block). When you want to
use those functions in your server application together with threads,
you've to either link the application against special third-party
libraries (or for thread\-safe/reentrant functions possibly against an
existing \f(CW\*(C`libc_r\*(C'\fR of the platform vendor). For an asynchronous \s-1DNS\s0
resolver library use the \s-1GNU\s0 \fBadns\fR package from Ian Jackson ( see
http://www.gnu.org/software/adns/adns.html ).
.SH "HISTORY"
.IX Header "HISTORY"
The \fBPth\fR library was designed and implemented between February and
July 1999 by \fIRalf S. Engelschall\fR after evaluating numerous (mostly
preemptive) thread libraries and after intensive discussions with
\&\fIPeter Simons\fR, \fIMartin Kraemer\fR, \fILars Eilebrecht\fR and \fIRalph
Babel\fR related to an experimental (matrix based) non-preemptive \*(C+
scheduler class written by \fIPeter Simons\fR.
.PP
\&\fBPth\fR was then implemented in order to combine the \fInon-preemptive\fR
approach of multithreading (which provides better portability and
performance) with an \s-1API\s0 similar to the popular one found in \fBPthread\fR
libraries (which provides easy programming).
.PP
So the essential idea of the non-preemptive approach was taken over from
\&\fIPeter Simons\fR scheduler. The priority based scheduling algorithm was
suggested by \fIMartin Kraemer\fR. Some code inspiration also came from
an experimental threading library (\fBrsthreads\fR) written by \fIRobert
S. Thau\fR for an ancient internal test version of the Apache webserver.
The concept and \s-1API\s0 of message ports was borrowed from AmigaOS' \fBExec\fR
subsystem. The concept and idea for the flexible event mechanism came
from \fIPaul Vixie\fR's \fBeventlib\fR (which can be found as a part of
\&\fB\s-1BIND\s0\fR v8).
.SH "BUG REPORTS AND SUPPORT"
.IX Header "BUG REPORTS AND SUPPORT"
If you think you have found a bug in \fBPth\fR, you should send a report as
complete as possible to \fIbug\-pth@gnu.org\fR. If you can, please try to
fix the problem and include a patch, made with '\f(CW\*(C`diff \-u3\*(C'\fR', in your
report. Always, at least, include a reasonable amount of description in
your report to allow the author to deterministically reproduce the bug.
.PP
For further support you additionally can subscribe to the
\&\fIpth\-users@gnu.org\fR mailing list by sending an Email to
\&\fIpth\-users\-request@gnu.org\fR with `\f(CW\*(C`subscribe pth\-users\*(C'\fR' (or
`\f(CW\*(C`subscribe pth\-users\*(C'\fR \fIaddress\fR' if you want to subscribe
from a particular Email \fIaddress\fR) in the body. Then you can
discuss your issues with other \fBPth\fR users by sending messages to
\&\fIpth\-users@gnu.org\fR. Currently (as of August 2000) you can reach about
110 Pth users on this mailing list. Old postings you can find at
\&\fIhttp://www.mail\-archive.com/pth\-users@gnu.org/\fR.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.Sh "Related Web Locations"
.IX Subsection "Related Web Locations"
`comp.programming.threads Newsgroup Archive',
http://www.deja.com/topics_if.xp?
search=topic&group=comp.programming.threads
.PP
`comp.programming.threads Frequently Asked Questions (F.A.Q.)',
http://www.lambdacs.com/newsgroup/FAQ.html
.PP
`\fIMultithreading \- Definitions and Guidelines\fR',
Numeric Quest Inc 1998;
http://www.numeric\-quest.com/lang/multi\-frame.html
.PP
`\fIThe Single \s-1UNIX\s0 Specification, Version 2 \- Threads\fR',
The Open Group 1997;
http://www.opengroup.org/onlinepubs /007908799/xsh/threads.html
.PP
\&\s-1SMI\s0 Thread Resources,
Sun Microsystems Inc;
http://www.sun.com/workshop/threads/
.PP
Bibliography on threads and multithreading,
Torsten Amundsen;
http://liinwww.ira.uka.de/bibliography/Os/threads.html
.Sh "Related Books"
.IX Subsection "Related Books"
B. Nichols, D. Buttlar, J.P. Farrel:
`\fIPthreads Programming \- A \s-1POSIX\s0 Standard for Better Multiprocessing\fR',
O'Reilly 1996;
\&\s-1ISBN\s0 1\-56592\-115\-1
.PP
B. Lewis, D. J. Berg:
`\fIMultithreaded Programming with Pthreads\fR',
Sun Microsystems Press, Prentice Hall 1998;
\&\s-1ISBN\s0 0\-13\-680729\-1
.PP
B. Lewis, D. J. Berg:
`\fIThreads Primer \- A Guide To Multithreaded Programming\fR',
Prentice Hall 1996;
\&\s-1ISBN\s0 0\-13\-443698\-9
.PP
S. J. Norton, M. D. Dipasquale:
`\fIThread Time \- The Multithreaded Programming Guide\fR',
Prentice Hall 1997;
\&\s-1ISBN\s0 0\-13\-190067\-6
.PP
D. R. Butenhof:
`\fIProgramming with \s-1POSIX\s0 Threads\fR',
Addison Wesley 1997;
\&\s-1ISBN\s0 0\-201\-63392\-2
.Sh "Related Manpages"
.IX Subsection "Related Manpages"
\&\fIpth\-config\fR\|(1), \fIpthread\fR\|(3).
.PP
\&\fIgetcontext\fR\|(2), \fIsetcontext\fR\|(2), \fImakecontext\fR\|(2), \fIswapcontext\fR\|(2),
\&\fIsigstack\fR\|(2), \fIsigaltstack\fR\|(2), \fIsigaction\fR\|(2), \fIsigemptyset\fR\|(2), \fIsigaddset\fR\|(2),
\&\fIsigprocmask\fR\|(2), \fIsigsuspend\fR\|(2), \fIsigsetjmp\fR\|(3), \fIsiglongjmp\fR\|(3), \fIsetjmp\fR\|(3),
\&\fIlongjmp\fR\|(3), \fIselect\fR\|(2), \fIgettimeofday\fR\|(2).
.SH "AUTHOR"
.IX Header "AUTHOR"
.Vb 3
\& Ralf S. Engelschall
\& rse@engelschall.com
\& www.engelschall.com
.Ve