head	1.234;
access;
symbols
	PTH_1_4:1.232.0.2
	PTH_1_4_1:1.232
	PTH_1_4_0:1.230
	PTH_1_3_7:1.208.2.7
	PTH_1_4a3:1.220
	PTH_1_3_6:1.208.2.5
	PTH_1_4a2:1.218
	PTH_1_3_5:1.208.2.4
	PTH_1_4a1:1.214
	PTH_1_3_4:1.208.2.3
	PTH_1_3:1.208.0.2
	PTH_1_3_3:1.208
	PTH_1_3_2:1.203
	PTH_1_3_1:1.201
	PTH_1_3_0:1.200
	PTH_1_3b3:1.195
	PTH_1_2_3:1.169.2.6
	PTH_1_3b2:1.191
	PTH_1_3b1:1.183
	PTH_1_3a5:1.180
	PTH_1_3a4:1.178
	PTH_1_3a3:1.177
	PTH_1_2_2:1.169.2.5
	PTH_1_3a2:1.174
	PTH_1_2_1:1.169.2.2
	PTH_1_3a1:1.171
	PTH_1_2:1.169.0.2
	PTH_1_2_0:1.169
	PTH_1_2b8:1.167
	PTH_1_2b7:1.163
	PTH_1_1_6:1.148.2.5
	PTH_1_2b6:1.159
	PTH_1_2b5:1.157
	PTH_1_2b4:1.156
	PTH_1_2b3:1.155
	PTH_1_2b2:1.152
	PTH_1_2b1:1.150
	PTH_1_1_5:1.148.2.2
	PTH_1_0_6:1.119.2.2
	PTH_1_0_5:1.119.2.1
	PTH_1_0:1.119.0.2
	PTH_1_1:1.148.0.2
	PTH_1_1_4:1.148
	PTH_1_1_3:1.146
	PTH_1_1_2:1.144
	PTH_1_1_1:1.142
	PTH_1_1_0:1.139
	PTH_1_1b7:1.136
	PTH_1_1b6:1.135
	PTH_1_1b5:1.133
	PTH_1_1b4:1.130
	PTH_1_1b3:1.129
	PTH_1_1b2:1.126
	PTH_1_1b1:1.124
	PTH_1_0_4:1.119
	PTH_1_0_3:1.115
	PTH_1_0_2:1.113
	PTH_1_0_1:1.108
	PTH_1_0_0:1.103
	PTH_1_0b8:1.99
	PTH_1_0b7:1.98
	PTH_1_0b6:1.97
	PTH_1_0b5:1.95
	PTH_1_0b4:1.89
	PTH_1_0b3:1.81
	PTH_1_0b2:1.77
	PTH_1_0b1:1.70
	PTH_0_9_21:1.62
	PTH_0_9_20:1.59
	PTH_0_9_19:1.51
	PTH_0_9_18:1.44
	PTH_0_9_17:1.38
	PTH_0_9_16:1.36
	PTH_0_9_15:1.34
	PTH_0_9_14:1.30
	PTH_0_9_13:1.28
	PTH_0_9_12:1.26
	PTH_0_9_11:1.24
	PTH_0_9_10:1.23
	PTH_0_9_9:1.19
	PTH_0_9_8:1.16
	PTH_0_9_7:1.7
	PTH_0_9_6:1.6
	PTH_0_9_5:1.4
	PTH_0_9_4:1.4
	PTH_0_9_3:1.2
	PTH_0_9_2:1.2
	PTH_0_9_1:1.2
	PTH_0_9_0:1.1.1.1
	RSE:1.1.1;
locks; strict;
comment	@.\" @;
expand	@o@;


1.234
date	2002.01.30.12.54.23;	author rse;	state dead;
branches;
next	1.233;

1.233
date	2002.01.27.16.14.01;	author rse;	state Exp;
branches;
next	1.232;

1.232
date	2002.01.27.12.34.30;	author rse;	state Exp;
branches;
next	1.231;

1.231
date	2001.07.12.07.20.04;	author rse;	state Exp;
branches;
next	1.230;

1.230
date	2001.03.24.16.30.36;	author rse;	state Exp;
branches;
next	1.229;

1.229
date	2001.03.24.14.56.47;	author rse;	state Exp;
branches;
next	1.228;

1.228
date	2001.03.24.14.37.06;	author rse;	state Exp;
branches;
next	1.227;

1.227
date	2001.03.24.13.49.06;	author rse;	state Exp;
branches;
next	1.226;

1.226
date	2001.02.25.17.15.54;	author rse;	state Exp;
branches;
next	1.225;

1.225
date	2000.10.03.08.00.35;	author rse;	state Exp;
branches;
next	1.224;

1.224
date	2000.09.30.08.00.18;	author rse;	state Exp;
branches;
next	1.223;

1.223
date	2000.08.18.08.47.51;	author rse;	state Exp;
branches;
next	1.222;

1.222
date	2000.08.18.08.35.29;	author rse;	state Exp;
branches;
next	1.221;

1.221
date	2000.08.18.07.39.09;	author rse;	state Exp;
branches;
next	1.220;

1.220
date	2000.07.18.09.03.20;	author rse;	state Exp;
branches;
next	1.219;

1.219
date	2000.07.10.06.18.08;	author rse;	state Exp;
branches;
next	1.218;

1.218
date	2000.07.01.12.40.51;	author rse;	state Exp;
branches;
next	1.217;

1.217
date	2000.05.21.09.10.01;	author rse;	state Exp;
branches;
next	1.216;

1.216
date	2000.04.19.15.37.13;	author rse;	state Exp;
branches;
next	1.215;

1.215
date	2000.04.17.16.18.13;	author rse;	state Exp;
branches;
next	1.214;

1.214
date	2000.04.16.14.04.28;	author rse;	state Exp;
branches;
next	1.213;

1.213
date	2000.03.31.19.06.02;	author rse;	state Exp;
branches;
next	1.212;

1.212
date	2000.03.27.17.03.25;	author rse;	state Exp;
branches;
next	1.211;

1.211
date	2000.03.12.19.13.42;	author rse;	state Exp;
branches;
next	1.210;

1.210
date	2000.03.12.16.43.16;	author rse;	state Exp;
branches;
next	1.209;

1.209
date	2000.03.12.13.41.42;	author rse;	state Exp;
branches;
next	1.208;

1.208
date	2000.03.10.10.13.51;	author rse;	state Exp;
branches
	1.208.2.1;
next	1.207;

1.207
date	2000.03.10.09.32.39;	author rse;	state Exp;
branches;
next	1.206;

1.206
date	2000.03.09.12.13.24;	author rse;	state Exp;
branches;
next	1.205;

1.205
date	2000.03.07.19.28.29;	author rse;	state Exp;
branches;
next	1.204;

1.204
date	2000.03.07.19.26.26;	author rse;	state Exp;
branches;
next	1.203;

1.203
date	2000.02.24.12.43.17;	author rse;	state Exp;
branches;
next	1.202;

1.202
date	2000.02.24.12.35.00;	author rse;	state Exp;
branches;
next	1.201;

1.201
date	2000.02.20.11.42.45;	author rse;	state Exp;
branches;
next	1.200;

1.200
date	2000.02.19.15.48.10;	author rse;	state Exp;
branches;
next	1.199;

1.199
date	2000.02.17.16.58.39;	author rse;	state Exp;
branches;
next	1.198;

1.198
date	2000.02.15.07.43.14;	author rse;	state Exp;
branches;
next	1.197;

1.197
date	2000.02.15.07.41.35;	author rse;	state Exp;
branches;
next	1.196;

1.196
date	2000.02.13.19.17.36;	author rse;	state Exp;
branches;
next	1.195;

1.195
date	2000.02.13.17.24.02;	author rse;	state Exp;
branches;
next	1.194;

1.194
date	2000.02.11.11.22.23;	author rse;	state Exp;
branches;
next	1.193;

1.193
date	2000.02.04.21.45.29;	author rse;	state Exp;
branches;
next	1.192;

1.192
date	2000.01.28.14.48.54;	author rse;	state Exp;
branches;
next	1.191;

1.191
date	2000.01.28.14.28.40;	author rse;	state Exp;
branches;
next	1.190;

1.190
date	2000.01.27.17.59.23;	author rse;	state Exp;
branches;
next	1.189;

1.189
date	2000.01.27.17.48.18;	author rse;	state Exp;
branches;
next	1.188;

1.188
date	2000.01.27.16.09.39;	author rse;	state Exp;
branches;
next	1.187;

1.187
date	2000.01.27.13.55.53;	author rse;	state Exp;
branches;
next	1.186;

1.186
date	2000.01.27.12.53.01;	author rse;	state Exp;
branches;
next	1.185;

1.185
date	2000.01.26.13.06.38;	author rse;	state Exp;
branches;
next	1.184;

1.184
date	2000.01.26.10.38.09;	author rse;	state Exp;
branches;
next	1.183;

1.183
date	2000.01.26.10.04.35;	author rse;	state Exp;
branches;
next	1.182;

1.182
date	2000.01.26.10.02.26;	author rse;	state Exp;
branches;
next	1.181;

1.181
date	2000.01.24.15.02.37;	author rse;	state Exp;
branches;
next	1.180;

1.180
date	2000.01.15.15.53.37;	author rse;	state Exp;
branches;
next	1.179;

1.179
date	2000.01.13.07.27.14;	author rse;	state Exp;
branches;
next	1.178;

1.178
date	2000.01.08.16.26.10;	author rse;	state Exp;
branches;
next	1.177;

1.177
date	2000.01.08.15.20.12;	author rse;	state Exp;
branches;
next	1.176;

1.176
date	2000.01.07.22.45.06;	author rse;	state Exp;
branches;
next	1.175;

1.175
date	2000.01.03.18.38.57;	author rse;	state Exp;
branches;
next	1.174;

1.174
date	99.12.30.21.56.59;	author rse;	state Exp;
branches;
next	1.173;

1.173
date	99.12.24.18.19.49;	author rse;	state Exp;
branches;
next	1.172;

1.172
date	99.11.09.08.12.55;	author rse;	state Exp;
branches;
next	1.171;

1.171
date	99.11.09.07.56.46;	author rse;	state Exp;
branches;
next	1.170;

1.170
date	99.11.01.10.27.18;	author rse;	state Exp;
branches;
next	1.169;

1.169
date	99.10.31.14.53.48;	author rse;	state Exp;
branches
	1.169.2.1;
next	1.168;

1.168
date	99.10.31.11.48.52;	author rse;	state Exp;
branches;
next	1.167;

1.167
date	99.10.26.14.33.35;	author rse;	state Exp;
branches;
next	1.166;

1.166
date	99.10.26.14.24.27;	author rse;	state Exp;
branches;
next	1.165;

1.165
date	99.10.26.14.17.27;	author rse;	state Exp;
branches;
next	1.164;

1.164
date	99.10.26.09.01.00;	author rse;	state Exp;
branches;
next	1.163;

1.163
date	99.10.22.07.13.26;	author rse;	state Exp;
branches;
next	1.162;

1.162
date	99.10.19.13.42.06;	author rse;	state Exp;
branches;
next	1.161;

1.161
date	99.10.19.12.46.39;	author rse;	state Exp;
branches;
next	1.160;

1.160
date	99.10.19.12.18.26;	author rse;	state Exp;
branches;
next	1.159;

1.159
date	99.09.28.08.59.17;	author rse;	state Exp;
branches;
next	1.158;

1.158
date	99.09.25.12.46.24;	author rse;	state Exp;
branches;
next	1.157;

1.157
date	99.09.21.12.13.58;	author rse;	state Exp;
branches;
next	1.156;

1.156
date	99.09.17.10.56.41;	author rse;	state Exp;
branches;
next	1.155;

1.155
date	99.09.17.08.11.08;	author rse;	state Exp;
branches;
next	1.154;

1.154
date	99.09.17.08.07.17;	author rse;	state Exp;
branches;
next	1.153;

1.153
date	99.09.05.13.47.12;	author rse;	state Exp;
branches;
next	1.152;

1.152
date	99.09.04.12.34.48;	author rse;	state Exp;
branches;
next	1.151;

1.151
date	99.09.02.17.26.22;	author rse;	state Exp;
branches;
next	1.150;

1.150
date	99.09.02.12.19.54;	author rse;	state Exp;
branches;
next	1.149;

1.149
date	99.08.31.08.40.11;	author rse;	state Exp;
branches;
next	1.148;

1.148
date	99.08.30.17.21.03;	author rse;	state Exp;
branches
	1.148.2.1;
next	1.147;

1.147
date	99.08.27.16.29.13;	author rse;	state Exp;
branches;
next	1.146;

1.146
date	99.08.27.15.28.15;	author rse;	state Exp;
branches;
next	1.145;

1.145
date	99.08.26.16.29.13;	author rse;	state Exp;
branches;
next	1.144;

1.144
date	99.08.23.12.00.53;	author rse;	state Exp;
branches;
next	1.143;

1.143
date	99.08.21.13.07.36;	author rse;	state Exp;
branches;
next	1.142;

1.142
date	99.08.21.12.30.53;	author rse;	state Exp;
branches;
next	1.141;

1.141
date	99.08.20.14.05.49;	author rse;	state Exp;
branches;
next	1.140;

1.140
date	99.08.20.07.20.27;	author rse;	state Exp;
branches;
next	1.139;

1.139
date	99.08.19.15.16.59;	author rse;	state Exp;
branches;
next	1.138;

1.138
date	99.08.19.14.37.42;	author rse;	state Exp;
branches;
next	1.137;

1.137
date	99.08.19.14.34.21;	author rse;	state Exp;
branches;
next	1.136;

1.136
date	99.08.18.13.33.15;	author rse;	state Exp;
branches;
next	1.135;

1.135
date	99.08.18.12.59.33;	author rse;	state Exp;
branches;
next	1.134;

1.134
date	99.08.17.10.23.29;	author rse;	state Exp;
branches;
next	1.133;

1.133
date	99.08.17.09.11.10;	author rse;	state Exp;
branches;
next	1.132;

1.132
date	99.08.17.09.08.25;	author rse;	state Exp;
branches;
next	1.131;

1.131
date	99.08.13.20.40.13;	author rse;	state Exp;
branches;
next	1.130;

1.130
date	99.08.13.15.54.29;	author rse;	state Exp;
branches;
next	1.129;

1.129
date	99.08.11.10.12.11;	author rse;	state Exp;
branches;
next	1.128;

1.128
date	99.08.11.09.30.54;	author rse;	state Exp;
branches;
next	1.127;

1.127
date	99.08.11.07.46.05;	author rse;	state Exp;
branches;
next	1.126;

1.126
date	99.08.10.07.58.58;	author rse;	state Exp;
branches;
next	1.125;

1.125
date	99.08.07.15.50.00;	author rse;	state Exp;
branches;
next	1.124;

1.124
date	99.08.07.12.11.25;	author rse;	state Exp;
branches;
next	1.123;

1.123
date	99.08.03.12.56.35;	author rse;	state Exp;
branches;
next	1.122;

1.122
date	99.08.03.12.31.43;	author rse;	state Exp;
branches;
next	1.121;

1.121
date	99.08.03.12.29.46;	author rse;	state Exp;
branches;
next	1.120;

1.120
date	99.08.03.12.24.02;	author rse;	state Exp;
branches;
next	1.119;

1.119
date	99.08.03.10.42.28;	author rse;	state Exp;
branches
	1.119.2.1;
next	1.118;

1.118
date	99.08.02.12.26.10;	author rse;	state Exp;
branches;
next	1.117;

1.117
date	99.08.01.10.16.30;	author rse;	state Exp;
branches;
next	1.116;

1.116
date	99.07.30.10.47.18;	author rse;	state Exp;
branches;
next	1.115;

1.115
date	99.07.30.07.13.59;	author rse;	state Exp;
branches;
next	1.114;

1.114
date	99.07.30.06.19.42;	author rse;	state Exp;
branches;
next	1.113;

1.113
date	99.07.28.07.08.37;	author rse;	state Exp;
branches;
next	1.112;

1.112
date	99.07.25.08.38.55;	author rse;	state Exp;
branches;
next	1.111;

1.111
date	99.07.24.14.22.40;	author rse;	state Exp;
branches;
next	1.110;

1.110
date	99.07.24.13.16.17;	author rse;	state Exp;
branches;
next	1.109;

1.109
date	99.07.23.13.39.42;	author rse;	state Exp;
branches;
next	1.108;

1.108
date	99.07.22.15.55.37;	author rse;	state Exp;
branches;
next	1.107;

1.107
date	99.07.22.15.49.04;	author rse;	state Exp;
branches;
next	1.106;

1.106
date	99.07.22.14.55.09;	author rse;	state Exp;
branches;
next	1.105;

1.105
date	99.07.19.06.15.58;	author rse;	state Exp;
branches;
next	1.104;

1.104
date	99.07.17.14.55.00;	author rse;	state Exp;
branches;
next	1.103;

1.103
date	99.07.16.14.52.19;	author rse;	state Exp;
branches;
next	1.102;

1.102
date	99.07.16.11.44.20;	author rse;	state Exp;
branches;
next	1.101;

1.101
date	99.07.16.11.41.51;	author rse;	state Exp;
branches;
next	1.100;

1.100
date	99.07.16.11.15.57;	author rse;	state Exp;
branches;
next	1.99;

1.99
date	99.07.16.08.46.45;	author rse;	state Exp;
branches;
next	1.98;

1.98
date	99.07.14.07.09.25;	author rse;	state Exp;
branches;
next	1.97;

1.97
date	99.07.14.06.29.05;	author rse;	state Exp;
branches;
next	1.96;

1.96
date	99.07.12.13.46.01;	author rse;	state Exp;
branches;
next	1.95;

1.95
date	99.07.11.15.39.39;	author rse;	state Exp;
branches;
next	1.94;

1.94
date	99.07.10.15.14.47;	author rse;	state Exp;
branches;
next	1.93;

1.93
date	99.07.10.14.21.17;	author rse;	state Exp;
branches;
next	1.92;

1.92
date	99.07.09.08.06.40;	author rse;	state Exp;
branches;
next	1.91;

1.91
date	99.07.08.15.01.37;	author rse;	state Exp;
branches;
next	1.90;

1.90
date	99.07.08.15.01.17;	author rse;	state Exp;
branches;
next	1.89;

1.89
date	99.07.08.10.47.50;	author rse;	state Exp;
branches;
next	1.88;

1.88
date	99.07.08.10.39.39;	author rse;	state Exp;
branches;
next	1.87;

1.87
date	99.07.08.10.35.54;	author rse;	state Exp;
branches;
next	1.86;

1.86
date	99.07.08.10.27.47;	author rse;	state Exp;
branches;
next	1.85;

1.85
date	99.07.08.10.20.05;	author rse;	state Exp;
branches;
next	1.84;

1.84
date	99.07.08.10.17.07;	author rse;	state Exp;
branches;
next	1.83;

1.83
date	99.07.08.10.17.03;	author rse;	state Exp;
branches;
next	1.82;

1.82
date	99.07.08.09.40.59;	author rse;	state Exp;
branches;
next	1.81;

1.81
date	99.07.07.19.04.42;	author rse;	state Exp;
branches;
next	1.80;

1.80
date	99.07.07.19.02.28;	author rse;	state Exp;
branches;
next	1.79;

1.79
date	99.07.04.15.42.34;	author rse;	state Exp;
branches;
next	1.78;

1.78
date	99.07.04.15.39.12;	author rse;	state Exp;
branches;
next	1.77;

1.77
date	99.07.04.13.00.51;	author rse;	state Exp;
branches;
next	1.76;

1.76
date	99.07.04.12.21.20;	author rse;	state Exp;
branches;
next	1.75;

1.75
date	99.07.04.12.01.42;	author rse;	state Exp;
branches;
next	1.74;

1.74
date	99.07.04.11.04.52;	author rse;	state Exp;
branches;
next	1.73;

1.73
date	99.07.01.08.28.47;	author rse;	state Exp;
branches;
next	1.72;

1.72
date	99.06.28.17.15.56;	author rse;	state Exp;
branches;
next	1.71;

1.71
date	99.06.28.15.04.23;	author rse;	state Exp;
branches;
next	1.70;

1.70
date	99.06.28.13.17.04;	author rse;	state Exp;
branches;
next	1.69;

1.69
date	99.06.28.11.36.26;	author rse;	state Exp;
branches;
next	1.68;

1.68
date	99.06.28.10.02.06;	author rse;	state Exp;
branches;
next	1.67;

1.67
date	99.06.28.09.45.24;	author rse;	state Exp;
branches;
next	1.66;

1.66
date	99.06.28.07.51.55;	author rse;	state Exp;
branches;
next	1.65;

1.65
date	99.06.27.15.40.29;	author rse;	state Exp;
branches;
next	1.64;

1.64
date	99.06.27.15.38.03;	author rse;	state Exp;
branches;
next	1.63;

1.63
date	99.06.26.14.07.12;	author rse;	state Exp;
branches;
next	1.62;

1.62
date	99.06.26.12.58.14;	author rse;	state Exp;
branches;
next	1.61;

1.61
date	99.06.26.12.48.04;	author rse;	state Exp;
branches;
next	1.60;

1.60
date	99.06.26.12.47.55;	author rse;	state Exp;
branches;
next	1.59;

1.59
date	99.06.25.15.28.13;	author rse;	state Exp;
branches;
next	1.58;

1.58
date	99.06.25.15.15.39;	author rse;	state Exp;
branches;
next	1.57;

1.57
date	99.06.25.09.10.29;	author rse;	state Exp;
branches;
next	1.56;

1.56
date	99.06.24.12.24.46;	author rse;	state Exp;
branches;
next	1.55;

1.55
date	99.06.24.11.50.04;	author rse;	state Exp;
branches;
next	1.54;

1.54
date	99.06.24.10.54.28;	author rse;	state Exp;
branches;
next	1.53;

1.53
date	99.06.24.10.47.23;	author rse;	state Exp;
branches;
next	1.52;

1.52
date	99.06.23.07.14.37;	author rse;	state Exp;
branches;
next	1.51;

1.51
date	99.06.21.15.31.53;	author rse;	state Exp;
branches;
next	1.50;

1.50
date	99.06.21.15.31.32;	author rse;	state Exp;
branches;
next	1.49;

1.49
date	99.06.21.15.24.03;	author rse;	state Exp;
branches;
next	1.48;

1.48
date	99.06.21.10.31.29;	author rse;	state Exp;
branches;
next	1.47;

1.47
date	99.06.21.10.11.44;	author rse;	state Exp;
branches;
next	1.46;

1.46
date	99.06.21.10.08.28;	author rse;	state Exp;
branches;
next	1.45;

1.45
date	99.06.21.08.34.16;	author rse;	state Exp;
branches;
next	1.44;

1.44
date	99.06.20.10.05.31;	author rse;	state Exp;
branches;
next	1.43;

1.43
date	99.06.20.09.52.02;	author rse;	state Exp;
branches;
next	1.42;

1.42
date	99.06.20.09.44.27;	author rse;	state Exp;
branches;
next	1.41;

1.41
date	99.06.20.09.28.39;	author rse;	state Exp;
branches;
next	1.40;

1.40
date	99.06.19.11.53.10;	author rse;	state Exp;
branches;
next	1.39;

1.39
date	99.06.19.11.49.20;	author rse;	state Exp;
branches;
next	1.38;

1.38
date	99.06.18.09.28.31;	author rse;	state Exp;
branches;
next	1.37;

1.37
date	99.06.12.15.00.21;	author rse;	state Exp;
branches;
next	1.36;

1.36
date	99.06.09.06.51.19;	author rse;	state Exp;
branches;
next	1.35;

1.35
date	99.06.04.11.42.04;	author rse;	state Exp;
branches;
next	1.34;

1.34
date	99.06.04.11.01.42;	author rse;	state Exp;
branches;
next	1.33;

1.33
date	99.06.04.10.47.42;	author rse;	state Exp;
branches;
next	1.32;

1.32
date	99.06.04.07.46.32;	author rse;	state Exp;
branches;
next	1.31;

1.31
date	99.06.03.09.28.04;	author rse;	state Exp;
branches;
next	1.30;

1.30
date	99.06.01.15.53.03;	author rse;	state Exp;
branches;
next	1.29;

1.29
date	99.06.01.15.29.22;	author rse;	state Exp;
branches;
next	1.28;

1.28
date	99.06.01.09.55.26;	author rse;	state Exp;
branches;
next	1.27;

1.27
date	99.06.01.07.56.34;	author rse;	state Exp;
branches;
next	1.26;

1.26
date	99.05.30.10.09.14;	author rse;	state Exp;
branches;
next	1.25;

1.25
date	99.05.30.09.33.48;	author rse;	state Exp;
branches;
next	1.24;

1.24
date	99.05.28.16.26.33;	author rse;	state Exp;
branches;
next	1.23;

1.23
date	99.05.28.10.31.53;	author rse;	state Exp;
branches;
next	1.22;

1.22
date	99.05.28.10.30.19;	author rse;	state Exp;
branches;
next	1.21;

1.21
date	99.05.25.17.37.40;	author rse;	state Exp;
branches;
next	1.20;

1.20
date	99.05.25.17.36.52;	author rse;	state Exp;
branches;
next	1.19;

1.19
date	99.05.25.14.35.02;	author rse;	state Exp;
branches;
next	1.18;

1.18
date	99.05.25.11.53.29;	author rse;	state Exp;
branches;
next	1.17;

1.17
date	99.05.24.15.54.12;	author rse;	state Exp;
branches;
next	1.16;

1.16
date	99.05.24.11.13.53;	author rse;	state Exp;
branches;
next	1.15;

1.15
date	99.05.24.11.10.23;	author rse;	state Exp;
branches;
next	1.14;

1.14
date	99.05.24.10.24.23;	author rse;	state Exp;
branches;
next	1.13;

1.13
date	99.05.24.10.07.44;	author rse;	state Exp;
branches;
next	1.12;

1.12
date	99.05.24.08.06.52;	author rse;	state Exp;
branches;
next	1.11;

1.11
date	99.05.24.07.58.13;	author rse;	state Exp;
branches;
next	1.10;

1.10
date	99.05.24.07.45.56;	author rse;	state Exp;
branches;
next	1.9;

1.9
date	99.05.24.07.27.59;	author rse;	state Exp;
branches;
next	1.8;

1.8
date	99.05.23.16.09.06;	author rse;	state Exp;
branches;
next	1.7;

1.7
date	99.05.23.12.37.55;	author rse;	state Exp;
branches;
next	1.6;

1.6
date	99.05.22.14.37.52;	author rse;	state Exp;
branches;
next	1.5;

1.5
date	99.05.21.16.36.26;	author rse;	state Exp;
branches;
next	1.4;

1.4
date	99.05.21.09.44.10;	author rse;	state Exp;
branches;
next	1.3;

1.3
date	99.05.19.15.46.24;	author rse;	state Exp;
branches;
next	1.2;

1.2
date	99.05.13.15.38.49;	author rse;	state Exp;
branches;
next	1.1;

1.1
date	99.05.13.12.18.16;	author rse;	state Exp;
branches
	1.1.1.1;
next	;

1.1.1.1
date	99.05.13.12.18.16;	author rse;	state Exp;
branches;
next	;

1.119.2.1
date	99.08.31.08.30.28;	author rse;	state Exp;
branches;
next	1.119.2.2;

1.119.2.2
date	99.08.31.08.32.17;	author rse;	state Exp;
branches;
next	;

1.148.2.1
date	99.09.01.10.54.34;	author rse;	state Exp;
branches;
next	1.148.2.2;

1.148.2.2
date	99.09.02.12.00.26;	author rse;	state Exp;
branches;
next	1.148.2.3;

1.148.2.3
date	99.09.24.21.52.52;	author rse;	state Exp;
branches;
next	1.148.2.4;

1.148.2.4
date	99.09.25.11.44.47;	author rse;	state Exp;
branches;
next	1.148.2.5;

1.148.2.5
date	99.09.28.09.04.01;	author rse;	state Exp;
branches;
next	;

1.169.2.1
date	99.11.09.08.07.35;	author rse;	state Exp;
branches;
next	1.169.2.2;

1.169.2.2
date	99.11.14.13.04.42;	author rse;	state Exp;
branches;
next	1.169.2.3;

1.169.2.3
date	2000.01.07.23.00.35;	author rse;	state Exp;
branches;
next	1.169.2.4;

1.169.2.4
date	2000.01.07.23.16.16;	author rse;	state Exp;
branches;
next	1.169.2.5;

1.169.2.5
date	2000.01.08.15.02.59;	author rse;	state Exp;
branches;
next	1.169.2.6;

1.169.2.6
date	2000.02.04.22.07.17;	author rse;	state Exp;
branches;
next	1.169.2.7;

1.169.2.7
date	2000.02.11.11.32.41;	author rse;	state Exp;
branches;
next	;

1.208.2.1
date	2000.03.23.19.44.58;	author rse;	state Exp;
branches;
next	1.208.2.2;

1.208.2.2
date	2000.03.29.16.22.37;	author rse;	state Exp;
branches;
next	1.208.2.3;

1.208.2.3
date	2000.04.16.11.20.24;	author rse;	state Exp;
branches;
next	1.208.2.4;

1.208.2.4
date	2000.04.17.15.39.52;	author rse;	state Exp;
branches;
next	1.208.2.5;

1.208.2.5
date	2000.07.01.14.07.10;	author rse;	state Exp;
branches;
next	1.208.2.6;

1.208.2.6
date	2000.07.29.14.57.14;	author rse;	state Exp;
branches;
next	1.208.2.7;

1.208.2.7
date	2000.07.29.15.04.34;	author rse;	state Exp;
branches;
next	;


desc
@@


1.234
log
@Woohhooo! Major GNU Pth source tree overhauling:
- Removed all generated files from CVS.
- Use OSSP devtool stuff to re-generate files on demand.
- Switched to Autoconf 2.52 and Libtool 1.4.2 environment.
@
text
@.\" Automatically generated by Pod::Man version 1.15
.\" Sun Jan 27 17:13:13 2002
.\"
.\" 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 Ip \" List item
.br
.ie \\n(.$>=3 .ne \\$3
.el .ne 3
.IP "\\$1" \\$2
..
.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.
.bd B 3
.    \" 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 "27-Jan-2002" "GNU Pth 1.5b1" "GNU Portable Threads"
.UC
.SH "NAME"
\&\fBpth\fR \- \s-1GNU\s0 Portable Threads
.SH "VERSION"
.IX Header "VERSION"
\&\s-1GNU\s0 Pth \s-11.5b1 (27-Jan-2002)\s0
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Ip "\fBGlobal Library Management\fR" 4
.IX Item "Global Library Management"
pth_init,
pth_kill,
pth_ctrl,
pth_version.
.Ip "\fBThread Attribute Handling\fR" 4
.IX Item "Thread Attribute Handling"
pth_attr_of,
pth_attr_new,
pth_attr_init,
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_occurred,
pth_event_free.
.Ip "\fBKey-Based Storage\fR" 4
.IX Item "Key-Based Storage"
pth_key_create,
pth_key_delete,
pth_key_setdata,
pth_key_getdata.
.Ip "\fBMessage Port Communication\fR" 4
.IX Item "Message Port Communication"
pth_msgport_create,
pth_msgport_destroy,
pth_msgport_find,
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 "\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_usleep,
pth_sleep,
pth_waitpid,
pth_system,
pth_sigmask,
pth_sigwait,
pth_accept,
pth_connect,
pth_select,
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
\&\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 \fIhundreds\fR\|(!) 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 its 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
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 for
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 be
now easy to understand how to program threads with this \s-1API\s0. In good
Unix tradition, \fBPth\fR functions use special return values (\f(CW\*(C`NULL\*(C'\fR
in pointer context, \f(CW\*(C`FALSE\*(C'\fR in boolean context and \f(CW\*(C`\-1\*(C'\fR in integer
context) to indicate an error condition and set (or pass through) the
\&\f(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 called not from within the main thread. Else
kills the threading system and returns \f(CW\*(C`TRUE\*(C'\fR.
.Ip "long \fBpth_ctrl\fR(unsigned long \fIquery\fR, ...);" 4
.IX Item "long pth_ctrl(unsigned long query, ...);"
This is a generalized query/control function for the \fBPth\fR library.  The
argument \fIquery\fR is a bitmask formed out of one or more \f(CW\*(C`PTH_CTRL_\*(C'\fR\fI\s-1XXXX\s0\fR
queries. Currently the following queries are supported:
.RS 4
.if n .Ip "\f(CW""""PTH_CTRL_GETTHREADS""""\fR" 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).
.if n .Ip "\f(CW""""PTH_CTRL_GETAVLOAD""""\fR" 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.
.if n .Ip "\f(CW""""PTH_CTRL_GETPRIO""""\fR" 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.
.if n .Ip "\f(CW""""PTH_CTRL_GETNAME""""\fR" 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'.
.if n .Ip "\f(CW""""PTH_CTRL_DUMPSTATE""""\fR" 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.
.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:
.if n .Ip "\f(CW""""PTH_ATTR_PRIO""""\fR (read-write) [\f(CW""""int""""\fR]" 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.
.if n .Ip "\f(CW""""PTH_ATTR_NAME""""\fR (read-write) [\f(CW""""char *""""\fR]" 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.
.if n .Ip "\f(CW""""PTH_ATTR_JOINABLE""""\fR (read-write> [\f(CW""""int""""\fR]" 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.
.if n .Ip "\f(CW""""PTH_ATTR_CANCEL_STATE""""\fR (read-write) [\f(CW""""unsigned int""""\fR]" 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.
.if n .Ip "\f(CW""""PTH_ATTR_STACK_SIZE""""\fR (read-write) [\f(CW""""unsigned int""""\fR]" 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!
.if n .Ip "\f(CW""""PTH_ATTR_STACK_ADDR""""\fR (read-write) [\f(CW""""char *""""\fR]" 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.
.if n .Ip "\f(CW""""PTH_ATTR_TIME_SPAWN""""\fR (read-only) [\f(CW""""pth_time_t""""\fR]" 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.
.if n .Ip "\f(CW""""PTH_ATTR_TIME_LAST""""\fR (read-only) [\f(CW""""pth_time_t""""\fR]" 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.
.if n .Ip "\f(CW""""PTH_ATTR_TIME_RAN""""\fR (read-only) [\f(CW""""pth_time_t""""\fR]" 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.
.if n .Ip "\f(CW""""PTH_ATTR_START_FUNC""""\fR (read-only) [\f(CW""""void *(*)(void *)""""\fR]" 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.
.if n .Ip "\f(CW""""PTH_ATTR_START_ARG""""\fR (read-only) [\f(CW""""void *""""\fR]" 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.
.if n .Ip "\f(CW""""PTH_ATTR_STATE""""\fR (read-only) [\f(CW""""pth_state_t""""\fR]" 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.
.if n .Ip "\f(CW""""PTH_ATTR_EVENTS""""\fR (read-only) [\f(CW""""pth_event_t""""\fR]" 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.
.if n .Ip "\f(CW""""PTH_ATTR_BOUND""""\fR (read-only) [\f(CW""""int""""\fR]" 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 exists to handle the attribute objects:
.Ip "pth_attr_t \fBpth_attr_of\fR(pth_t \fItid\fR);" 4
.IX Item "pth_attr_t pth_attr_of(pth_t tid);"
This returns a new attribute object \fIbound\fR to thread \fItid\fR.  Any queries on
this object directly fetch attributes from \fItid\fR. And attribute modifications
directly change \fItid\fR. Use such attribute objects to modify existing threads.
.Ip "pth_attr_t \fBpth_attr_new\fR(void);" 4
.IX Item "pth_attr_t pth_attr_new(void);"
This returns a new \fIunbound\fR attribute object. An implicit \fIpth_attr_init()\fR is
done on it. Any queries on this object just fetch stored attributes from it.
And attribute modifications just change the stored attributes.  Use such
attribute objects to pre-configure attributes for to be spawned threads.
.Ip "int \fBpth_attr_init\fR(pth_attr_t \fIattr\fR);" 4
.IX Item "int pth_attr_init(pth_attr_t attr);"
This initializes an attribute object \fIattr\fR to the default values:
\&\f(CW\*(C`PTH_ATTR_PRIO\*(C'\fR := \f(CW\*(C`PTH_PRIO_STD\*(C'\fR, \f(CW\*(C`PTH_ATTR_NAME\*(C'\fR := `\f(CW\*(C`unknown\*(C'\fR',
\&\f(CW\*(C`PTH_ATTR_JOINABLE\*(C'\fR := \f(CW\*(C`TRUE\*(C'\fR, \f(CW\*(C`PTH_ATTR_CANCELSTATE\*(C'\fR :=
\&\f(CW\*(C`PTH_CANCEL_DEFAULT\*(C'\fR, \f(CW\*(C`PTH_ATTR_STACK_SIZE\*(C'\fR := 64*1024 and
\&\f(CW\*(C`PTH_ATTR_STACK_ADDR\*(C'\fR := \f(CW\*(C`NULL\*(C'\fR. All other \f(CW\*(C`PTH_ATTR_*\*(C'\fR attributes are
read-only attributes and don't receive default values in \fIattr\fR, because they
exists only for bounded attribute objects.
.Ip "int \fBpth_attr_set\fR(pth_attr_t \fIattr\fR, int \fIfield\fR, ...);" 4
.IX Item "int pth_attr_set(pth_attr_t attr, int field, ...);"
This sets the attribute field \fIfield\fR in \fIattr\fR to a value
specified as an additional argument on the variable argument
list. The following attribute \fIfields\fR and argument pairs can
be used: 
.Sp
.Vb 6
\& PTH_ATTR_PRIO           int
\& PTH_ATTR_NAME           char *
\& 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 14
\& PTH_ATTR_PRIO           int *
\& PTH_ATTR_NAME           char **
\& 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 form the main \s-1API\s0 of
the \fBPth\fR library.
.Ip "pth_t \fBpth_spawn\fR(pth_attr_t \fIattr\fR, void *(*\fIentry\fR)(void *), void *\fIarg\fR);" 4
.IX Item "pth_t pth_spawn(pth_attr_t attr, void *(*entry)(void *), void *arg);"
This spawns a new thread with the attributes given in \fIattr\fR (or
\&\f(CW\*(C`PTH_ATTR_DEFAULT\*(C'\fR for default attributes \- which means that thread priority,
joinability and cancel state are inherited from the current thread) with the
starting point at routine \fIentry\fR. This entry routine is called as
`pth_exit(\fIentry\fR(\fIarg\fR))' inside the new thread unit, i.e., \fIentry\fR's
return value is fed to an implicit \fIpth_exit\fR\|(3). So the thread usually can exit
by just returning. Nevertheless the thread can also exit explicitly at any
time by calling \fIpth_exit\fR\|(3). But keep in mind that calling the \s-1POSIX\s0 function
\&\fIexit\fR\|(3) still terminates the complete process and not just the current thread.
.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 and invalid or still not
new or ready thread.
.Ip "int \fBpth_nap\fR(pth_time_t \fInaptime\fR);" 4
.IX Item "int pth_nap(pth_time_t naptime);"
This functions suspends the execution of the current thread until \fInaptime\fR
is elapsed. \fInaptime\fR is of type \f(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 after tagging them as occurred. 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 events and the application
can use \fIpth_event_occurred\fR\|(3) to test which events occurred.
.Ip "int \fBpth_cancel\fR(pth_t \fItid\fR);" 4
.IX Item "int pth_cancel(pth_t tid);"
This cancels a thread \fItid\fR. How the cancellation is done depends on the
cancellation state of \fItid\fR which the thread can configure itself. When its
state is \f(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"
The following functions are utility functions.
.Ip "int \fBpth_fdmode\fR(int \fIfd\fR, int \fImode\fR);" 4
.IX Item "int pth_fdmode(int fd, int mode);"
This switches the non-blocking mode flag on file descriptor \fIfd\fR.  The
argument \fImode\fR can be \f(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(CW\*(C`0\*(C'\fR it sets the
new cancellation state. \fIoldstate\fR is created before \fInewstate\fR is set.  A
state is a combination of \f(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
.if n .Ip "\f(CW""""PTH_EVENT_FD""""\fR" 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'.
.if n .Ip "\f(CW""""PTH_EVENT_SELECT""""\fR" 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.
.if n .Ip "\f(CW""""PTH_EVENT_SIGS""""\fR" 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'.
.if n .Ip "\f(CW""""PTH_EVENT_TIME""""\fR" 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'.
.if n .Ip "\f(CW""""PTH_EVENT_MSG""""\fR" 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'.
.if n .Ip "\f(CW""""PTH_EVENT_TID""""\fR" 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'.
.if n .Ip "\f(CW""""PTH_EVENT_FUNC""""\fR" 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'.
.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 "int \fBpth_event_occurred\fR(pth_event_t \fIev\fR);" 4
.IX Item "int pth_event_occurred(pth_event_t ev);"
This checks whether the event \fIev\fR occurred. This is a fast operation because
only a tag on \fIev\fR is checked which was either set or still not set by the
scheduler. In other words: This doesn't check the event itself, it just checks
the last knowledge of the scheduler.
.Ip "int \fBpth_event_free\fR(pth_event_t \fIev\fR, int \fImode\fR);" 4
.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 with name \fIname\fR. The \fIname\fR
can be used by other threads via \fIpth_msgport_find\fR\|(3) to find the message port
in case they do not know directly the pointer to the message port.
.Ip "void \fBpth_msgport_destroy\fR(pth_msgport_t \fImp\fR);" 4
.IX Item "void pth_msgport_destroy(pth_msgport_t mp);"
This destroys a message port \fImp\fR. Before all pending messages on it are
replied to their origin message port.
.Ip "pth_msgport_t \fBpth_msgport_find\fR(const char *\fIname\fR);" 4
.IX Item "pth_msgport_t pth_msgport_find(const char *name);"
This finds a message port in the system by \fIname\fR and returns the pointer to
it.
.Ip "int \fBpth_msgport_pending\fR(pth_msgport_t \fImp\fR);" 4
.IX Item "int pth_msgport_pending(pth_msgport_t mp);"
This returns the number of pending messages on message port \fImp\fR.
.Ip "int \fBpth_msgport_put\fR(pth_msgport_t \fImp\fR, pth_message_t *\fIm\fR);" 4
.IX Item "int pth_msgport_put(pth_msgport_t mp, pth_message_t *m);"
This puts (or sends) a message \fIm\fR to message port \fImp\fR.
.Ip "pth_message_t *\fBpth_msgport_get\fR(pth_msgport_t \fImp\fR);" 4
.IX Item "pth_message_t *pth_msgport_get(pth_msgport_t mp);"
This gets (or receives) the top message from message port \fImp\fR.  Incoming
messages are always kept in a queue, so there can be more pending messages, of
course.
.Ip "int \fBpth_msgport_reply\fR(pth_message_t *\fIm\fR);" 4
.IX Item "int pth_msgport_reply(pth_message_t *m);"
This replies a message \fIm\fR to the message port of the sender.
.Sh "Thread Cleanups"
.IX Subsection "Thread Cleanups"
The following functions provide per-thread cleanup functions.
.Ip "int \fBpth_cleanup_push\fR(void (*\fIhandler\fR)(void *), void *\fIarg\fR);" 4
.IX Item "int pth_cleanup_push(void (*handler)(void *), void *arg);"
This pushes the routine \fIhandler\fR onto the stack of cleanup routines for the
current thread.  These routines are called in \s-1LIFO\s0 order when the thread
terminates.
.Ip "int \fBpth_cleanup_pop\fR(int \fIexecute\fR);" 4
.IX Item "int pth_cleanup_pop(int execute);"
This pops the top-most routine from the stack of cleanup routines for the
current thread. When \fIexecute\fR is \f(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 "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_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 awakened 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 awakened 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 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 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 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 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 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_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 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 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 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 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 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 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
.Vb 1
\& #define PORT 12345
.Ve
.Vb 6
\& /* the socket connection handler thread */
\& static void *handler(void *_arg)
\& {
\&     int fd = (int)_arg;
\&     time_t now;
\&     char *ct;
.Ve
.Vb 6
\&     now = time(NULL);
\&     ct = ctime(&now);
\&     pth_write(fd, ct, strlen(ct));
\&     close(fd);
\&     return NULL;
\& }
.Ve
.Vb 6
\& /* the stderr time ticker thread */
\& static void *ticker(void *_arg)
\& {
\&     time_t now;
\&     char *ct;
\&     float load;
.Ve
.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
.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
.Vb 2
\&     pth_init();
\&     signal(SIGPIPE, SIG_IGN);
.Ve
.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
.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
.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
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 unflexible. 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 an 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
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.in\*(C'\fR, a (minimal) \fBautoconf\fR script specification:
.PP
.Vb 4
\& $ vi configure.in
\& | AC_INIT(Makefile.in)
\& | AC_CHECK_PTH(1.3.0)
\& | AC_OUTPUT(Makefile)
.Ve
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.in\*(C'\fR
file:
.PP
.Vb 2
\& $ aclocal --acdir=`pth-config --acdir`
\& $ autoconf
.Ve
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.in
\& -rw-r--r--  1 rse  users   4227 Nov  3 11:11 foo.c
.Ve
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\*(C`$PATH\*(C'\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
If \fBPth\fR is installed in non-standard locations or \f(CW\*(C`pth\-config\*(C'\fR
is not in \f(CW\*(C`$PATH\*(C'\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
Then we create a slightly different \fBautoconf\fR script \f(CW\*(C`configure.in\*(C'\fR:
.PP
.Vb 6
\& $ vi configure.in
\& | 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
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.in\*(C'\fR file.
.PP
.Vb 2
\& $ aclocal --acdir=`pth-config --acdir`
\& $ autoconf
.Ve
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
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
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.in
\& -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
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
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),
\&\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), \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 inlined 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
@


1.233
log
@switch to version 1.5 branding
@
text
@@


1.232
log
@update version
@
text
@d2 1
a2 1
.\" Sun Jan 27 13:33:11 2002
d141 1
a141 1
.TH pth 3 "27-Jan-2002" "GNU Pth 1.4.1" "GNU Portable Threads"
d147 1
a147 1
\&\s-1GNU\s0 Pth \s-11.4.1 (27-Jan-2002)\s0
@


1.231
log
@*** empty log message ***
@
text
@d2 1
a2 1
.\" Thu Jul 12 09:19:00 2001
d141 1
a141 1
.TH pth 3 "24-Mar-2001" "GNU Pth 1.4.0" "GNU Portable Threads"
d147 1
a147 1
\&\s-1GNU\s0 Pth \s-11.4.0 (24-Mar-2001)\s0
d759 4
a762 3
The thread detachment type, \f(CW\*(C`TRUE\*(C'\fR indicates a joinable thread, \f(CW\*(C`FALSE\*(C'\fR
indicates a detached thread.  When a the is detached after termination it is
immediately kicked out of the system instead of inserted into the dead queue.
d1010 8
a1017 7
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 was \fInot\fR spawned with \f(CW\*(C`PTH_FLAG_NOJOIN\*(C'\fR. A thread can only be
joined once, i.e., after the \fIpth_join\fR\|(3) call the thread \fItid\fR is removed
from the system.
d1020 7
a1026 6
This terminates the current thread. Whether it's immediately removed from the
system or inserted into the dead queue of the scheduler depends on its join
type which was specified at spawning time. When it was spawned with
\&\f(CW\*(C`PTH_FLAG_NOJOIN\*(C'\fR it's immediately removed and \fIvalue\fR is ignored.
Else the thread is inserted into the dead queue and \fIvalue\fR remembered
for a \fIpth_join\fR\|(3) call by another thread.
d1104 1
a1104 1
\&\f(CW\*(C`PTH_UNTIL_FD_WRITEABLE\*(C'\fR or \f(CW\*(C`PTH_UNTIL_FD_EXECPTION\*(C'\fR have to be OR-ed into
d1827 2
a1828 3
\&\f(CW\*(C`distclean\*(C'\fR target which cleanups this, too. Second, we write
a (minimalistic) \fBautoconf\fR script specification in a file
\&\f(CW\*(C`configure.in\*(C'\fR:
d1886 2
a1887 2
easier distribution and installation.  That is, we don't want that the
end-user first has to install \fBPth\fR just to allow our \f(CW\*(C`foo\*(C'\fR package to
@


1.230
log
@*** empty log message ***
@
text
@d1 2
a2 2
.\" Automatically generated by Pod::Man version 1.02
.\" Sat Mar 24 17:29:24 2001
d49 2
a50 2
.    ds C` `
.    ds C' '
d66 1
a66 1
.    .
d678 2
a679 1
.Ip "\f(CW\*(C`PTH_CTRL_GETTHREADS\*(C'\fR" 4
d697 2
a698 1
.Ip "\f(CW\*(C`PTH_CTRL_GETAVLOAD\*(C'\fR" 4
d708 2
a709 1
.Ip "\f(CW\*(C`PTH_CTRL_GETPRIO\*(C'\fR" 4
d714 2
a715 1
.Ip "\f(CW\*(C`PTH_CTRL_GETNAME\*(C'\fR" 4
d720 2
a721 1
.Ip "\f(CW\*(C`PTH_CTRL_DUMPSTATE\*(C'\fR" 4
d746 2
a747 1
.Ip "\f(CW\*(C`PTH_ATTR_PRIO\*(C'\fR (read-write) [\f(CW\*(C`int\*(C'\fR]" 4
d751 2
a752 1
.Ip "\f(CW\*(C`PTH_ATTR_NAME\*(C'\fR (read-write) [\f(CW\*(C`char *\*(C'\fR]" 4
d756 2
a757 1
.Ip "\f(CW\*(C`PTH_ATTR_JOINABLE\*(C'\fR (read-write> [\f(CW\*(C`int\*(C'\fR]" 4
d762 2
a763 1
.Ip "\f(CW\*(C`PTH_ATTR_CANCEL_STATE\*(C'\fR (read-write) [\f(CW\*(C`unsigned int\*(C'\fR]" 4
d768 2
a769 1
.Ip "\f(CW\*(C`PTH_ATTR_STACK_SIZE\*(C'\fR (read-write) [\f(CW\*(C`unsigned int\*(C'\fR]" 4
d772 2
a773 1
.Ip "\f(CW\*(C`PTH_ATTR_STACK_ADDR\*(C'\fR (read-write) [\f(CW\*(C`char *\*(C'\fR]" 4
d777 2
a778 1
.Ip "\f(CW\*(C`PTH_ATTR_TIME_SPAWN\*(C'\fR (read-only) [\f(CW\*(C`pth_time_t\*(C'\fR]" 4
d782 2
a783 1
.Ip "\f(CW\*(C`PTH_ATTR_TIME_LAST\*(C'\fR (read-only) [\f(CW\*(C`pth_time_t\*(C'\fR]" 4
d787 2
a788 1
.Ip "\f(CW\*(C`PTH_ATTR_TIME_RAN\*(C'\fR (read-only) [\f(CW\*(C`pth_time_t\*(C'\fR]" 4
d792 2
a793 1
.Ip "\f(CW\*(C`PTH_ATTR_START_FUNC\*(C'\fR (read-only) [\f(CW\*(C`void *(*)(void *)\*(C'\fR]" 4
d797 2
a798 1
.Ip "\f(CW\*(C`PTH_ATTR_START_ARG\*(C'\fR (read-only) [\f(CW\*(C`void *\*(C'\fR]" 4
d802 2
a803 1
.Ip "\f(CW\*(C`PTH_ATTR_STATE\*(C'\fR (read-only) [\f(CW\*(C`pth_state_t\*(C'\fR]" 4
d808 2
a809 1
.Ip "\f(CW\*(C`PTH_ATTR_EVENTS\*(C'\fR (read-only) [\f(CW\*(C`pth_event_t\*(C'\fR]" 4
d813 2
a814 1
.Ip "\f(CW\*(C`PTH_ATTR_BOUND\*(C'\fR (read-only) [\f(CW\*(C`int\*(C'\fR]" 4
d1097 2
a1098 1
.Ip "\f(CW\*(C`PTH_EVENT_FD\*(C'\fR" 4
d1105 2
a1106 1
.Ip "\f(CW\*(C`PTH_EVENT_SELECT\*(C'\fR" 4
d1122 2
a1123 1
.Ip "\f(CW\*(C`PTH_EVENT_SIGS\*(C'\fR" 4
d1134 2
a1135 1
.Ip "\f(CW\*(C`PTH_EVENT_TIME\*(C'\fR" 4
d1144 2
a1145 1
.Ip "\f(CW\*(C`PTH_EVENT_MSG\*(C'\fR" 4
d1150 2
a1151 1
.Ip "\f(CW\*(C`PTH_EVENT_TID\*(C'\fR" 4
d1158 2
a1159 1
.Ip "\f(CW\*(C`PTH_EVENT_FUNC\*(C'\fR" 4
d1389 2
a1390 2
.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); "
d2118 1
a2118 1
\&\f(CW\*(C`pth_debug.h\*(C'\fR for details].
@


1.229
log
@*** empty log message ***
@
text
@d2 1
a2 1
.\" Sat Mar 24 15:54:47 2001
d141 1
a141 1
.TH pth 3 "24-Mar-2001" "GNU Pth 1.4a4" "GNU Portable Threads"
d147 1
a147 1
\&\s-1GNU\s0 Pth \s-11.4a4 (24-Mar-2001)\s0
@


1.228
log
@*** empty log message ***
@
text
@d2 1
a2 1
.\" Sat Mar 24 15:32:34 2001
d141 1
a141 1
.TH pth 3 "30-Sep-2000" "GNU Pth 1.4a4" "GNU Portable Threads"
d147 1
a147 1
\&\s-1GNU\s0 Pth \s-11.4a4 (30-Sep-2000)\s0
@


1.227
log
@*** empty log message ***
@
text
@d2 1
a2 1
.\" Sat Mar 24 14:44:57 2001
@


1.226
log
@*** empty log message ***
@
text
@d2 1
a2 1
.\" Sun Feb 25 18:13:54 2001
d2033 1
a2033 1
\&\fIpth_read\fR\|(3), etc.  Currently the following functions are mapped: \fIfork\fR\|(2),
d2035 2
a2036 1
\&\fIconnect\fR\|(2), \fIaccept\fR\|(2), \fIread\fR\|(2), \fIwrite\fR\|(2).
@


1.225
log
@*** empty log message ***
@
text
@d2 1
a2 1
.\" Sun Oct  1 14:44:33 2000
d256 1
d1505 8
d2034 2
a2035 2
\&\fIsleep\fR\|(3), \fIsigwait\fR\|(3), \fIwaitpid\fR\|(2), \fIselect\fR\|(2), \fIpoll\fR\|(2), \fIconnect\fR\|(2),
\&\fIaccept\fR\|(2), \fIread\fR\|(2), \fIwrite\fR\|(2).
d2048 3
a2050 3
replacement functions (\fIpth_read\fR\|(3)).  Currently the following functions are
mapped: \fIfork\fR\|(2), \fIsleep\fR\|(3), \fIwaitpid\fR\|(2), \fIselect\fR\|(2), \fIpoll\fR\|(2), \fIconnect\fR\|(2),
\&\fIaccept\fR\|(2), \fIread\fR\|(2), \fIwrite\fR\|(2).
@


1.224
log
@*** empty log message ***
@
text
@d2 1
a2 1
.\" Sat Sep 30 09:59:07 2000
d141 1
a141 1
.TH pth 3 "18-Aug-2000" "GNU Pth 1.4a3" "GNU Portable Threads"
d147 1
a147 1
\&\s-1GNU\s0 Pth \s-11.4a3 (18-Aug-2000)\s0
@


1.223
log
@*** empty log message ***
@
text
@d1 6
a6 6
.rn '' }`
''' $RCSfile$$Revision$$Date$
'''
''' $Log$
'''
.de Sh
d14 1
a14 1
.de Sp
d18 1
a18 1
.de Ip
d24 1
a24 1
.de Vb
d29 1
a29 1
.de Ve
d34 6
a39 6
'''
'''
'''     Set up \*(-- to give an unbreakable dash;
'''     string Tr holds user defined translation string.
'''     Bell System Logo is used as a dummy character.
'''
d41 1
d43 8
a50 20
.ds -- \(*W-
.ds PI pi
.if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
.ds L" ""
.ds R" ""
'''   \*(M", \*(S", \*(N" and \*(T" are the equivalent of
'''   \*(L" and \*(R", except that they are used on ".xx" lines,
'''   such as .IP and .SH, which do another additional levels of
'''   double-quote interpretation
.ds M" """
.ds S" """
.ds N" """""
.ds T" """""
.ds L' '
.ds R' '
.ds M' '
.ds S' '
.ds N' '
.ds T' '
d53 4
a56 15
.ds -- \(em\|
.tr \*(Tr
.ds L" ``
.ds R" ''
.ds M" ``
.ds S" ''
.ds N" ``
.ds T" ''
.ds L' `
.ds R' '
.ds M' `
.ds S' '
.ds N' `
.ds T' '
.ds PI \(*p
d58 11
a68 15
.\"	If the F register is turned on, we'll generate
.\"	index entries out stderr for the following things:
.\"		TH	Title 
.\"		SH	Header
.\"		Sh	Subsection 
.\"		Ip	Item
.\"		X<>	Xref  (embedded
.\"	Of course, you have to process the output yourself
.\"	in some meaninful fashion.
.if \nF \{
.de IX
.tm Index:\\$1\t\\n%\t"\\$2"
..
.nr % 0
.rr F
d70 4
a73 3
.TH pth 3 "18-Aug-2000" "GNU Pth 1.4a3" "GNU Portable Threads"
.UC
.if n .hy 0
d75 3
a77 12
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.de CQ          \" put $1 in typewriter font
.ft CW
'if n "\c
'if t \\&\\$1\c
'if n \\&\\$1\c
'if n \&"
\\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
'.ft R
..
.\" @@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
.	\" AM - accent mark definitions
d79 1
a79 1
.	\" fudge factors for nroff and troff
d81 5
a85 5
.	ds #H 0
.	ds #V .8m
.	ds #F .3m
.	ds #[ \f1
.	ds #] \fP
d88 5
a92 5
.	ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.	ds #V .6m
.	ds #F 0
.	ds #[ \&
.	ds #] \&
d94 1
a94 1
.	\" simple accents for nroff and troff
d96 6
a101 9
.	ds ' \&
.	ds ` \&
.	ds ^ \&
.	ds , \&
.	ds ~ ~
.	ds ? ?
.	ds ! !
.	ds /
.	ds q
d104 6
a109 9
.	ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.	ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.	ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.	ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.	ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.	ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
.	ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
.	ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.	ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
d111 1
a111 1
.	\" troff and (daisy-wheel) nroff accents
a113 4
.ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
.ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
.ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
.ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
d121 1
a121 3
.ds oe o\h'-(\w'o'u*4/10)'e
.ds Oe O\h'-(\w'O'u*4/10)'E
.	\" corrections for vroff
d124 1
a124 1
.	\" for low resolution devices (crt and lpr)
d127 9
a135 15
.	ds : e
.	ds 8 ss
.	ds v \h'-1'\o'\(aa\(ga'
.	ds _ \h'-1'^
.	ds . \h'-1'.
.	ds 3 3
.	ds o a
.	ds d- d\h'-1'\(ga
.	ds D- D\h'-1'\(hy
.	ds th \o'bp'
.	ds Th \o'LP'
.	ds ae ae
.	ds Ae AE
.	ds oe oe
.	ds Oe OE
d138 5
d144 1
a144 1
\fBpth\fR \- GNU Portable Threads
d146 2
a147 1
GNU Pth 1.4a3 (18-Aug-2000)
d149 1
d151 1
d157 1
d165 1
d180 1
d186 1
d190 1
d200 1
d206 1
d215 1
d219 1
d224 1
d237 1
d252 1
d273 1
a273 1
.PP
d281 1
a281 1
\fBPth\fR is a very portable POSIX/ANSI\-C based library for Unix platforms which
d285 1
a285 1
its own individual program counter, run-time stack, signal mask and \f(CWerrno\fR
d297 1
a297 1
\fBPth\fR also provides an optional emulation API for POSIX.1c threads
d302 1
d306 1
a306 1
machines, we use `multitasking\*(R' -- that is, we have the application
d341 1
d346 1
a346 1
\fBPth\fR.
d348 1
d359 1
d372 1
a372 1
\fIsetjmp\fR\|(3)/\fIlongjmp\fR\|(3)) than kernel based threads. On the other hand,
d379 1
d386 1
a386 1
user-space threads), like \f(CWSIGALRM\fR or \f(CWSIGVTALRM\fR. In non-preemptive
d392 1
d397 1
a397 1
\fIhigh concurrency\fR in the context of preemptive thread scheduling
d401 1
d409 1
d442 1
d446 2
a447 1
\fBMatrix-based explicit dispatching between small units of execution:\fR
d475 2
a476 1
\fBContext-based implicit scheduling between threads of execution:\fR
d500 1
a500 1
Finally, there is no really portable \s-1POSIX/ANSI\s0\-C based way to implement
d512 1
d523 2
a524 1
\fBPth provides maximum portability, but \s-1NOT\s0 the fanciest features\fR.
d526 1
a526 1
This is, because it uses a nifty and portable \s-1POSIX/ANSI\s0\-C approach for
d529 1
a529 1
doesn't require unportable facilities like \f(CWSIGVTALRM\fR). On the other
d534 2
a535 1
\fBPth increases the responsiveness and concurrency of an event-driven
d542 1
a542 1
concept of `coroutines\*(R'. On the other hand, event driven applications
d544 1
a544 1
\s-1CPU\s0 bursts and lots of events to wait on, and this way run faster under
d550 2
a551 1
\fBPth requires thread-safe functions, but \s-1NOT\s0 reentrant functions\fR.
d561 2
a562 1
\fBPth doesn't require any kernel support, but can \s-1NOT\s0
d573 1
d597 1
a597 1
priority of all remaining threads by 1, to prevent them from `starving\*(R'.
d600 1
a600 1
\fB\s-1RUNNING\s0\fR thread (there is always just one \fB\s-1RUNNING\s0\fR thread, of
d610 1
a610 1
\fB\s-1WAITING\s0\fR queue is checked for pending events. If one or more events
d624 1
a624 1
\fB\s-1DEAD\s0\fR queue. There it remains until another thread joins it.
d636 2
a637 1
In the following the \fBPth\fR \fIApplication Programming Interface\fR (API)
d639 3
a641 3
now easy to understand how to program threads with this API. In good
Unix tradition, \fBPth\fR functions use special return values (\f(CWNULL\fR
in pointer context, \f(CWFALSE\fR in boolean context and \f(CW-1\fR in integer
d643 1
a643 1
\f(CWerrno\fR system variable to pass more details about the error to the
d646 1
d650 1
d655 2
a656 2
unit of the current process into a thread (the `main\*(R' thread). It
returns \f(CWTRUE\fR on success and \f(CWFALSE\fR on error.
d658 1
d665 1
a665 1
`\f(CWpth_exit(0);\fR\*(R' in the main thread (which waits for all other threads to
d667 1
a667 1
`\f(CWpth_kill(); exit(0)\fR\*(R' (which immediately kills the threading system and
d669 2
a670 2
code of \f(CWFALSE\fR if it is called not from within the main thread. Else
kills the threading system and returns \f(CWTRUE\fR.
d672 1
d674 1
a674 1
argument \fIquery\fR is a bitmask formed out of one or more \f(CWPTH_CTRL_\fR\fI\s-1XXXX\s0\fR
d676 3
a678 1
.Ip "\f(CWPTH_CTRL_GETTHREADS\fR" 8
d681 2
a682 2
particular state, i.e., the \f(CWPTH_CTRL_GETTHREADS\fR query is equal to the
\s-1OR\s0\-combination of all the following specialized queries:
d684 1
a684 1
\f(CWPTH_CTRL_GETTHREADS_NEW\fR for the number of threads in the
d686 1
a686 1
scheduled once), \f(CWPTH_CTRL_GETTHREADS_READY\fR for the number of
d688 2
a689 2
\f(CWPTH_CTRL_GETTHREADS_RUNNING\fR for the number of running threads
(always just one thread!), \f(CWPTH_CTRL_GETTHREADS_WAITING\fR for
d691 1
a691 1
events), \f(CWPTH_CTRL_GETTHREADS_SUSPENDED\fR for the number of
d693 1
a693 1
\f(CWPTH_CTRL_GETTHREADS_DEAD\fR for the number of threads in the new queue
d695 3
a697 2
.Ip "\f(CWPTH_CTRL_GETAVLOAD\fR" 8
This requires a second argument of type `\f(CWfloat *\fR\*(R' (pointer to a floating
d705 8
a712 6
.Ip "\f(CWPTH_CTRL_GETPRIO\fR" 8
This requires a second argument of type `\f(CWpth_t\fR\*(R' which identifies a
thread.  It returns the priority (ranging from \f(CWPTH_PRIO_MIN\fR to
\f(CWPTH_PRIO_MAX\fR) of the given thread.
.Ip "\f(CWPTH_CTRL_GETNAME\fR" 8
This requires a second argument of type `\f(CWpth_t\fR\*(R' which identifies a
d714 4
a717 3
\fIpth_ctrl\fR\|(3) should be casted to a `\f(CWchar *\fR\*(R'.
.Ip "\f(CWPTH_CTRL_DUMPSTATE\fR" 8
This requires a second argument of type `\f(CWFILE *\fR\*(R' to which a summary
d720 2
d723 2
a724 1
The function returns \f(CW-1\fR on error.
d726 2
a727 1
This function returns a hex-value `0x\fIV\fR\fI\s-1RR\s0\fR\fIT\fR\fI\s-1LL\s0\fR\*(R' which describes the
d729 1
a729 1
\fI\s-1LL\s0\fR the level and \fIT\fR the type of the level (alphalevel=0, betalevel=1,
d733 1
a733 1
\f(CWPTH_VERSION\fR.
d735 1
d740 6
a745 4
.Ip "\f(CWPTH_ATTR_PRIO\fR (read-write) [\f(CWint\fR]" 4
Thread Priority between \f(CWPTH_PRIO_MIN\fR and \f(CWPTH_PRIO_MAX\fR.
The default is \f(CWPTH_PRIO_STD\fR.
.Ip "\f(CWPTH_ATTR_NAME\fR (read-write) [\f(CWchar *\fR]" 4
d748 3
a750 2
.Ip "\f(CWPTH_ATTR_JOINABLE\fR (read-write> [\f(CWint\fR]" 4
The thread detachment type, \f(CWTRUE\fR indicates a joinable thread, \f(CWFALSE\fR
d753 7
a759 5
.Ip "\f(CWPTH_ATTR_CANCEL_STATE\fR (read-write) [\f(CWunsigned int\fR]" 4
The thread cancellation state, i.e., a combination of \f(CWPTH_CANCEL_ENABLE\fR or
\f(CWPTH_CANCEL_DISABLE\fR and \f(CWPTH_CANCEL_DEFERRED\fR or
\f(CWPTH_CANCEL_ASYNCHRONOUS\fR.
.Ip "\f(CWPTH_ATTR_STACK_SIZE\fR (read-write) [\f(CWunsigned int\fR]" 4
d761 2
a762 1
.Ip "\f(CWPTH_ATTR_STACK_ADDR\fR (read-write) [\f(CWchar *\fR]" 4
d765 2
a766 1
.Ip "\f(CWPTH_ATTR_TIME_SPAWN\fR (read-only) [\f(CWpth_time_t\fR]" 4
d769 2
a770 1
.Ip "\f(CWPTH_ATTR_TIME_LAST\fR (read-only) [\f(CWpth_time_t\fR]" 4
d773 2
a774 1
.Ip "\f(CWPTH_ATTR_TIME_RAN\fR (read-only) [\f(CWpth_time_t\fR]" 4
d777 2
a778 1
.Ip "\f(CWPTH_ATTR_START_FUNC\fR (read-only) [\f(CWvoid *(*)(void *)\fR]" 4
d781 2
a782 1
.Ip "\f(CWPTH_ATTR_START_ARG\fR (read-only) [\f(CWvoid *\fR]" 4
d785 4
a788 3
.Ip "\f(CWPTH_ATTR_STATE\fR (read-only) [\f(CWpth_state_t\fR]" 4
The scheduling state of the thread, i.e., either \f(CWPTH_STATE_NEW\fR,
\f(CWPTH_STATE_READY\fR, \f(CWPTH_STATE_WAITING\fR, or \f(CWPTH_STATE_DEAD\fR
d790 2
a791 1
.Ip "\f(CWPTH_ATTR_EVENTS\fR (read-only) [\f(CWpth_event_t\fR]" 4
d794 3
a796 2
.Ip "\f(CWPTH_ATTR_BOUND\fR (read-only) [\f(CWint\fR]" 4
Whether the attribute object is bound (\f(CWTRUE\fR) to a thread or not (\f(CWFALSE\fR).
d800 1
d805 1
d811 1
d813 4
a816 4
\f(CWPTH_ATTR_PRIO\fR := \f(CWPTH_PRIO_STD\fR, \f(CWPTH_ATTR_NAME\fR := `\f(CWunknown\fR\*(R',
\f(CWPTH_ATTR_JOINABLE\fR := \f(CWTRUE\fR, \f(CWPTH_ATTR_CANCELSTATE\fR :=
\f(CWPTH_CANCEL_DEFAULT\fR, \f(CWPTH_ATTR_STACK_SIZE\fR := 64*1024 and
\f(CWPTH_ATTR_STACK_ADDR\fR := \f(CWNULL\fR. All other \f(CWPTH_ATTR_*\fR attributes are
d820 1
d835 1
d858 1
d862 1
d866 1
d868 1
a868 1
\f(CWPTH_ATTR_DEFAULT\fR for default attributes \- which means that thread priority,
d871 1
a871 1
`\fIpth_exit\fR\|(\fIentry\fR(\fIarg\fR))\*(R' inside the new thread unit, i.e., \fIentry\fR's
d875 1
a875 1
\fIexit\fR\|(3) still terminates the complete process and not just the current thread.
d880 1
a880 1
\f(CWNULL\fR on error.
d882 1
d884 5
a888 5
\f(CWpth_once_t\fR to make sure a constructor function \fIfunc\fR is called only once
as `\fIfunc\fR(\fIarg\fR)\*(R' in the system. In other words: Only the first call to
\fIpth_once\fR\|(3) by any thread in the system succeeds. The variable referenced via
\fIctrlvar\fR should be declared as `\f(CWpth_once_t\fR \fIvariable-name\fR =
\f(CWPTH_ONCE_INIT\fR;\*(R' before calling this function.
d890 1
d894 1
a894 1
type \f(CWpth_t\fR.
d896 1
d898 1
a898 1
\fIpth_resume\fR\|(3). For this, the thread is moved to the \fB\s-1SUSPENDED\s0\fR queue
d901 1
a901 1
The function returns \f(CWTRUE\fR on success and \f(CWFALSE\fR on errors.
d903 1
d906 1
a906 1
\fB\s-1NEW\s0\fR, \fB\s-1READY\s0\fR or \fB\s-1WAITING\s0\fR queue (dependent on what its state was
d909 1
a909 1
function returns \f(CWTRUE\fR on success and \f(CWFALSE\fR on errors.
d911 1
d918 1
a918 1
performed, i.e., `\f(CWpth_raise(tid, 0)\fR\*(R' returns \f(CWTRUE\fR when thread \fItid\fR
d921 1
d932 1
a932 1
Usually one specifies \fItid\fR as \f(CWNULL\fR to indicate to the scheduler that it
d937 1
a937 1
particular cooperating thread. If \fItid\fR is not \f(CWNULL\fR and points to a \fInew\fR
d940 1
a940 1
is, not in \f(CWPTH_STATE_NEW\fR or \f(CWPTH_STATE_READY\fR) an error is reported.
d942 2
a943 2
The function usually returns \f(CWTRUE\fR for success and only \f(CWFALSE\fR (with
\f(CWerrno\fR set to \f(CWEINVAL\fR) if \fItid\fR specified and invalid or still not
d946 1
d948 1
a948 1
is elapsed. \fInaptime\fR is of type \f(CWpth_time_t\fR and this way has theoretically
d958 1
d968 1
d971 4
a974 4
state is \f(CWPTH_CANCEL_DISABLE\fR a cancellation request is just made pending.
When it is \f(CWPTH_CANCEL_ENABLE\fR it depends on the cancellation type what is
performed. When its \f(CWPTH_CANCEL_DEFERRED\fR again the cancellation request is
just made pending. But when its \f(CWPTH_CANCEL_ASYNCHRONOUS\fR the thread is
d977 1
a977 1
`\f(CWpth_exit(PTH_CANCELED)\fR\*(R' at one of his cancellation points.  In \fBPth\fR
d981 1
d983 1
a983 1
waits to be joined it just joins it (via `\f(CWpth_join(\fR\fItid\fR\f(CW, NULL)\fR') and
d986 1
a986 1
`\f(CWpth_cancel(\fR\fItid\fR\f(CW)\fR\*(R'.
d988 1
d992 2
a993 2
\fIvalue\fR and not \f(CWNULL\fR) and returns to the caller.  A thread can be joined
only when it was \fInot\fR spawned with \f(CWPTH_FLAG_NOJOIN\fR. A thread can only be
d997 1
d1001 1
a1001 1
\f(CWPTH_FLAG_NOJOIN\fR it's immediately removed and \fIvalue\fR is ignored.
d1005 1
d1008 1
d1010 5
a1014 5
argument \fImode\fR can be \f(CWPTH_FDMODE_BLOCK\fR for switching \fIfd\fR into blocking
I/O mode, \f(CWPTH_FDMODE_NONBLOCK\fR for switching \fIfd\fR into non-blocking I/O
mode or \f(CWPTH_FDMODE_POLL\fR for just polling the current mode. The current mode
is returned (either \f(CWPTH_FDMODE_BLOCK\fR or \f(CWPTH_FDMODE_NONBLOCK\fR) or
\f(CWPTH_FDMODE_ERROR\fR on error. Keep in mind that since \fBPth\fR 1.1 there is no
d1020 2
a1021 1
This is a constructor for a \f(CWpth_time_t\fR structure which is a convenient
d1025 2
a1026 1
This is a constructor for a \f(CWpth_time_t\fR structure which is a convenient
d1029 1
a1029 1
\fIusec\fR to the current time.
d1031 1
d1033 2
a1034 2
was built with \fBSfio\fR support (\f(CW--with-sfio\fR option) and \f(CWPTH_EXT_SFIO\fR is
then defined by \f(CWpth.h\fR. It is useful for applications which want to use the
d1036 2
a1037 2
function can be used to get an \fBSfio\fR discipline structure (\f(CWSfdisc_t\fR)
which can be pushed onto \fBSfio\fR streams (\f(CWSfio_t\fR) in order to let this
d1040 1
a1040 1
instead of the whole process. The application has to \fIfree\fR\|(3) the \f(CWSfdisc_t\fR
d1044 2
a1045 1
\fBPth\fR supports \s-1POSIX\s0 style thread cancellation via \fIpth_cancel\fR\|(3) and the
d1048 1
d1050 2
a1051 2
is not \f(CWNULL\fR the function stores the old cancellation state under the
variable pointed to by \fIoldstate\fR. When \fInewstate\fR is not \f(CW0\fR it sets the
d1053 3
a1055 3
state is a combination of \f(CWPTH_CANCEL_ENABLE\fR or \f(CWPTH_CANCEL_DISABLE\fR and
\f(CWPTH_CANCEL_DEFERRED\fR or \f(CWPTH_CANCEL_ASYNCHRONOUS\fR.
\f(CWPTH_CANCEL_ENABLE|PTH_CANCEL_DEFERRED\fR (or \f(CWPTH_CANCEL_DEFAULT\fR) is the
d1057 2
a1058 2
Use \f(CWPTH_CANCEL_DISABLE\fR to complete disable cancellation for a thread and
\f(CWPTH_CANCEL_ASYNCHRONOUS\fR for allowing asynchronous cancellations, i.e.,
d1061 1
d1063 1
a1063 1
state is \f(CWPTH_CANCEL_DISABLE\fR or no cancellation request is pending, this has
d1065 1
a1065 1
`\f(CWpth_exit(PTH_CANCELED)\fR\*(R'.
d1067 2
a1068 1
\fBPth\fR has a very flexible event facility which is linked into the scheduler
d1072 1
d1076 6
a1081 4
.Ip "\f(CWPTH_EVENT_FD\fR" 8
This is a file descriptor event. One or more of \f(CWPTH_UNTIL_FD_READABLE\fR,
\f(CWPTH_UNTIL_FD_WRITEABLE\fR or \f(CWPTH_UNTIL_FD_EXECPTION\fR have to be \s-1OR\s0\-ed into
\fIspec\fR to specify on which state of the file descriptor you want to wait.  The
d1083 3
a1085 2
`\f(CWpth_event(PTH_EVENT_FD|PTH_UNTIL_FD_READABLE, fd)\fR\*(R'.
.Ip "\f(CWPTH_EVENT_SELECT\fR" 8
d1093 2
a1094 2
\fIselect\fR\|(2) function arguments except that there is no timeout argument (because
timeouts already can be handled via \f(CWPTH_EVENT_TIME\fR events).
d1096 6
a1101 5
Example: `\f(CWpth_event(PTH_EVENT_SELECT, &rc, nfd, rfds, wfds, efds)\fR\*(R' where
\f(CWrc\fR has to be of type `\f(CWint *\fR\*(R', \f(CWnfd\fR has to be of type `\f(CWint\fR\*(R' and
\f(CWrfds\fR, \f(CWwfds\fR and \f(CWefds\fR have to be of type `\f(CWfd_set *\fR\*(R' (see
\fIselect\fR\|(2)). The number of occurred file descriptors are stored in \f(CWrc\fR.
.Ip "\f(CWPTH_EVENT_SIGS\fR" 8
d1103 2
a1104 2
to a signal set (type `\f(CWsigset_t *\fR') and a pointer to a signal number
variable (type `\f(CWint *\fR').  This event waits until one of the signals in
d1109 4
a1112 3
your notice. Example: `\f(CWsigemptyset(&set); sigaddset(&set, SIGINT);
pth_event(PTH_EVENT_SIG, &set, &sig);\fR\*(R'.
.Ip "\f(CWPTH_EVENT_TIME\fR" 8
d1114 1
a1114 1
\f(CWpth_time_t\fR (usually on-the-fly generated via \fIpth_time\fR\|(3)). This events
d1119 3
a1121 2
`\f(CWpth_event(PTH_EVENT_TIME, pth_timeout(2,0))\fR\*(R'.
.Ip "\f(CWPTH_EVENT_MSG\fR" 8
d1123 7
a1129 6
\f(CWpth_msgport_t\fR. This events waits until one or more messages were received
on the specified message port.  Example: `\f(CWpth_event(PTH_EVENT_MSG, mp)\fR\*(R'.
.Ip "\f(CWPTH_EVENT_TID\fR" 8
This is a thread event. The additional argument has to be of type \f(CWpth_t\fR.
One of \f(CWPTH_UNTIL_TID_NEW\fR, \f(CWPTH_UNTIL_TID_READY\fR, \f(CWPTH_UNTIL_TID_WAITING\fR
or \f(CWPTH_UNTIL_TID_DEAD\fR has to be \s-1OR\s0\-ed into \fIspec\fR to specify on which
d1131 3
a1133 2
`\f(CWpth_event(PTH_EVENT_TID|PTH_UNTIL_TID_DEAD, tid)\fR\*(R'.
.Ip "\f(CWPTH_EVENT_FUNC\fR" 8
d1135 2
a1136 2
have to be given with the following types: `\f(CWint (*)(void *)\fR\*(R',
`\f(CWvoid *\fR\*(R' and `\f(CWpth_time_t\fR\*(R'. The first is a function pointer to
d1141 1
a1141 1
\f(CWFALSE\fR. Once it returned \f(CWTRUE\fR the thread will be awakened. The
d1144 4
a1147 1
`\f(CWpth_event(PTH_EVENT_FUNC, func, arg, pth_time(0,500000))\fR\*(R'.
d1149 1
d1151 1
a1151 1
\f(CWPTH_EVENT_XX\fR and \f(CWPTH_UNTIL_XX\fR value. This is especially useful to know
d1154 1
d1156 1
a1156 1
\fIsscanf\fR\|(3), i.e., it is the inverse operation of \fIpth_event\fR\|(3). This means that
d1162 3
a1164 3
To make it clear, when you constructed \fIev\fR via `\f(CWev =
pth_event(PTH_EVENT_FD, fd);\fR\*(R' you have to extract it via
`\f(CWpth_event_extract(ev, &fd)\fR\*(R', etc. For multiple arguments of an event the
d1170 1
d1173 1
a1173 1
\f(CWNULL\fR argument. Use this function to create real events rings out of the
d1176 1
d1178 1
a1178 1
When in \fIev\fR only one event exists, this returns \f(CWNULL\fR. When remaining
d1181 5
a1185 4
This walks to the next (when \fIdirection\fR is \f(CWPTH_WALK_NEXT\fR) or previews
(when \fIdirection\fR is \f(CWPTH_WALK_PREV\fR) event in the event ring \fIev\fR and
returns this new reached event. Additionally \f(CWPTH_UNTIL_OCCURRED\fR can be
\s-1OR\s0\-ed into \fIdirection\fR to walk to the next/previous occurred event in the
d1188 1
d1194 2
a1195 1
This deallocates the event \fIev\fR (when \fImode\fR is \f(CWPTH_FREE_THIS\fR) or all
d1197 1
a1197 1
\f(CWPTH_FREE_ALL\fR).
d1199 1
d1203 1
d1208 1
d1211 1
d1214 1
d1217 1
d1221 1
d1226 1
d1230 1
d1234 1
d1237 1
d1240 1
d1245 1
d1248 1
d1251 1
d1256 1
d1258 1
a1258 1
current thread. When \fIexecute\fR is \f(CWTRUE\fR the routine is additionally called.
d1260 1
d1264 1
d1266 3
a1268 3
\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
d1271 1
a1271 1
points, the corresponding handler can be given as \f(CWNULL\fR.  Each handler is
d1275 1
a1275 1
\fIchild\fR handlers are called in the order in which they were established by
d1279 1
d1281 1
a1281 1
established with the last \fIpth_atfork_push\fR\|(3) call. It returns \f(CWFALSE\fR when no
d1284 1
d1293 1
d1308 4
a1311 3
This dynamically initializes a mutex variable of type `\f(CWpth_mutex_t\fR\*(R'.
Alternatively one can also use static initialization via `\f(CWpth_mutex_t
mutex = PTH_MUTEX_INIT\fR\*(R'.
d1313 1
d1317 1
a1317 1
\f(CWNULL\fR).  Recursive locking is explicitly supported, i.e., a thread is allowed
d1320 2
a1321 2
When \fItry\fR is \f(CWTRUE\fR this function never suspends execution. Instead it
returns \f(CWFALSE\fR with \f(CWerrno\fR set to \f(CWEBUSY\fR.
d1323 1
d1327 1
d1329 2
a1330 2
`\f(CWpth_rwlock_t\fR\*(R'.  Alternatively one can also use static initialization
via `\f(CWpth_rwlock_t rwlock = PTH_RWLOCK_INIT\fR\*(R'.
d1332 3
a1334 2
This acquires a read-only (when \fIop\fR is \f(CWPTH_RWLOCK_RD\fR) or a read-write
(when \fIop\fR is \f(CWPTH_RWLOCK_RW\fR) lock \fIrwlock\fR. When the lock is only locked
d1338 2
a1339 2
the locking timeout, etc. When \fItry\fR is \f(CWTRUE\fR this function never suspends
execution. Instead it returns \f(CWFALSE\fR with \f(CWerrno\fR set to \f(CWEBUSY\fR.
d1341 1
d1344 1
d1346 2
a1347 2
`\f(CWpth_cond_t\fR\*(R'.  Alternatively one can also use static initialization via
`\f(CWpth_cond_t cond = PTH_COND_INIT\fR\*(R'.
d1349 1
d1353 2
a1354 2
either until the events in \fIev\fR occurred (when \fIev\fR is not \f(CWNULL\fR) or
\fIcond\fR was notified by another thread via \fIpth_cond_notify\fR\|(3).  While the
d1358 1
d1360 1
a1360 1
\fIbroadcast\fR is \f(CWTRUE\fR all thread are notified, else only a single
d1362 5
a1366 4
.Ip "int \fBpth_barrier_init\fR(pth_barrier_t *\fIbarrier\fR, int I<threshold);" 4
This dynamically initializes a barrier variable of type `\f(CWpth_barrier_t\fR\*(R'.
Alternatively one can also use static initialization via `\f(CWpth_barrier_t
barrier = PTH_BARRIER_INIT(\fR\fIthreadhold\fR\f(CW)\fR\*(R'.
d1368 1
d1372 4
a1375 4
and this way awakes all threads. The function returns (beside \f(CWFALSE\fR on
error) the value \f(CWTRUE\fR for any thread which neither reached the barrier as
the first nor the last thread; \f(CWPTH_BARRIER_HEADLIGHT\fR for the thread which
reached the barrier as the first thread and \f(CWPTH_BARRIER_TAILLIGHT\fR for the
d1378 1
d1380 2
a1381 2
\s-1API\s0, i.e., they are similar to the functions under `\fBStandard \s-1POSIX\s0
Replacement \s-1API\s0\fR\*(R' but all have an additional event argument which can be used
d1384 1
d1389 1
a1389 1
\fIev\fR actually is an event \fIring\fR).
d1391 1
d1394 1
a1394 1
usually only uses the I/O event on \fIfd\fR to awake. With this function any
d1396 1
a1396 1
\fIev\fR actually is an event \fIring\fR).
d1398 1
d1401 1
a1401 1
usually only uses the I/O event on \fIfd\fR to awake. With this function any
d1403 1
a1403 1
\fIev\fR actually is an event \fIring\fR).
d1405 1
d1412 1
d1414 1
a1414 1
\fIev\fR. When \fIpth_poll\fR\|(3) suspends the current threads execution it usually only
d1419 1
d1421 1
a1421 1
\fIev\fR. When \fIpth_read\fR\|(3) suspends the current threads execution it usually only
d1426 1
d1431 1
a1431 1
\fIev\fR actually is an event \fIring\fR).
d1433 1
d1435 1
a1435 1
\fIev\fR. When \fIpth_write\fR\|(3) suspends the current threads execution it usually
d1440 1
d1445 1
a1445 1
\fIev\fR actually is an event \fIring\fR).
d1447 1
d1452 1
a1452 1
\fIev\fR actually is an event \fIring\fR).
d1454 1
d1459 1
a1459 1
\fIev\fR actually is an event \fIring\fR).
d1461 1
d1466 1
a1466 1
\fIev\fR actually is an event \fIring\fR).
d1468 1
d1473 1
a1473 1
\fIev\fR actually is an event \fIring\fR).
d1475 1
d1480 1
d1489 1
d1494 1
a1494 1
\fIsleep\fR\|(3) and \fIpth_sleep\fR\|(3) is that that \fIpth_sleep\fR\|(3) suspends only the
d1497 1
d1501 1
a1501 1
\fIpth_waitpid\fR\|(3) is that that \fIpth_waitpid\fR\|(3) suspends only the execution of the
d1505 1
d1507 1
a1507 1
\fIpthread_sigmask\fR\|(3). The arguments \fIhow\fR, \fIset\fR and \fIoset\fR directly relate
d1512 1
d1522 1
d1526 1
a1526 1
\fIpth_connect\fR\|(3) suspends only the execution of the current thread and not the
d1530 1
d1539 1
d1546 1
d1553 1
d1560 1
d1566 1
a1566 1
\fIreadv\fR\|(2).
d1568 1
d1571 1
a1571 1
\fIpth_write\fR\|(2) is that that \fIpth_write\fR\|(2) suspends execution of the current
d1575 1
d1581 1
a1581 1
\fIwritev\fR\|(2).
d1583 1
d1590 1
d1597 1
d1599 1
a1599 1
``\fIpth_recvfrom\fR\|(fd, buf, nbytes, flags, \s-1NULL\s0, 0)'\*(R'.
d1601 1
d1603 3
a1605 3
\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 that \fIpth_recvfrom\fR\|(2) suspends execution of the
d1609 1
d1611 1
a1611 1
``\fIpth_sendto\fR\|(fd, buf, nbytes, flags, \s-1NULL\s0, 0)'\*(R'.
d1613 1
d1616 1
a1616 1
\fIto\fR/\fItolen\fR. The difference between \fIsendto\fR\|(2) and \fIpth_sendto\fR\|(2) is
d1621 1
d1623 1
a1623 1
listening on TCP port 12345 and displaying the current time to the
d1627 1
a1627 1
\f(CWstderr\fR every 5 seconds. The example contains \fIno\fR error checking and
d1723 1
d1728 1
d1730 2
a1731 2
source file \f(CWfoo.c\fR. Then we can create a very simple build environment by
just adding the following \f(CWMakefile\fR:
d1749 1
a1749 1
\fBPth\fR installation via its \f(CWpth-config\fR program. This approach is
d1752 1
d1759 1
a1759 1
\fBPth\fR version to make sure it is at least a minimum required version.
d1762 1
a1762 1
can be done if we use \s-1GNU\s0 \fBautoconf\fR and the \f(CWAC_CHECK_PTH\fR macro
d1765 1
a1765 1
First we again need the \f(CWMakefile\fR, but this time it contains \fBautoconf\fR
d1767 1
a1767 1
\f(CWMakefile.in\fR, because it is now an input file for \fBautoconf\fR:
d1789 1
a1789 1
\f(CWdistclean\fR target which cleanups this, too. Second, we write
d1791 1
a1791 1
\f(CWconfigure.in\fR:
d1799 3
a1801 3
Then we let \fBautoconf\fR's \f(CWaclocal\fR program generate for us an \f(CWaclocal.m4\fR
file containing \fBPth\fR's \f(CWAC_CHECK_PTH\fR macro. Then we generate the final
\f(CWconfigure\fR script out of this \f(CWaclocal.m4\fR file and the \f(CWconfigure.in\fR
d1818 3
a1820 3
If we now run \f(CWconfigure\fR we get a correct \f(CWMakefile\fR which
immediately can be used to build \f(CWfoo\fR (assuming that \fBPth\fR is already
installed somewhere, so that \f(CWpth-config\fR is in \f(CW$PATH\fR):
d1840 5
a1844 5
If \fBPth\fR is installed in non-standard locations or \f(CWpth-config\fR
is not in \f(CW$PATH\fR, one just has to drop the \f(CWconfigure\fR script
a note about the location by running \f(CWconfigure\fR with the option
\f(CW--with-pth=\fR\fIdir\fR (where \fIdir\fR is the argument which was used with
the \f(CW--prefix\fR option when \fBPth\fR was installed).
d1846 3
a1848 2
Finally let us assume the \f(CWfoo\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
d1850 1
a1850 1
end-user first has to install \fBPth\fR just to allow our \f(CWfoo\fR package to
d1852 3
a1854 3
libraries (here \fBPth\fR) into the source tree of the package (here \f(CWfoo\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(CWpth/\fR and this
d1856 1
a1856 1
process of \f(CWfoo\fR.
d1858 1
a1858 1
First we again start with the \f(CWMakefile.in\fR, but this time it is a more
d1897 1
a1897 1
Then we create a slightly different \fBautoconf\fR script \f(CWconfigure.in\fR:
d1907 4
a1910 4
Here we provided a default value for \f(CWfoo\fR's \f(CW--with-pth\fR option as the
second argument to \f(CWAC_CHECK_PTH\fR which indicates that \fBPth\fR can be found in
the subdirectory named \f(CWpth/\fR. Additionally we specified that the
\f(CW--disable-tests\fR option of \fBPth\fR should be passed to the \f(CWpth/\fR
d1912 2
a1913 2
added a \f(CWAC_CONFIG_SUBDIR\fR call which indicates to \fBautoconf\fR that it should
configure the \f(CWpth/\fR subdirectory, too. The \f(CWAC_CONFIG_AUX_DIR\fR directive
d1915 1
a1915 1
\f(CWinstall.sh\fR or \f(CWshtool\fR script if \f(CWAC_CONFIG_SUBDIRS\fR is used.
d1917 4
a1920 4
Now we let \fBautoconf\fR's \f(CWaclocal\fR program again generate for us an
\f(CWaclocal.m4\fR file with the contents of \fBPth\fR's \f(CWAC_CHECK_PTH\fR macro.
Finally we generate the \f(CWconfigure\fR script out of this \f(CWaclocal.m4\fR
file and the \f(CWconfigure.in\fR file.
d1926 2
a1927 2
Now we have to create the \f(CWpth/\fR subdirectory itself. For this, we extract the
\fBPth\fR distribution to the \f(CWfoo\fR source tree and just rename it to \f(CWpth/\fR:
d1933 1
a1933 1
Optionally to reduce the size of the \f(CWpth/\fR subdirectory, we can strip down
d1942 1
a1942 1
After this the source tree of \f(CWfoo\fR should look similar to this:
d1970 1
a1970 1
Now when we configure and build the \f(CWfoo\fR package it looks similar to this:
d2006 2
a2007 2
(stripped down) copy of \fBPth\fR in the subdirectory \f(CWpth/\fR and the
\f(CWMakefile\fR automatically builds the subdirectory, too.
d2009 2
a2010 1
\fBPth\fR per default uses an explicit API, including the system calls. For
d2012 1
a2012 1
\fIread\fR\|(3) and cannot expect that by just calling \fIread\fR\|(3) only the current thread
d2016 1
a2016 1
to \fIread\fR\|(3) `magically\*(R' means \fIpth_read\fR\|(3). The problem here is that such
d2020 1
d2022 5
a2026 5
building \fBPth\fR with \f(CW--enable-syscall-soft\fR. This then triggers some
\f(CW#define\fR's in the \f(CWpth.h\fR header which map for instance \fIread\fR\|(3) to
\fIpth_read\fR\|(3), etc.  Currently the following functions are mapped: \fIfork\fR\|(2),
\fIsleep\fR\|(3), \fIsigwait\fR\|(3), \fIwaitpid\fR\|(2), \fIselect\fR\|(2), \fIpoll\fR\|(2), \fIconnect\fR\|(2),
\fIaccept\fR\|(2), \fIread\fR\|(2), \fIwrite\fR\|(2).
d2030 1
a2030 1
\f(CWpth.h\fR, of course. And this also means that existing libraries,
d2034 1
d2037 2
a2038 2
\f(CW--enable-syscall-hard\fR. This then builds wrapper functions (for instances
\fIread\fR\|(3)) into the \fBPth\fR library which internally call the real \fBPth\fR
d2041 1
a2041 1
\fIaccept\fR\|(2), \fIread\fR\|(2), \fIwrite\fR\|(2).
d2048 1
a2048 1
\f(CWpth.h\fR and that existing libraries, including the vendor's \fBstdio\fR,
d2051 2
a2052 1
\fBPth\fR is very portable because it has only one part which perhaps has
d2056 1
a2056 1
\f(CWpth_mctx.c\fR for details]. Any other \fBPth\fR code is POSIX and ANSI C
d2059 2
a2060 2
The context switching is done via either SUSv2 \fImakecontext\fR\|(2) or POSIX
make[sig]\fIsetjmp\fR\|(3) and [sig]\fIlongjmp\fR\|(3). Here all CPU registers, the
d2062 3
a2064 3
\fBPth\fR dispatcher switches also the global Unix \f(CWerrno\fR variable [see
\f(CWpth_mctx.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).
d2069 1
a2069 1
single central \fIselect\fR\|(2) call [see \f(CWpth_sched.c\fR for details].
d2075 1
a2075 1
entry point [see \f(CWpth_tcb.h\fR and \f(CWpth_pqueue.c\fR for details].
d2078 1
a2078 1
manager) are speeded up by inlined functions (implemented as ANSI C
d2080 3
a2082 3
removed from the source when not built with \f(CW-DPTH_DEBUG\fR (see Autoconf
\f(CW--enable-debug\fR option), i.e., not only stub functions remain [see
\f(CWpth_debug.h\fR for details].
d2084 2
a2085 1
\fBPth\fR (intentionally) provides no replacements for non-thread-safe
d2092 2
a2093 2
existing \f(CWlibc_r\fR of the platform vendor). For an asynchronous DNS
resolver library use the GNU \fBadns\fR package from Ian Jackson ( see
d2096 1
d2100 1
a2100 1
\fIPeter Simons\fR, \fIMartin Kraemer\fR, \fILars Eilebrecht\fR and \fIRalph
d2104 1
a2104 1
\fBPth\fR was then implemented in order to combine the \fInon-preemptive\fR
d2106 1
a2106 1
performance) with an API similar to the popular one found in \fBPthread\fR
d2110 1
a2110 1
\fIPeter Simons\fR scheduler. The priority based scheduling algorithm was
d2114 1
a2114 1
The concept and API of message ports was borrowed from AmigaOS\*(R' \fBExec\fR
d2117 1
a2117 1
\fBBIND\fR v8).
d2119 1
d2122 1
a2122 1
fix the problem and include a patch, made with \*(L'\f(CWdiff -u3\fR\*(R', in your
d2127 3
a2129 3
\fIpth-users@@gnu.org\fR mailing list by sending an Email to
\fIpth-users-request@@gnu.org\fR with `\f(CWsubscribe pth-users\fR\*(R' (or
`\f(CWsubscribe pth-users\fR \fIaddress\fR\*(R' if you want to subscribe
d2132 1
a2132 1
\fIpth-users@@gnu.org\fR. Currently (as of August 2000) you can reach about
d2134 1
a2134 1
\fIhttp://www.mail-archive.com/pth-users@@gnu.org/\fR.
d2136 1
d2138 2
a2139 1
`comp.programming.threads Newsgroup Archive\*(R',
d2143 2
a2144 2
`comp.programming.threads Frequently Asked Questions (F.A.Q.)\*(R',
http://www.lambdacs.com/newsgroup/\s-1FAQ\s0.html
d2146 1
a2146 1
`\fIMultithreading \- Definitions and Guidelines\fR\*(R',
d2150 1
a2150 1
`\fIThe Single \s-1UNIX\s0 Specification, Version 2 \- Threads\fR\*(R',
d2154 1
a2154 1
\s-1SMI\s0 Thread Resources,
d2162 1
d2164 1
a2164 1
`\fIPthreads Programming \- A \s-1POSIX\s0 Standard for Better Multiprocessing\fR\*(R',
d2166 1
a2166 1
\s-1ISBN\s0 1-56592-115-1
d2169 1
a2169 1
`\fIMultithreaded Programming with Pthreads\fR\*(R',
d2171 1
a2171 1
\s-1ISBN\s0 0-13-680729-1
d2174 1
a2174 1
`\fIThreads Primer \- A Guide To Multithreaded Programming\fR\*(R',
d2176 1
a2176 1
\s-1ISBN\s0 0-13-443698-9
d2179 1
a2179 1
`\fIThread Time \- The Multithreaded Programming Guide\fR\*(R',
d2181 1
a2181 1
\s-1ISBN\s0 0-13-190067-6
d2184 1
a2184 1
`\fIProgramming with \s-1POSIX\s0 Threads\fR\*(R',
d2186 1
a2186 1
\s-1ISBN\s0 0-201-63392-2
d2188 2
a2189 1
pth-\fIconfig\fR\|(1), \fIpthread\fR\|(3).
d2191 4
a2194 4
\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).
d2196 1
a2196 1
.PP
a2201 379

.rn }` ''
.IX Title "pth 3"
.IX Name "B<pth> - GNU Portable Threads"

.IX Header "NAME"

.IX Header "VERSION"

.IX Header "SYNOPSIS"

.IX Item "\fBGlobal Library Management\fR"

.IX Item "\fBThread Attribute Handling\fR"

.IX Item "\fBThread Control\fR"

.IX Item "\fBUtilities\fR"

.IX Item "\fBCancellation Management\fR"

.IX Item "\fBEvent Handling\fR"

.IX Item "\fBKey-Based Storage\fR"

.IX Item "\fBMessage Port Communication\fR"

.IX Item "\fBThread Cleanups\fR"

.IX Item "\fBProcess Forking\fR"

.IX Item "\fBSynchronization\fR"

.IX Item "\fBGeneralized \s-1POSIX\s0 Replacement \s-1API\s0\fR"

.IX Item "\fBStandard \s-1POSIX\s0 Replacement \s-1API\s0\fR"

.IX Header "DESCRIPTION"

.IX Subsection "Threading Background"

.IX Subsection "The World of Threading"

.IX Item "\fBo\fR \fBprocess\fR vs. \fBthread\fR"

.IX Item "\fBo\fR \fBkernel-space\fR vs. \fBuser-space\fR threading"

.IX Item "\fBo\fR \fBpreemptive\fR vs. \fBnon-preemptive\fR thread scheduling"

.IX Item "\fBo\fR \fBconcurrency\fR vs. \fBparallelism\fR"

.IX Item "\fBo\fR \fBresponsiveness\fR"

.IX Item "\fBo\fR \fBreentrant\fR, \fBthread-safe\fR and \fBasynchronous-safe\fR functions"

.IX Subsection "User-Space Threads"

.IX Item "\fB1.\fR"

.IX Item "\fB2.\fR"

.IX Subsection "The Compromise of Pth"

.IX Item "\fBo\fR"

.IX Item "\fBo\fR"

.IX Item "\fBo\fR"

.IX Item "\fBo\fR"

.IX Subsection "The life cycle of a thread"

.IX Header "APPLICATION PROGRAMMING INTERFACE (API)"

.IX Subsection "Global Library Management"

.IX Item "int \fBpth_init\fR(void);"

.IX Item "int \fBpth_kill\fR(void);"

.IX Item "long \fBpth_ctrl\fR(unsigned long \fIquery\fR, ...);"

.IX Item "\f(CWPTH_CTRL_GETTHREADS\fR"

.IX Item "\f(CWPTH_CTRL_GETAVLOAD\fR"

.IX Item "\f(CWPTH_CTRL_GETPRIO\fR"

.IX Item "\f(CWPTH_CTRL_GETNAME\fR"

.IX Item "\f(CWPTH_CTRL_DUMPSTATE\fR"

.IX Item "long \fBpth_version\fR(void);"

.IX Subsection "Thread Attribute Handling"

.IX Item "\f(CWPTH_ATTR_PRIO\fR (read-write) [\f(CWint\fR]"

.IX Item "\f(CWPTH_ATTR_NAME\fR (read-write) [\f(CWchar *\fR]"

.IX Item "\f(CWPTH_ATTR_JOINABLE\fR (read-write> [\f(CWint\fR]"

.IX Item "\f(CWPTH_ATTR_CANCEL_STATE\fR (read-write) [\f(CWunsigned int\fR]"

.IX Item "\f(CWPTH_ATTR_STACK_SIZE\fR (read-write) [\f(CWunsigned int\fR]"

.IX Item "\f(CWPTH_ATTR_STACK_ADDR\fR (read-write) [\f(CWchar *\fR]"

.IX Item "\f(CWPTH_ATTR_TIME_SPAWN\fR (read-only) [\f(CWpth_time_t\fR]"

.IX Item "\f(CWPTH_ATTR_TIME_LAST\fR (read-only) [\f(CWpth_time_t\fR]"

.IX Item "\f(CWPTH_ATTR_TIME_RAN\fR (read-only) [\f(CWpth_time_t\fR]"

.IX Item "\f(CWPTH_ATTR_START_FUNC\fR (read-only) [\f(CWvoid *(*)(void *)\fR]"

.IX Item "\f(CWPTH_ATTR_START_ARG\fR (read-only) [\f(CWvoid *\fR]"

.IX Item "\f(CWPTH_ATTR_STATE\fR (read-only) [\f(CWpth_state_t\fR]"

.IX Item "\f(CWPTH_ATTR_EVENTS\fR (read-only) [\f(CWpth_event_t\fR]"

.IX Item "\f(CWPTH_ATTR_BOUND\fR (read-only) [\f(CWint\fR]"

.IX Item "pth_attr_t \fBpth_attr_of\fR(pth_t \fItid\fR);"

.IX Item "pth_attr_t \fBpth_attr_new\fR(void);"

.IX Item "int \fBpth_attr_init\fR(pth_attr_t \fIattr\fR);"

.IX Item "int \fBpth_attr_set\fR(pth_attr_t \fIattr\fR, int \fIfield\fR, ...);"

.IX Item "int \fBpth_attr_get\fR(pth_attr_t \fIattr\fR, int \fIfield\fR, ...);"

.IX Item "int \fBpth_attr_destroy\fR(pth_attr_t \fIattr\fR);"

.IX Subsection "Thread Control"

.IX Item "pth_t \fBpth_spawn\fR(pth_attr_t \fIattr\fR, void *(*\fIentry\fR)(void *), void *\fIarg\fR);"

.IX Item "int \fBpth_once\fR(pth_once_t *\fIctrlvar\fR, void (*\fIfunc\fR)(void *), void *\fIarg\fR);"

.IX Item "pth_t \fBpth_self\fR(void);"

.IX Item "int \fBpth_suspend\fR(pth_t \fItid\fR);"

.IX Item "int \fBpth_resume\fR(pth_t \fItid\fR);"

.IX Item "int \fBpth_raise\fR(pth_t \fItid\fR, int \fIsig\fR)"

.IX Item "int \fBpth_yield\fR(pth_t \fItid\fR);"

.IX Item "int \fBpth_nap\fR(pth_time_t \fInaptime\fR);"

.IX Item "int \fBpth_wait\fR(pth_event_t \fIev\fR);"

.IX Item "int \fBpth_cancel\fR(pth_t \fItid\fR);"

.IX Item "int \fBpth_abort\fR(pth_t \fItid\fR);"

.IX Item "int \fBpth_join\fR(pth_t \fItid\fR, void **\fIvalue\fR);"

.IX Item "void \fBpth_exit\fR(void *\fIvalue\fR);"

.IX Subsection "Utilities"

.IX Item "int \fBpth_fdmode\fR(int \fIfd\fR, int \fImode\fR);"

.IX Item "pth_time_t \fBpth_time\fR(long \fIsec\fR, long \fIusec\fR);"

.IX Item "pth_time_t \fBpth_timeout\fR(long \fIsec\fR, long \fIusec\fR);"

.IX Item "Sfdisc_t *\fBpth_sfiodisc\fR(void);"

.IX Subsection "Cancellation Management"

.IX Item "void \fBpth_cancel_state\fR(int \fInewstate\fR, int *\fIoldstate\fR);"

.IX Item "void \fBpth_cancel_point\fR(void);"

.IX Subsection "Event Handling"

.IX Item "pth_event_t \fBpth_event\fR(unsigned long \fIspec\fR, ...);"

.IX Item "\f(CWPTH_EVENT_FD\fR"

.IX Item "\f(CWPTH_EVENT_SELECT\fR"

.IX Item "\f(CWPTH_EVENT_SIGS\fR"

.IX Item "\f(CWPTH_EVENT_TIME\fR"

.IX Item "\f(CWPTH_EVENT_MSG\fR"

.IX Item "\f(CWPTH_EVENT_TID\fR"

.IX Item "\f(CWPTH_EVENT_FUNC\fR"

.IX Item "unsigned long \fBpth_event_typeof\fR(pth_event_t \fIev\fR);"

.IX Item "int \fBpth_event_extract\fR(pth_event_t \fIev\fR, ...);"

.IX Item "pth_event_t \fBpth_event_concat\fR(pth_event_t \fIev\fR, ...);"

.IX Item "pth_event_t \fBpth_event_isolate\fR(pth_event_t \fIev\fR);"

.IX Item "pth_event_t \fBpth_event_walk\fR(pth_event_t \fIev\fR, int \fIdirection\fR);"

.IX Item "int \fBpth_event_occurred\fR(pth_event_t \fIev\fR);"

.IX Item "int \fBpth_event_free\fR(pth_event_t \fIev\fR, int \fImode\fR);"

.IX Subsection "Key-Based Storage"

.IX Item "int \fBpth_key_create\fR(pth_key_t *\fIkey\fR, void (*\fIfunc\fR)(void *));"

.IX Item "int \fBpth_key_delete\fR(pth_key_t \fIkey\fR);"

.IX Item "int \fBpth_key_setdata\fR(pth_key_t \fIkey\fR, const void *\fIvalue\fR);"

.IX Item "void *\fBpth_key_getdata\fR(pth_key_t \fIkey\fR);"

.IX Subsection "Message Port Communication"

.IX Item "pth_msgport_t \fBpth_msgport_create\fR(const char *\fIname\fR);"

.IX Item "void \fBpth_msgport_destroy\fR(pth_msgport_t \fImp\fR);"

.IX Item "pth_msgport_t \fBpth_msgport_find\fR(const char *\fIname\fR);"

.IX Item "int \fBpth_msgport_pending\fR(pth_msgport_t \fImp\fR);"

.IX Item "int \fBpth_msgport_put\fR(pth_msgport_t \fImp\fR, pth_message_t *\fIm\fR);"

.IX Item "pth_message_t *\fBpth_msgport_get\fR(pth_msgport_t \fImp\fR);"

.IX Item "int \fBpth_msgport_reply\fR(pth_message_t *\fIm\fR);"

.IX Subsection "Thread Cleanups"

.IX Item "int \fBpth_cleanup_push\fR(void (*\fIhandler\fR)(void *), void *\fIarg\fR);"

.IX Item "int \fBpth_cleanup_pop\fR(int \fIexecute\fR);"

.IX Subsection "Process Forking"

.IX Item "int \fBpth_atfork_push\fR(void (*\fIprepare\fR)(void *), void (*)(void *\fIparent\fR), void (*)(void *\fIchild\fR), void *\fIarg\fR);"

.IX Item "int \fBpth_atfork_pop\fR(void);"

.IX Item "pid_t \fBpth_fork\fR(void);"

.IX Subsection "Synchronization"

.IX Item "int \fBpth_mutex_init\fR(pth_mutex_t *\fImutex\fR);"

.IX Item "int \fBpth_mutex_acquire\fR(pth_mutex_t *\fImutex\fR, int \fItry\fR, pth_event_t \fIev\fR);"

.IX Item "int \fBpth_mutex_release\fR(pth_mutex_t *\fImutex\fR);"

.IX Item "int \fBpth_rwlock_init\fR(pth_rwlock_t *\fIrwlock\fR);"

.IX Item "int \fBpth_rwlock_acquire\fR(pth_rwlock_t *\fIrwlock\fR, int \fIop\fR, int \fItry\fR, pth_event_t \fIev\fR);"

.IX Item "int \fBpth_rwlock_release\fR(pth_rwlock_t *\fIrwlock\fR);"

.IX Item "int \fBpth_cond_init\fR(pth_cond_t *\fIcond\fR);"

.IX Item "int \fBpth_cond_await\fR(pth_cond_t *\fIcond\fR, pth_mutex_t *\fImutex\fR, pth_event_t \fIev\fR);"

.IX Item "int \fBpth_cond_notify\fR(pth_cond_t *\fIcond\fR, int \fIbroadcast\fR);"

.IX Item "int \fBpth_barrier_init\fR(pth_barrier_t *\fIbarrier\fR, int I<threshold);"

.IX Item "int \fBpth_barrier_reach\fR(pth_barrier_t *\fIbarrier\fR);"

.IX Subsection "Generalized \s-1POSIX\s0 Replacement \s-1API\s0"

.IX Item "int \fBpth_sigwait_ev\fR(const sigset_t *\fIset\fR, int *\fIsig\fR, pth_event_t \fIev\fR);"

.IX Item "int \fBpth_connect_ev\fR(int \fIs\fR, const struct sockaddr *\fIaddr\fR, socklen_t \fIaddrlen\fR, pth_event_t \fIev\fR);"

.IX Item "int \fBpth_accept_ev\fR(int \fIs\fR, struct sockaddr *\fIaddr\fR, socklen_t *\fIaddrlen\fR, pth_event_t \fIev\fR);"

.IX Item "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);"

.IX Item "int \fBpth_poll_ev\fR(struct pollfd *\fIfds\fR, unsigned int \fInfd\fR, int \fItimeout\fR, pth_event_t \fIev\fR);"

.IX Item "ssize_t \fBpth_read_ev\fR(int \fIfd\fR, void *\fIbuf\fR, size_t \fInbytes\fR, pth_event_t \fIev\fR);"

.IX Item "ssize_t \fBpth_readv_ev\fR(int \fIfd\fR, const struct iovec *\fIiovec\fR, int \fIiovcnt\fR, pth_event_t \fIev\fR);"

.IX Item "ssize_t \fBpth_write_ev\fR(int \fIfd\fR, const void *\fIbuf\fR, size_t \fInbytes\fR, pth_event_t \fIev\fR);"

.IX Item "ssize_t \fBpth_writev_ev\fR(int \fIfd\fR, const struct iovec *\fIiovec\fR, int \fIiovcnt\fR, pth_event_t \fIev\fR);"

.IX Item "ssize_t \fBpth_recv_ev\fR(int \fIfd\fR, void *\fIbuf\fR, size_t \fInbytes\fR, int \fIflags\fR, pth_event_t \fIev\fR);"

.IX Item "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);"

.IX Item "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);"

.IX Item "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);"

.IX Subsection "Standard \s-1POSIX\s0 Replacement \s-1API\s0"

.IX Item "int \fBpth_usleep\fR(unsigned int \fIusec\fR);"

.IX Item "unsigned int \fBpth_sleep\fR(unsigned int \fIsec\fR);"

.IX Item "pid_t \fBpth_waitpid\fR(pid_t \fIpid\fR, int *\fIstatus\fR, int \fIoptions\fR);"

.IX Item "int \fBpth_sigmask\fR(int \fIhow\fR, const sigset_t *\fIset\fR, sigset_t *\fIoset\fR)"

.IX Item "int \fBpth_sigwait\fR(const sigset_t *\fIset\fR, int *\fIsig\fR);"

.IX Item "int \fBpth_connect\fR(int \fIs\fR, const struct sockaddr *\fIaddr\fR, socklen_t \fIaddrlen\fR);"

.IX Item "int \fBpth_accept\fR(int \fIs\fR, struct sockaddr *\fIaddr\fR, socklen_t *\fIaddrlen\fR);"

.IX Item "int \fBpth_select\fR(int \fInfd\fR, fd_set *\fIrfds\fR, fd_set *\fIwfds\fR, fd_set *\fIefds\fR, struct timeval *\fItimeout\fR);"

.IX Item "int \fBpth_poll\fR(struct pollfd *\fIfds\fR, unsigned int \fInfd\fR, int \fItimeout\fR);"

.IX Item "ssize_t \fBpth_read\fR(int \fIfd\fR, void *\fIbuf\fR, size_t \fInbytes\fR);"

.IX Item "ssize_t \fBpth_readv\fR(int \fIfd\fR, const struct iovec *\fIiovec\fR, int \fIiovcnt\fR);"

.IX Item "ssize_t \fBpth_write\fR(int \fIfd\fR, const void *\fIbuf\fR, size_t \fInbytes\fR);"

.IX Item "ssize_t \fBpth_writev\fR(int \fIfd\fR, const struct iovec *\fIiovec\fR, int \fIiovcnt\fR);"

.IX Item "ssize_t \fBpth_pread\fR(int \fIfd\fR, void *\fIbuf\fR, size_t \fInbytes\fR, off_t \fIoffset\fR);"

.IX Item "ssize_t \fBpth_pwrite\fR(int \fIfd\fR, const void *\fIbuf\fR, size_t \fInbytes\fR, off_t \fIoffset\fR);"

.IX Item "ssize_t \fBpth_recv\fR(int \fIfd\fR, void *\fIbuf\fR, size_t \fInbytes\fR, int \fIflags\fR);"

.IX Item "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);"

.IX Item "ssize_t \fBpth_send\fR(int \fIfd\fR, const void *\fIbuf\fR, size_t \fInbytes\fR, int \fIflags\fR);"

.IX Item "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);"

.IX Header "EXAMPLE"

.IX Header "BUILD ENVIRONMENTS"

.IX Subsection "Manual Build Environment (Novice)"

.IX Subsection "Autoconf Build Environment (Advanced)"

.IX Subsection "Autoconf Build Environment with Local Copy of Pth (Expert)"

.IX Header "SYSTEM CALL WRAPPER FACILITY"

.IX Subsection "Soft System Call Mapping"

.IX Subsection "Hard System Call Mapping"

.IX Header "IMPLEMENTATION NOTES"

.IX Header "RESTRICTIONS"

.IX Header "HISTORY"

.IX Header "BUG REPORTS AND SUPPORT"

.IX Header "SEE ALSO"

.IX Subsection "Related Web Locations"

.IX Subsection "Related Books"

.IX Subsection "Related Manpages"

.IX Header "AUTHOR"

@


1.222
log
@*** empty log message ***
@
text
@d1372 1
a1372 1
elapsed. The thread is guaranteed to not awakened before this time, but
d1374 1
a1374 1
later, of course. The difference between \fIusleep\fR\|(3) and \fIpth_usleep\fR\|(3) is that
d1376 1
a1376 3
the whole process.  The function returns the value \f(CW0\fR if successful,
otherwise the value \f(CW-1\fR is returned and the global variable \f(CWerrno\fR is set
to indicate the error.
d1378 6
a1383 10
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 awakened 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 that
\fIpth_sleep\fR\|(3) suspends only the execution of the current thread and not the
whole process.  If the function returns because the requested time has
elapsed, the value returned will be \f(CW0\fR. If the function returns due to the
delivery of a signal, the value returned will be the unslept amount (the
requested time minus the time actually slept) in seconds.
@


1.221
log
@*** empty log message ***
@
text
@d1371 2
a1372 2
threads execution until \fIusec\fR microsecond (= \fIusec\fR * 1/1000000 sec)
elapsed.  The thread is guaranteed to not awakened before this time, but
d1374 1
a1374 1
later, of course.  The difference between \fIusleep\fR\|(3) and \fIpth_usleep\fR\|(3) is that
d1376 3
a1378 1
the whole process.
d1384 1
a1384 1
course.  The difference between \fIsleep\fR\|(3) and \fIpth_sleep\fR\|(3) is that that
d1386 4
a1389 1
whole process.
@


1.220
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "18-Jul-2000" "GNU Pth 1.4a3" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.4a3 (18-Jul-2000)
d1992 3
a1994 2
\fIpth-users@@gnu.org\fR. Currently (as of January 2000) you can reach about
50 Pth users on this mailing list.
@


1.219
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "01-Jul-2000" "GNU Pth 1.4a2" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.4a2 (01-Jul-2000)
@


1.218
log
@*** empty log message ***
@
text
@d406 1
a406 1
.Ip "\fBo\fR \fBpreemtive\fR vs. \fBnon-preemtive\fR thread scheduling" 2
d617 1
a617 1
this thread yields execution (either explicitly by yielding excution
d1088 1
a1088 1
\f(CWFALSE\fR. Once it returned \f(CWTRUE\fR the thread will be awakend. The
d1619 1
a1619 1
straight-foreward and works fine for small projects.
d1718 1
a1718 1
compile. For this, it is a convinient practice to include the required
d2104 1
a2104 1
.IX Item "\fBo\fR \fBpreemtive\fR vs. \fBnon-preemtive\fR thread scheduling"
@


1.217
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "21-May-2000" "GNU Pth 1.4a2" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.4a2 (21-May-2000)
@


1.216
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "19-Apr-2000" "GNU Pth 1.4a2" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.4a2 (19-Apr-2000)
@


1.215
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "16-Apr-2000" "GNU Pth 1.4a2" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.4a2 (16-Apr-2000)
@


1.214
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "16-Apr-2000" "GNU Pth 1.4a1" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.4a1 (16-Apr-2000)
@


1.213
log
@''
@
text
@d96 1
a96 1
.TH pth 3 "31-Mar-2000" "GNU Pth 1.4a1" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.4a1 (31-Mar-2000)
@


1.212
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "27-Mar-2000" "GNU Pth 1.4a1" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.4a1 (27-Mar-2000)
@


1.211
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "12-Mar-2000" "GNU Pth 1.4a1" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.4a1 (12-Mar-2000)
@


1.210
log
@*** empty log message ***
@
text
@d279 5
a283 1
pth_writev_ev.
d299 5
a303 1
pth_pwrite.
d1341 24
d1472 20
d2354 8
d2393 8
@


1.209
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "12-Mar-2000" "GNU Pth 1.3.4" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.3.4 (12-Mar-2000)
@


1.208
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "10-Mar-2000" "GNU Pth 1.3.3" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.3.3 (10-Mar-2000)
@


1.208.2.1
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "23-Mar-2000" "GNU Pth 1.3.4" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.3.4 (23-Mar-2000)
@


1.208.2.2
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "29-Mar-2000" "GNU Pth 1.3.4" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.3.4 (29-Mar-2000)
@


1.208.2.3
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "16-Apr-2000" "GNU Pth 1.3.4" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.3.4 (16-Apr-2000)
@


1.208.2.4
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "17-Apr-2000" "GNU Pth 1.3.5" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.3.5 (17-Apr-2000)
@


1.208.2.5
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "01-Jul-2000" "GNU Pth 1.3.5" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.3.5 (01-Jul-2000)
@


1.208.2.6
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "01-Jul-2000" "GNU Pth 1.3.6" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.3.6 (01-Jul-2000)
@


1.208.2.7
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "29-Jul-2000" "GNU Pth 1.3.7" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.3.7 (29-Jul-2000)
@


1.207
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "07-Mar-2000" "GNU Pth 1.3.3" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.3.3 (07-Mar-2000)
@


1.206
log
@*** empty log message ***
@
text
@d900 4
a903 5
particular cooperating thread.  If \fItid\fR is not \f(CWNULL\fR and points to a
\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, still
not \fIready\fR) this has no effect and is equal to calling this function with
\fItid\fR specified as \f(CWNULL\fR.
d906 2
a907 2
\f(CWerrno\fR set to \f(CWEINVAL\fR) if \fItid\fR specified and invalid or still not ready
thread.
@


1.205
log
@*** empty log message ***
@
text
@d975 1
a975 1
.Ip "pth_time_t \fBpth_time\fR(int \fIsec\fR, int \fIusec\fR);" 4
d979 1
a979 1
.Ip "pth_time_t \fBpth_timeout\fR(int \fIsec\fR, int \fIusec\fR);" 4
d2175 1
a2175 1
.IX Item "pth_time_t \fBpth_time\fR(int \fIsec\fR, int \fIusec\fR);"
d2177 1
a2177 1
.IX Item "pth_time_t \fBpth_timeout\fR(int \fIsec\fR, int \fIusec\fR);"
@


1.204
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "03-Mar-2000" "GNU Pth 1.3.3" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.3.3 (03-Mar-2000)
@


1.203
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "24-Feb-2000" "GNU Pth 1.3.2" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.3.2 (24-Feb-2000)
d746 1
a746 1
The thread stack size in bytes. Use lower values than 32KB with great care!
d789 1
a789 1
\f(CWPTH_CANCEL_DEFAULT\fR, \f(CWPTH_ATTR_STACK_SIZE\fR := 32*1024 and
d1520 1
a1520 1
\&     pth_attr_set(attr, PTH_ATTR_STACK_SIZE, 32*1024);
@


1.202
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "20-Feb-2000" "GNU Pth 1.3.1" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.3.1 (20-Feb-2000)
@


1.201
log
@*** empty log message ***
@
text
@d950 5
a954 4
awakened and stores the value of \fItid\fR's \fIpth_exit\fR\|(3) call into \fIvalue\fR and
returns to the caller. A thread can be joined only when it was \fInot\fR spawned
with \f(CWPTH_FLAG_NOJOIN\fR. A thread can only be joined once, i.e., after the
\fIpth_join\fR\|(3) call the thread \fItid\fR is removed from the system.
@


1.200
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "19-Feb-2000" "GNU Pth 1.3.0" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.3.0 (19-Feb-2000)
d730 1
a730 1
threads.  The following attribute fields exists in attribute objects:
d794 13
a806 3
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 fields exists:
d808 21
d830 2
a831 2
This destroys a attribute object \fIattr\fR. After this \fIattr\fR is no longer a
valid attribute object.
d1895 1
a1895 1
\fBPth\fR (intentionally) provides no replacements for thread-safe
@


1.199
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "13-Feb-2000" "GNU Pth 1.3.0" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.3.0 (13-Feb-2000)
@


1.198
log
@*** empty log message ***
@
text
@d1535 2
a1536 2
\fBPth\fR installation via its \f(CWpth-config\fR program. This approach works fine
for small projects.
d1538 11
a1548 10
The previous approach is simple but unflexible. 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 an 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(CWAC_CHECK_PTH\fR macro
provided by \fBPth\fR.  For this, we establish the following three files:
d1574 3
a1576 2
\f(CWdistclean\fR target which cleans up this, too.  Second, we write a
(minimalistic) \fBautoconf\fR script specification in a file \f(CWconfigure.in\fR:
d1581 1
a1581 1
\& | AC_CHECK_PTH(1.2.0)
d1603 3
a1605 2
If we now run \f(CWconfigure\fR we get a correct \f(CWMakefile\fR which immediately can
be used to build \f(CWfoo\fR (assuming that \fBPth\fR is already installed somewhere):
d1616 1
a1616 1
\& checking for GNU Pth... version 1.2.0, installed under /usr/local
d1622 2
a1623 2
\& gcc -g -O2 -I/sw/pkg/pth/include -c foo.c
\& gcc -L/sw/pkg/pth/lib -o foo foo.o -lpth
d1625 5
d1687 1
a1687 1
\& | AC_CHECK_PTH(1.2.0, subdir:pth --disable-tests)
d1701 4
a1704 4
Now we let \fBautoconf\fR's \f(CWaclocal\fR program again generate an \f(CWaclocal.m4\fR
file for us with the contents of \fBPth\fR's \f(CWAC_CHECK_PTH\fR macro and finally we
generate the \f(CWconfigure\fR script out of this \f(CWaclocal.m4\fR file and the
\f(CWconfigure.in\fR file:
d1765 1
a1765 1
\& checking for GNU Pth... version 1.3a1, local under pth
d1789 3
a1791 3
As you can see \fBautoconf\fR now automatically configures the local (stripped
down) copy of \fBPth\fR in the subdirectory \f(CWpth/\fR and the \f(CWMakefile\fR
automatically builds the subdirectory, too.
@


1.197
log
@*** empty log message ***
@
text
@d1410 7
a1416 8
The following example is a useless server which does nothing more
than listening on a TCP port (specified numerically on the command
line) 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(CWstderr\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.
d1431 3
d1481 1
a1481 7
.Vb 4
\&     if (argc != 2) {
\&         fprintf(stderr, "Usage: %s <port>\en", argv[0]);
\&         exit(1);
\&     }
.Ve
.Vb 3
a1482 1
\&     port = atoi(argv[1]);
d1497 1
a1497 1
\&     sar.sin_port = htons(port);
@


1.196
log
@*** empty log message ***
@
text
@d439 1
a439 1
traditional approach to achieve tread-safety is to wrap a function body
d450 1
a450 1
side-effects from within a signal handler context. Usually very less
d469 3
a471 4
function after each other controlled by this matrix. The threads
are created by more than one jump-trail through this matrix and by
switching the individual jump-trails between function calls controlled
by corresponding occurred events.
d673 1
a673 1
kills the treading system and returns \f(CWTRUE\fR.
d904 1
a904 1
just made pending. But when its \f(CWPTH_CANCEL_ASYNCHRONOUS\fR the tread is
d1478 6
@


1.195
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "13-Feb-2000" "GNU Pth 1.3b3" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.3b3 (13-Feb-2000)
@


1.194
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "11-Feb-2000" "GNU Pth 1.3b3" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.3b3 (11-Feb-2000)
a1041 5
.Ip "\f(CWPTH_EVENT_PID\fR" 8
This is a process event. Three additional arguments have to be given which
correspond to the arguments of the \fIwaitpid\fR\|(2) function: `\f(CWpid_t\fR\*(R', `\f(CWint
*\fR\*(R' and `\f(CWint\fR\*(R'.  This events waits until the process changed to the
specified state.  Example: `\f(CWpth_event(PTH_EVENT_PID, pid, &status, 0)\fR\*(R'.
d1043 11
a1053 7
This is a custom callback function event. Two additional arguments have to be
given with the following types: `\f(CWint (*)(void *)\fR\*(R' and `\f(CWvoid *\fR\*(R'. The
first is a function pointer and the second is an argument which is passed to
the function. The scheduler calls this function on a regular basis (on his own
scheduler stack, so be careful!) and the thread is kept sleeping while the
function returns 0. Once it returned not 0 the thread will be awakend.
Example: `\f(CWpth_event(PTH_EVENT_FUNC, func, arg)\fR\*(R'.
a2161 2

.IX Item "\f(CWPTH_EVENT_PID\fR"
@


1.193
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "04-Feb-2000" "GNU Pth 1.3b3" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.3b3 (04-Feb-2000)
@


1.192
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "28-Jan-2000" "GNU Pth 1.3b3" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.3b3 (28-Jan-2000)
@


1.191
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "28-Jan-2000" "GNU Pth 1.3b2" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.3b2 (28-Jan-2000)
@


1.190
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "26-Jan-2000" "GNU Pth 1.3b2" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.3b2 (26-Jan-2000)
@


1.189
log
@*** empty log message ***
@
text
@d1100 1
a1100 1
similar to the \s-1POSIX\s0 Pthread \s-1API\s0. Use this for thread specific global data.
d1869 1
a1869 1
July 1999 by \fIRalf S. Engelschall\fR after evaluating various (mostly
d1877 1
a1877 1
performance) with an API similar to the popular one found in Pthread
d1880 9
a1888 9
So the essential idea for the non-preemptive approach was taken over
from \fIPeter Simons\fR scheduler. The priority based scheduling algorithm
was contributed 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 API of message ports was borrowed from
AmigaOS\*(R' \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 \fBBIND\fR v8).
@


1.188
log
@*** empty log message ***
@
text
@d307 1
a307 1
execution (aka \*(L"multithreading") inside event-driven applications. All threads
d322 1
a322 1
("Pthreads") which can be used for backward compatibility to existing
d329 1
a329 1
machines, we use \*(L"multitasking\*(R" -- that is, we have the application
d440 1
a440 1
with an internal mutual exclusion lock (aka \*(L"mutex"). As you should
d553 1
a553 1
concept of \*(L"coroutines\*(R". On the other hand, event driven applications
d605 1
a605 1
priority of all remaining threads by 1, to prevent them from \*(L"starving\*(R".
d660 1
a660 1
unit of the current process into a thread (the \*(L"main\*(R" thread). It
d669 1
a669 1
``\f(CWpth_exit(0);\fR'\*(R' in the main thread (which waits for all other threads to
d671 1
a671 1
``\f(CWpth_kill(); exit(0)\fR'\*(R' (which immediately kills the threading system and
d685 11
a695 8
\f(CWPTH_CTRL_GETTHREADS_NEW\fR for the number of threads in the new queue (threads
created via \fIpth_spawn\fR\|(3) but still not scheduled once),
\f(CWPTH_CTRL_GETTHREADS_READY\fR for the number of threads in the ready queue
(threads who want to do \s-1CPU\s0 bursts), \f(CWPTH_CTRL_GETTHREADS_RUNNING\fR for the
number of running threads (always just one thread!),
\f(CWPTH_CTRL_GETTHREADS_WAITING\fR for the number of threads in the waiting queue
(threads waiting for events), \f(CWPTH_CTRL_GETTHREADS_DEAD\fR for the number of
threads in the new queue (terminated threads waiting for a join).
d697 1
a697 1
This requires a second argument of type ``\f(CWfloat *\fR'\*(R' (pointer to a floating
d706 1
a706 1
This requires a second argument of type ``\f(CWpth_t\fR'\*(R' which identifies a
d710 1
a710 1
This requires a second argument of type ``\f(CWpth_t\fR'\*(R' which identifies a
d712 1
a712 1
\fIpth_ctrl\fR\|(3) should be casted to a ``\f(CWchar *\fR'\*(R'.
d714 1
a714 1
This requires a second argument of type ``\f(CWFILE *\fR'\*(R' to which a summary
d720 1
a720 1
This function returns a hex-value ``0x\fIV\fR\fI\s-1RR\s0\fR\fIT\fR\fI\s-1LL\s0\fR'\*(R' which describes the
d788 1
a788 1
\f(CWPTH_ATTR_PRIO\fR := \f(CWPTH_PRIO_STD\fR, \f(CWPTH_ATTR_NAME\fR := \*(L"\f(CWunknown\fR\*(R",
d810 1
a810 1
``\fIpth_exit\fR\|(\fIentry\fR(\fIarg\fR))'\*(R' inside the new thread unit, i.e., \fIentry\fR's
d823 1
a823 1
as ``\fIfunc\fR(\fIarg\fR)'\*(R' in the system. In other words: Only the first call to
d825 2
a826 2
\fIctrlvar\fR should be declared as ``\f(CWpth_once_t\fR \fIvariable-name\fR =
\f(CWPTH_ONCE_INIT\fR;'\*(R' before calling this function.
d852 1
a852 1
performed, i.e., ``\f(CWpth_raise(tid, 0)\fR'\*(R' returns \f(CWTRUE\fR when thread \fItid\fR
d908 1
a908 1
``\f(CWpth_exit(PTH_CANCELED)\fR'\*(R' at one of his cancellation points.  In \fBPth\fR
d913 1
a913 1
waits to be joined it just joins it (via ``\f(CWpth_join(\fR\fItid\fR\f(CW, NULL)\fR'') and
d916 1
a916 1
``\f(CWpth_cancel(\fR\fItid\fR\f(CW)\fR'\*(R'.
d984 1
a984 1
``\f(CWpth_exit(PTH_CANCELED)\fR'\*(R'.
d998 1
a998 1
``\f(CWpth_event(PTH_EVENT_FD|PTH_UNTIL_FD_READABLE, fd)\fR'\*(R'.
d1010 3
a1012 3
Example: ``\f(CWpth_event(PTH_EVENT_SELECT, &rc, nfd, rfds, wfds, efds)\fR'\*(R' where
\f(CWrc\fR has to be of type ``\f(CWint *\fR'\*(R', \f(CWnfd\fR has to be of type ``\f(CWint\fR'\*(R' and
\f(CWrfds\fR, \f(CWwfds\fR and \f(CWefds\fR have to be of type ``\f(CWfd_set *\fR'\*(R' (see
d1016 2
a1017 2
to a signal set (type ``\f(CWsigset_t *\fR'') and a pointer to a signal number
variable (type ``\f(CWint *\fR'').  This event waits until one of the signals in
d1022 2
a1023 2
your notice. Example: ``\f(CWsigemptyset(&set); sigaddset(&set, SIGINT);
pth_event(PTH_EVENT_SIG, &set, &sig);\fR'\*(R'.
d1031 1
a1031 1
``\f(CWpth_event(PTH_EVENT_TIME, pth_timeout(2,0))\fR'\*(R'.
d1035 1
a1035 1
on the specified message port.  Example: ``\f(CWpth_event(PTH_EVENT_MSG, mp)\fR'\*(R'.
d1041 1
a1041 1
``\f(CWpth_event(PTH_EVENT_TID|PTH_UNTIL_TID_DEAD, tid)\fR'\*(R'.
d1044 3
a1046 3
correspond to the arguments of the \fIwaitpid\fR\|(2) function: ``\f(CWpid_t\fR'\*(R', ``\f(CWint
*\fR'\*(R' and ``\f(CWint\fR'\*(R'.  This events waits until the process changed to the
specified state.  Example: ``\f(CWpth_event(PTH_EVENT_PID, pid, &status, 0)\fR'\*(R'.
d1049 1
a1049 1
given with the following types: ``\f(CWint (*)(void *)\fR'\*(R' and ``\f(CWvoid *\fR'\*(R'. The
d1054 1
a1054 1
Example: ``\f(CWpth_event(PTH_EVENT_FUNC, func, arg)\fR'\*(R'.
d1067 3
a1069 3
To make it clear, when you constructed \fIev\fR via ``\f(CWev =
pth_event(PTH_EVENT_FD, fd);\fR'\*(R' you have to extract it via
``\f(CWpth_event_extract(ev, &fd)\fR'\*(R', etc. For multiple arguments of an event the
d1187 3
a1189 3
This dynamically initializes a mutex variable of type ``\f(CWpth_mutex_t\fR'\*(R'.
Alternatively one can also use static initialization via ``\f(CWpth_mutex_t
mutex = PTH_MUTEX_INIT\fR'\*(R'.
d1204 2
a1205 2
``\f(CWpth_rwlock_t\fR'\*(R'.  Alternatively one can also use static initialization
via ``\f(CWpth_rwlock_t rwlock = PTH_RWLOCK_INIT\fR'\*(R'.
d1218 2
a1219 2
``\f(CWpth_cond_t\fR'\*(R'.  Alternatively one can also use static initialization via
``\f(CWpth_cond_t cond = PTH_COND_INIT\fR'\*(R'.
d1233 3
a1235 3
This dynamically initializes a barrier variable of type ``\f(CWpth_barrier_t\fR'\*(R'.
Alternatively one can also use static initialization via ``\f(CWpth_barrier_t
barrier = PTH_BARRIER_INIT(\fR\fIthreadhold\fR\f(CW)\fR'\*(R'.
d1247 2
a1248 2
\s-1API\s0, i.e., they are similar to the functions under \*(L"\fBStandard \s-1POSIX\s0
Replacement \s-1API\s0\fR\*(R" but all have an additional event argument which can be used
d1412 7
a1418 4
The following example is a useless server which does nothing more than
listening on a specified TCP port and displaying the current time to the
socket when a connection was established. For each incoming connection a
thread is spawned. The example contains \fIno\fR error checking and is \fIonly\fR
d1434 2
a1435 1
.Vb 5
d1450 2
a1451 1
.Vb 5
d1469 2
a1470 1
.Vb 9
d1792 1
a1792 1
to \fIread\fR\|(3) ``magically'\*(R' means \fIpth_read\fR\|(3). The problem here is that such
d1892 1
a1892 1
fix the problem and include a patch, made with ``\f(CWdiff -u3\fR'\*(R', in your
d1898 2
a1899 2
\fIpth-users-request@@gnu.org\fR with ``\f(CWsubscribe pth-users\fR'\*(R' (or
``\f(CWsubscribe pth-users\fR \fIaddress\fR'\*(R' if you want to subscribe
d1906 1
a1906 1
``comp.programming.threads Newsgroup Archive'\*(R',
d1910 1
a1910 1
``comp.programming.threads Frequently Asked Questions (F.A.Q.)'\*(R',
d1913 1
a1913 1
``\fIMultithreading \- Definitions and Guidelines\fR'\*(R',
d1917 1
a1917 1
``\fIThe Single \s-1UNIX\s0 Specification, Version 2 \- Threads\fR'\*(R',
d1930 1
a1930 1
``\fIPthreads Programming \- A \s-1POSIX\s0 Standard for Better Multiprocessing\fR'\*(R',
d1935 1
a1935 1
``\fIMultithreaded Programming with Pthreads\fR'\*(R',
d1940 1
a1940 1
``\fIThreads Primer \- A Guide To Multithreaded Programming\fR'\*(R',
d1945 1
a1945 1
``\fIThread Time \- The Multithreaded Programming Guide\fR'\*(R',
d1950 1
a1950 1
``\fIProgramming with \s-1POSIX\s0 Threads\fR'\*(R',
d1956 1
d1958 1
a1958 1
\fIsigprocmask\fR\|(2).  \fIsigsuspend\fR\|(2), \fIsigsetjmp\fR\|(3), \fIsiglongjmp\fR\|(3), \fIsetjmp\fR\|(3),
@


1.187
log
@*** empty log message ***
@
text
@d225 1
a225 1
pth_sfiodisc,
d314 1
a314 1
scheduler. The intention is, that this way both better portability and run-time
d323 2
a324 1
multithreaded applications.
d327 1
a327 1
regular jobs and one-shot requests have to processed in parallel.
d337 1
a337 1
of memory).
d343 1
a343 1
(one has to use atomic locks, etc). The machine's resources can be
d349 3
a351 3
load because of these resource problems. In practice, lot's of tricks
are usually used to overcome these problems (ranging from pre-forked
sub-process pools to semi-serialized processing, etc).
d353 1
a353 1
One the most elegant ways to solve these resource- and data-sharing
d359 1
a359 1
processes. Threads are neither the optimal runtime facility for all
d373 1
a373 1
descriptors\fR, \fIsignal table\fR. On every process switch, the kernel
d388 1
a388 1
called light-weight processes / \s-1LWP\s0).
d390 8
a397 7
User-space threads are usually more portable and can perform faster and
cheaper context switches (for instance via \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 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.
d399 11
a409 10
In preemptive scheduling the scheduler lets a thread execute until
a blocking situation occurres (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 software signal (like
\f(CWSIGALRM\fR or \f(CWSIGVTALRM\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 to the scheduler) or the thread explicitly yields control back
to the scheduler in a cooperative way.
d419 7
a425 6
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 \fBasync-safe\fR functions" 2
d427 30
a456 21
simultaneously by several threads. 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 behaves semantically
correct when executed by several threads. As you should recognize,
reentrant is a slightly stronger attribute than thread-safe, because it
is usually harder to achieve.
.Sp
Additionally there is a related attribute named \fIasynchronous-safe\fR which
comes into play in conjunction with signal handlers. This is very related to
the problem of \fIreentrant\fR functions. An \fIasynchronous safe\fR function is one
that can be called safe and without side-effects from within a signal handler
context. Usually very less functions are of this type. The problem
is that an application is very restricted in what it can perform
from within a signal handler, because only a few \s-1POSIX\s0 functions are
officially declared as and guaranteed to be async-safe.
d464 9
a472 8
execution units (each runs for no 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 the threads between
these jump-trails controlled by corresponding occurred events.
d474 1
a474 1
This approach gives the best possible performance because one can
d480 9
a488 9
The disadvantage of this approach is that it is complicated to write large
applications with this approach, because in those applications one quickly
gets \fIhundreds\fR\|(!) 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.
d496 5
a500 5
Actually in a preemptive way similar to what the kernel does for the
heavy-weight processes, i.e., every few milliseconds the 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.
d505 2
a506 2
Additionally the programming is very similar to a \fIfork\fR\|(2) based
approach.
d509 1
a509 1
compared to using approaches with heavy-weight processes, it is decreased
d514 2
a515 2
Finally there is no really portable \s-1POSIX/ANSI\s0\-C based way to implement
user-space preemptive threads. Either the platform already has threads,
d517 3
a519 2
even those semi-portable packages have to deal with assembler code and
other nasty internals and are not easy to port to forthcoming platforms.
d521 1
a521 1
So, in short: The matrix-dispatching approach is portable and fast, but
d538 1
a538 1
This is because it uses a nifty and portable \s-1POSIX/ANSI\s0\-C approach for
d542 1
a542 1
hand this way not all fancy threading features can be implemented.
d549 11
a559 9
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 \*(L"coroutines\*(R". 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 preemptive scheduling because of 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.
d565 5
a569 5
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 its the case for other threading
systems.
d577 4
a580 4
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 more important than
highest concurrency.
d582 4
a585 3
To understand the \fBPth\fR \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 graph:
d600 16
a615 15
scheduler.  On the next dispatching, 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 \*(L"starving\*(R".
.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 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 enters the \fB\s-1READY\s0\fR queue again.
d618 15
a632 14
\fB\s-1WAITING\s0\fR queue is checked for pending events. If one or more events of
a thread 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 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 for what
the \fB\s-1NEW\s0\fR queue is for. 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.
d634 1
a634 1
Finally there is a special separated queue named \fB\s-1SUSPENDED\s0\fR to where
d636 1
a636 1
queue by the application. The purpose of this special queue is to
d641 11
a651 5
from where it originally came.
.SH "APPLICATION PROGRAMMERS INTERFACE"
In the following the \fBPth\fR \fIApplication Programming Interface\fR (API) is
discussed in detail. With the knowledge given above it should be now easy to
understand how to program threads with this API.
d2010 1
a2010 1
.IX Item "\fBo\fR \fBreentrant\fR, \fBthread-safe\fR and \fBasync-safe\fR functions"
d2030 1
a2030 1
.IX Header "APPLICATION PROGRAMMERS INTERFACE"
@


1.186
log
@*** empty log message ***
@
text
@d297 8
@


1.185
log
@*** empty log message ***
@
text
@d299 1
a299 1
execution (aka `multithreading') inside event-driven applications. All threads
d626 2
a627 1
unit of the current process into a thread (the \*(L"main\*(R" thread).
d638 3
a640 3
terminates the process). The \fIpth_kill()\fR return immediately with a return code
of \f(CWFALSE\fR if it is called not from within the main thread. Else kills the
treading system and returns \f(CWTRUE\fR.
d680 2
d781 2
a782 1
keeps track of thread in dynamic data structures.
@


1.184
log
@*** empty log message ***
@
text
@d211 2
d570 2
a571 2
\&                     V
\&                   DEAD
d605 9
d791 13
d1501 1
a1501 1
provided by \fBPth\fR.  For this we establish the following three files:
d1581 1
a1581 1
compile. For this it is a convinient practice to include the required
d1656 1
a1656 1
Now we have to create the \f(CWpth/\fR subdirectory itself. For this we extract the
d1756 5
a1760 4
The drawback of this approach is just that really all source files of the
application where these function calls occur have to include \f(CWpth.h\fR, of
course. And this also means that this way existing libraries, including the
vendor's \fBstdio\fR usually will still block the whole process.
d1770 7
a1776 6
The drawback of this approach is that it depends on \fIsyscall\fR\|(2) and that
prototype conflicts can occur while building the wrapper functions due to
different function signatures in the vendor headers. 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(CWpth.h\fR and that existing libraries,
including the vendor's \fBstdio\fR, magically become thread-aware.
d1778 31
a1808 29
\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
\fIsigstack\fR\|(2) or \fIsigaltstack\fR\|(2) [see \f(CWpth_mctx.c\fR for details]. Any other code
is straight-forward POSIX and ANSI C based.
.PP
The context switching is done via POSIX [sig]\fIsetjmp\fR\|(3) and [sig]\fIlongjmp\fR\|(3).
Here all CPU registers, the program counter and the stack pointer are
switched. Additionally the \fBPth\fR dispatcher switches also the global Unix
\f(CWerrno\fR variable [see \f(CWpth_mctx.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
calculations and both the time and all I/O events are implemented via a single
\fIselect\fR\|(2) call [see \f(CWpth_sched.c\fR for details].
.PP
The thread control block management is done via 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(CWpth_tcb.h\fR and
\f(CWpth_pqueue.c\fR for details].
.PP
Most time critical sections (especially the dispatcher and event manager) are
speeded up by inlined functions (implemented as ANSI C pre-processor macros).
Additionally any debugging code is \fIcompletely\fR removed from the source when
not built with \f(CW-DPTH_DEBUG\fR (see Autoconf \f(CW--enable-debug\fR option), i.e.,
not only stub functions remain [see \f(CWpth_debug.h\fR for details].
d1811 9
a1819 9
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(CWlibc_r\fR of the platform vendor).  For an
asynchronous DNS resolver library use either the \f(CWlibresolv\fR from \fBBIND
8\fR ( see ftp://ftp.isc.org/isc/bind/ ) or the forthcoming GNU \fBadns\fR package
from Ian Jackson ( see http://www.gnu.org/software/adns/adns.html ).
d1821 21
a1841 18
The \fBPth\fR library was designed and implemented between February and July 1999
by \fIRalf S. Engelschall\fR after evaluating various (mostly preemptive) thread
libraries and 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 (providing better portability and performance) with an API
similar to the one found in POSIX thread libraries (providing easy
programming).
.PP
So the essential idea for the non-preemptive approach was taken over from
\fIPeter Simons\fR scheduler. The priority based scheduling algorithm was
contributed by \fIMartin Kraemer\fR. Some code inspiration also came from an old
threading library (\fBrsthreads\fR) written by \fIRobert S. Thau\fR for an ancient
internal test version of Apache. The concept and API of message ports was
borrowed from AmigaOS\*(R' \fBExec\fR. The concept and idea for the flexible event
mechanism came from \fIPaul Vixie\fR's \fBeventlib\fR (part of \fBBIND8\fR).
d1844 13
a1856 10
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(CWdiff -u3\fR'\*(R', in your report.
Always at least include a reasonable amount of description in your report to
allow the author to reproduce the bug.
.PP
For further support you additionally can subscribe yourself to the
\fIpth-users@@gnu.org\fR mailing list by sending a mail to
\fIpth-users-request@@gnu.org\fR with ``\f(CWsubscribe pth-users\fR'\*(R' in the body.
Then you can discuss your issues with other \fBPth\fR users by sending messages
to \fIpth-users@@gnu.org\fR.
d1888 5
d2063 4
@


1.183
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "26-Jan-2000" "GNU Pth 1.3b1" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.3b1 (26-Jan-2000)
@


1.182
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "24-Jan-2000" "GNU Pth 1.3a6" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.3a6 (24-Jan-2000)
@


1.181
log
@*** empty log message ***
@
text
@d298 2
a299 2
runs in the same address space of the application process, but each thread has
its own individual program-counter, run-time stack, signal mask and errno
d311 2
a312 2
Additionally \fBPth\fR provides an optional emulation API for POSIX.1c threads
("pthreads") which can be used for backward compatibility to existing
d315 37
a351 35
When programming event driven applications, usually servers, lots of regular
jobs and one-shot requests have to processed in parallel. To achieve this in
an efficient way on uniprocessor machines the idea of multitasking is
implemented by the operating system which can be used by the applications to
spawn multiple instances of itself. On Unix the kernel classically implements
multitasking in a preemptive and priority-based way through heavy-weight
processes spawned with \fIfork\fR\|(2). These processes do usually \fInot\fR share a
common address space. Instead they are clearly separated from each other and
were 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 memory).
.PP
The drawbacks are obvious: Sharing data between the processes is complicated
and can usually only solved in an efficient way 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 atomic locks,
etc). The machine resources can be exhausted very quickly when the server
application has to serve too much longer running requests (heavy-weight
processes cost memory). Additionally when for each request a sub-process is
spawned to handle it, the server performance and responsiveness is horrible
(heavy-weight processes cost time to spawn).  And finally the server
application doesn't scale very well with the load because of these resource
problems. Lot's of tricks are usually done in practice to overcome these
problems (ranging from pre-forked sub-process pools to semi-serialized
processing, etc).
.PP
One 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 especially require
less system resources. Threads neither are the optimal runtime facility for
all types of applications nor can all applications gain from them. But at
least event driven server applications usually benefit greatly from using
threads.
d353 5
a357 5
Lots of documents exists which describe and define the world of threading. To
understand \fBPth\fR only the basic knowledge about threading is actually
required. The following definitions of thread related terms should at least
help you in understanding the programming context of threads in order to allow
you to use \fBPth\fR.
d359 9
a367 8
A process on Unix systems consist 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 descriptors\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
only of a private program counter, stack memory, stack pointer and signal
table. All other ingredients, especially the virtual memory, it shares with
the other threads of the same process.
d369 9
a377 8
Threads on a Unix platform classically 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 notice by the
application. When threads are implemented in user space, the thread context
switches are performed by an application library without notice by the kernel.
Additionally there exist also 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 / \s-1LWP\s0).
d379 7
a385 7
User space threads are usually more portable and can perform faster and
cheaper context switches (for instance via \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 I/O blocking problems. Kernel-space
threads are usually always scheduled in preemptive way side-by-side with the
underlaying processes. User-space threads on the other hand use either
preemptive or non-preemptive scheduling.
d392 1
a392 1
\f(CWSIGALRM\fR or \f(CWSIGVTALRM\fR). In non-preemptive scheduling once a thread
d397 3
a399 3
.Ip "\fBo\fR \fBconcurrency\fR vs. \fBparalleism\fR" 2
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
d401 4
a404 3
machines, of course. But one also usually speaks of parallelism or \fIhigh
concurreny\fR in the context of preemptive thread scheduling and of \fIlow
concurreny\fR in the context of non-preemptive thread scheduling.
d413 4
a416 4
simultaneously by several threads. Functions that access global state, like
memory or files, have inherently reentrant problems, of course. Two classical
approaches to solve these problems are caller-supplied states and
thread-specific data.
d418 7
a424 6
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 behaves logically correct when executed by several
threads. As you should recognize, reentrant is a stronger attribute than
thread-safe.
d430 7
a436 7
context. Usually very less functions are of this type. The problem is that an
application is very restricted in what it can perform from within a signal
handler, because only a few \s-1POSIX\s0 functions are officially declared as and
guarrantied to be async-safe.
.Sh "User-Land Threads"
User-land threads can be implemented in various way. The two classical
approaches are:
d441 8
a448 8
execution units (each has to run maximal a few milliseconds) and those units
are implemented by separate program functions. Then a global matrix is created
which describes the execution (and perhaps even dependency) order of these
functions. The main server procedure then does just dispatching between these
units by calling one function after each other controlled by this matrix.  The
treads are created by more than one jump-trail through this matrix and by
switching between these jump-trails controlled by corresponding occurred
events.
d450 5
a454 5
The advantage of this approach is that the performance is really as maximal as
possible (because one can fine-tune the threads of execution by adjusting the
matrix and the scheduling is done explicitly by the application itself).
Additionally this is very portable, because the matrix is just an ordinary
data structure and functions are a standard feature of \s-1ANSI\s0 C.
d457 8
a464 7
applications with this approach, because in those applications one quickly get
\fIhundreds\fR\|(!) 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. The scheduling borders are function borders.
d466 1
a466 1
\fBContext-based based implicit scheduling between threads of execution:\fR
d468 9
a476 8
Here the idea is that one programs the application as with \fIfork\fR\|(2)'ed
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 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.
d478 5
a482 4
The advantage of this approach is that it's usually 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 \fIfork\fR\|(2)'ed approach.
d487 1
a487 1
scheduling does usually a lot more context switches (every user-land context
d491 9
a499 8
user-space preemptive threads. 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 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.
d501 9
a509 10
But why not combine the good aspects of both discussed approaches while trying
to avoid their bad aspects? That's the general intention and goal of \fBPth\fR.
In detail this means that \fBPth\fR implements the easy to program threads of
execution but in a way which doesn't have the portability side-effects of
preemptive scheduling. This means that instead a non-preemptive scheduling is
used.
.PP
This sounds and is an interesting 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:
d513 4
a516 4
The reasons are mainly because it uses a nifty and portable \s-1POSIX/ANSI\s0\-C
approach for thread creation (and this way doesn't require any platform
dependent assembler hacks) and schedules the threads in non-preemptive way
(which doesn't require unportable facilities like \f(CWSIGVTALRM\fR).  On the other
d521 2
a522 2
\fBPth increases the responsiveness and concurrency of an event driven
application, but \s-1NOT\s0 the concurrency of number crunching applications\fR.
d524 1
a524 1
The reason is the non-preemptive scheduling. Number crunching applications
d547 7
a553 6
This means that \fBPth\fR runs on mostly all types of Unix kernels, because the
kernel does not even recognize the \fBPth\fR threads (because they are
implemented entirely in user-space).  On the other hand, it cannot benefit
from the existance of multiprocessors, because for this kernel support would
be needed. Practice this is no problem because multiprocessor systems are rare
and portability is more important than highest concurrency.
d555 3
a557 3
To better understand the \fBPth\fR \s-1API\s0 it is reasonable to first understand the
life cycle of a thread in the \fBPth\fR threading system. It can be illustrated
with the following graph:
d563 1
a563 1
\&      +---> READY----+
d572 1
a572 1
scheduler.  On the next dispatching the scheduler picks it up from there and
d574 4
a577 4
want to perform a \s-1CPU\s0 burst. There they are queued in priority order.  Per
dispatching step, the scheduler always removes the thread with the highest
priority only. The assigned queue priority for all remaining threads every
time is increased by 1 to prevent thread starvation.
d588 15
a602 11
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. When one or more events of a thread
occured, it is immediately moved to the \fB\s-1READY\s0\fR queue, too.
.PP
The purpose of the \fB\s-1NEW\s0\fR queue has to do with the fact that a thread never
directly switches to another thread. A thread always yields execution to the
scheduler and the scheduler dispatches to the next thread. 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 is remains until
another thread joins it.
d605 1
a605 1
disscussed in detail. With the knowledge given above it should be now easy to
d608 1
a608 1
The following functions act on a global library basis.  They are used to
d611 5
a615 5
This initializes the \fBPth\fR library. It has to be really 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 \*(L"main\*(R" thread).
d619 1
a619 1
the main function of the application. At least it has to be called from within
d621 1
a621 1
calling thread into the single execution unit of the underlaying process.  The
d629 1
a629 1
.Ip "long \fBpth_ctrl\fR(unsigned lont \fIquery\fR, ...);" 4
d784 1
a784 1
signal to a thread and its guarranties that only this thread gets the signal
d806 1
a806 1
\fIready\fR thread, it is guarrantied that this thread receives execution control
d817 1
a817 1
a resolution of one microsecond. In pratice you should neither rely on this
d819 1
a819 1
only guarranties that the thread will sleep at least \fInaptime\fR. But because
d827 1
a827 1
the various \fIpth_event_xxx()\fR functions). It's modelled like \fIselect\fR\|(2), i.e., one
d830 1
a830 1
when one ore more of them occurred after tagging them as occured. The \fIev\fR
d832 2
a833 2
tagging. \fIpth_wait\fR\|(3) returns the number of occured events and the application
can use \fIpth_event_occurred\fR\|(3) to test which events occured.
d839 1
a839 1
performed. When its \f(CWPTH_CANCEL_DEFERRED\fR again the calcellation request is
d841 1
a841 1
immediately cancelled before \fIpth_cancel\fR\|(3) returns. The effect of a thread
d847 1
a847 1
This is the crual way to cancel a thread \fItid\fR. When it's already dead and
d855 1
a855 1
awakend and stores the value of \fItid\fR's \fIpth_exit\fR\|(3) call into \fIvalue\fR and
d869 1
a869 1
This switches the non-blocking mode flag on filedescriptor \fIfd\fR.  The
d875 1
a875 1
longer a requirement to manually switch a filedescriptor into non-blocking
d877 1
a877 1
Instead when you now switch a filedescriptor explicitly into non-blocking
d889 1
a889 1
This functions is always available, but only reasonably useable when \fBPth\fR
d929 1
a929 1
This is a filedescriptor event. One or more of \f(CWPTH_UNTIL_FD_READABLE\fR,
d931 2
a932 2
\fIspec\fR to specify on which state of the filedescriptor you want to wait.  The
filedescriptor itself has to be given as an additional argument.  Example:
d935 1
a935 1
This is a multiple filedescriptor event modeled directly after the \fIselect\fR\|(2)
d937 4
a940 4
convinient way to wait for a large set of filedescriptors at once and at each
filedescriptor for a different type of state. Additionally as a nice
side-effect one receives the number of filedescriptors which causes the event
to be occurred (using \s-1BSD\s0 semantics, i.e., when a filedescriptor occurred in
d948 1
a948 1
\fIselect\fR\|(2)). The number of occurred filedescriptors are stored in \f(CWrc\fR.
d995 1
a995 1
When \fIpth_event\fR\|(3) is threated like \fIsprintf\fR\|(3), then this function is
d1035 1
a1035 1
similar to the \s-1POSIX\s0 pthread \s-1API\s0. Use this for thread specific global data.
d1129 1
a1129 1
\f(CWNULL\fR).  Recursive locking is explicity supported, i.e., a thread is allowed
d1242 1
a1242 1
the whole process in case the filedescriptors will block.
d1246 1
a1246 1
elapsed.  The thread is guarrantied to not awakened before this time, but
d1254 1
a1254 1
thread is guarrantied to not awakened before this time, but because of the
d1276 1
a1276 1
signal handler. Instead it's catched by the scheduler only in order to awake
d1310 1
a1310 1
bytes into \fIbuf\fR from filedescriptor \fIfd\fR.  The difference between \fIread\fR\|(2)
d1312 1
a1312 1
thread until the filedescriptor is ready for reading. For more details about
d1316 1
a1316 1
filedescriptor \fIfd\fR into the first \fIiovcnt\fR rows of the \fIiov\fR vector.  The
d1318 1
a1318 1
suspends execution of the current thread until the filedescriptor is ready for
d1323 1
a1323 1
from \fIbuf\fR to filedescriptor \fIfd\fR.  The difference between \fIwrite\fR\|(2) and
d1325 1
a1325 1
thread until the filedescriptor is ready for writing.  For more details about
d1329 1
a1329 1
filedescriptor \fIfd\fR from the first \fIiovcnt\fR rows of the \fIiov\fR vector.  The
d1331 1
a1331 1
suspends execution of the current thread until the filedescriptor is ready for
d1720 1
a1720 1
third-party stuff) this can be inconvinient.  Here it's required that a call
d1929 1
a1929 1
.IX Item "\fBo\fR \fBconcurrency\fR vs. \fBparalleism\fR"
d1935 1
a1935 1
.IX Subsection "User-Land Threads"
d1961 1
a1961 1
.IX Item "long \fBpth_ctrl\fR(unsigned lont \fIquery\fR, ...);"
@


1.180
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "15-Jan-2000" "GNU Pth 1.3a5" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.3a5 (15-Jan-2000)
@


1.179
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "08-Jan-2000" "GNU Pth 1.3a4" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.3a4 (08-Jan-2000)
@


1.178
log
@*** empty log message ***
@
text
@d1417 1
a1417 1
.Vb 6
d1420 1
@


1.177
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "08-Jan-2000" "GNU Pth 1.3a3" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.3a3 (08-Jan-2000)
@


1.176
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "03-Jan-2000" "GNU Pth 1.3a3" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.3a3 (03-Jan-2000)
@


1.175
log
@*** empty log message ***
@
text
@d650 4
d1955 2
@


1.174
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "30-Dec-1999" "GNU Pth 1.3a2" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.3a2 (30-Dec-1999)
@


1.173
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "09-Nov-1999" "GNU Pth 1.3a2" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.3a2 (09-Nov-1999)
@


1.172
log
@*** empty log message ***
@
text
@d602 1
a602 1
.Ip "void \fBpth_kill\fR(void);" 4
d605 10
a614 3
the main function of the application. It implicitly kills all threads and
transforms back the calling thread into the single execution unit of the
underlaying process.
d1940 1
a1940 1
.IX Item "void \fBpth_kill\fR(void);"
@


1.171
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "09-Nov-1999" "GNU Pth 1.3a1" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.3a1 (09-Nov-1999)
d250 1
a250 1
pth_cleanup_push, 
d339 1
a339 1
processing, etc). 
d411 1
a411 1
thread-specific data. 
d427 1
a427 1
guarrantied to be async-safe.  
d432 1
a432 1
\fBMatrix-based explicit dispatching between small units of execution:\fR 
d442 1
a442 1
events. 
d459 1
a459 1
\fBContext-based based implicit scheduling between threads of execution:\fR 
d496 1
a496 1
used. 
d501 2
a502 2
.Ip "\fBo\fR " 2
\fBPth provides maximum portability, but \s-1NOT\s0 the fanciest features\fR. 
d511 1
a511 1
.Ip "\fBo\fR " 2
d513 1
a513 1
application, but \s-1NOT\s0 the concurrency of number crunching applications\fR. 
d524 2
a525 2
.Ip "\fBo\fR " 2
\fBPth requires thread-safe functions, but \s-1NOT\s0 reentrant functions\fR. 
d534 1
a534 1
.Ip "\fBo\fR " 2
d536 1
a536 1
benefit from multiprocessor machines\fR. 
d576 1
a576 1
\s-1CPU\s0 bursts and enters the \fB\s-1READY\s0\fR queue again. 
d601 1
a601 1
current process into a thread (the \*(L"main\*(R" thread). 
d773 1
a773 1
bursts into smaller units with this call. 
d899 1
a899 1
.Ip "pth_event_t \fBpth_event\fR(unsigned long \fIspec\fR, ...); " 4
d918 1
a918 1
timeouts already can be handled via \f(CWPTH_EVENT_TIME\fR events). 
d1089 1
a1089 1
mutex to protect it, of course. 
d1095 1
a1095 1
the event mechanism. 
d1225 1
a1225 1
the whole process. 
d1233 1
a1233 1
whole process. 
d1314 1
a1314 1
desired position inside the file. 
d1320 1
a1320 1
desired position inside the file. 
d1328 1
a1328 1
.Vb 75
d1340 2
a1341 1
\& 
d1347 2
a1348 1
\& 
d1355 2
a1356 1
\& 
d1362 2
a1363 1
\& 
d1373 3
a1375 2
\& 
\& int main(int argc, char *argv[]) 
d1384 2
a1385 1
\& 
d1389 2
a1390 1
\& 
d1396 2
a1397 1
\& 
d1405 2
a1406 1
\& 
d1429 1
a1429 1
\& | 
d1463 1
a1463 1
\& | 
d1704 1
a1704 1
\fIaccept\fR\|(2), \fIread\fR\|(2), \fIwrite\fR\|(2).  
d1717 1
a1717 1
\fIaccept\fR\|(2), \fIread\fR\|(2), \fIwrite\fR\|(2). 
d1730 1
a1730 1
is straight-forward POSIX and ANSI C based. 
d1771 1
a1771 1
based) non-preemptive \*(C+ scheduler class written by \fIPeter Simons\fR. 
d1776 1
a1776 1
programming). 
d1818 1
a1818 1
Bibliography on threads and multithreading, 
d1823 2
a1824 2
``\fIPthreads Programming \- A \s-1POSIX\s0 Standard for Better Multiprocessing\fR'\*(R', 
O'Reilly 1996; 
d1828 2
a1829 2
``\fIThreads Primer \- A Guide To Multithreaded Programming\fR'\*(R', 
Prentice Hall 1996; 
d1917 1
a1917 1
.IX Item "\fBo\fR "
d1919 1
a1919 1
.IX Item "\fBo\fR "
d1921 1
a1921 1
.IX Item "\fBo\fR "
d1923 1
a1923 1
.IX Item "\fBo\fR "
d2031 1
a2031 1
.IX Item "pth_event_t \fBpth_event\fR(unsigned long \fIspec\fR, ...); "
@


1.170
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "01-Nov-1999" "GNU Pth 1.3a1" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.3a1 (01-Nov-1999)
d1405 274
d2171 8
@


1.169
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "31-Oct-1999" "GNU Pth 1.2.0" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.2.0 (31-Oct-1999)
@


1.169.2.1
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "09-Nov-1999" "GNU Pth 1.2.1" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.2.1 (09-Nov-1999)
@


1.169.2.2
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "14-Nov-1999" "GNU Pth 1.2.1" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.2.1 (14-Nov-1999)
@


1.169.2.3
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "07-Jan-2000" "GNU Pth 1.2.2" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.2.2 (07-Jan-2000)
@


1.169.2.4
log
@*** empty log message ***
@
text
@d605 3
a607 10
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 underlaying process.  The
usual way to terminate a \fBPth\fR application is either a simple
``\f(CWpth_exit(0);\fR'\*(R' in the main thread (which waits for all other threads to
terminate, kills the threading system and then terminates the process) or a
``\f(CWpth_kill(); exit(0)\fR'\*(R' (which immediately kills the threading system and
terminates the process). The \fIpth_kill()\fR return immediately with a return code
of \f(CWFALSE\fR if it is called not from within the main thread. Else kills the
treading system and returns \f(CWTRUE\fR.
@


1.169.2.5
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "08-Jan-2000" "GNU Pth 1.2.2" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.2.2 (08-Jan-2000)
@


1.169.2.6
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "04-Feb-2000" "GNU Pth 1.2.3" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.2.3 (04-Feb-2000)
d1335 1
a1335 1
.Vb 76
a1406 1
\&         peer_len = sizeof(peer_addr);
@


1.169.2.7
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "11-Feb-2000" "GNU Pth 1.2.4" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.2.4 (11-Feb-2000)
@


1.168
log
@*** empty log message ***
@
text
@d297 3
a299 3
execution ("multithreading") inside even driven applications. All threads runs
in the same address space of the application process, but each thread has its
own individual program-counter, run-time stack, signal mask and errno
d302 1
a302 1
The thread scheduling itself is done in a cooperative way, i.e. the threads
d304 1
a304 1
scheduler. The intention is that this way both better portability and run-time
d343 1
a343 1
(heavy-weight) process, i.e. to use \fImultithreading\fR.  Those \fIthreads\fR
d413 1
a413 1
Thread-safety is the avoidance of \fIdata races\fR, i.e. situations in which data
d462 1
a462 1
processes, i.e. one spawns a thread of execution and this runs from the begin
d465 1
a465 1
way similar to what the kernel does for the heavy-weight processes, i.e. every
d615 1
a615 1
particular state, i.e. the \f(CWPTH_CTRL_GETTHREADS\fR query is equal to the
d641 1
a641 1
thread. It returns the name of the given thread, i.e. the return value of
d667 1
a667 1
The thread cancellation state, i.e.  a combination of \f(CWPTH_CANCEL_ENABLE\fR or
d691 1
a691 1
The scheduling state of the thread, i.e. either \f(CWPTH_STATE_NEW\fR,
d734 1
a734 1
``\fIpth_exit\fR\|(\fIentry\fR(\fIarg\fR))'\*(R' inside the new thread unit, i.e. \fIentry\fR's
d762 1
a762 1
performed, i.e.  ``\f(CWpth_raise(tid, 0)\fR'\*(R' returns \f(CWTRUE\fR when thread \fItid\fR
d772 1
a772 1
times the threads should be cooperative, i.e. when they should split their \s-1CPU\s0
d782 1
a782 1
on the next dispatching step. If \fItid\fR is in a different state (i.e.  still
d802 1
a802 1
the various \fIpth_event_xxx()\fR functions). It's modelled like \fIselect\fR\|(2), i.e. one
d832 1
a832 1
with \f(CWPTH_FLAG_NOJOIN\fR. A thread can only be joined once, i.e.  after the
d888 1
a888 1
\f(CWPTH_CANCEL_ASYNCHRONOUS\fR for allowing asynchronous cancellations, i.e.
d915 1
a915 1
to be occurred (using \s-1BSD\s0 semantics, i.e. when a filedescriptor occurred in
d971 1
a971 1
\fIsscanf\fR\|(3), i.e. it is the inverse operation of \fIpth_event\fR\|(3). This means that
d1068 2
a1069 2
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.
d1076 1
a1076 1
is forked into a separate process, i.e. in the parent process nothing changes
d1104 1
a1104 1
\f(CWNULL\fR).  Recursive locking is explicity supported, i.e. a thread is allowed
d1157 1
a1157 1
\s-1API\s0, i.e. they are similar to the functions under \*(L"\fBStandard \s-1POSIX\s0
d1456 1
a1456 1
The \fBPth\fR event manager is mainly \fIselect\fR\|(2) and \fIgettimeofday\fR\|(2) based, i.e.
d1470 1
a1470 1
not built with \f(CW-DPTH_DEBUG\fR (see Autoconf \f(CW--enable-debug\fR option), i.e.
@


1.167
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "26-Oct-1999" "GNU Pth 1.2b8" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.2b8 (26-Oct-1999)
@


1.166
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "26-Oct-1999" "GNU Pth 1.2.0" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.2.0 (26-Oct-1999)
@


1.165
log
@*** empty log message ***
@
text
@d298 1
a298 1
in the same address space of the application process, but each thread has it's
@


1.164
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "26-Oct-1999" "GNU Pth 1.2b8" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.2b8 (26-Oct-1999)
@


1.163
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "22-Oct-1999" "GNU Pth 1.2b7" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.2b7 (22-Oct-1999)
@


1.162
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "19-Oct-1999" "GNU Pth 1.2b7" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.2b7 (19-Oct-1999)
@


1.161
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "28-Sep-1999" "GNU Pth 1.2b6" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.2b6 (28-Sep-1999)
@


1.160
log
@*** empty log message ***
@
text
@d590 1
a590 1
In the following the \fBPth\fR \fIApplication Programmers Interface\fR (API) is
@


1.159
log
@*** empty log message ***
@
text
@d318 1
a318 1
implemented by the operation system which can be used by the applications to
d1502 1
a1502 1
.SH "BUG REPORTS"
d1508 6
d1910 1
a1910 1
.IX Header "BUG REPORTS"
@


1.158
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "25-Sep-1999" "GNU Pth 1.2b6" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.2b6 (25-Sep-1999)
@


1.157
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "21-Sep-1999" "GNU Pth 1.2b5" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.2b5 (21-Sep-1999)
@


1.156
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "17-Sep-1999" "GNU Pth 1.2b4" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.2b4 (17-Sep-1999)
d659 1
a659 1
.Ip "\f(CWPTH_ATTR_NAME\fR (read-write) [\fBchar *\fR]" 4
d731 8
a738 7
\f(CWPTH_ATTR_DEFAULT\fR for default attributes) with the starting point at routine
\fIentry\fR. This entry routine is called as ``\fIpth_exit\fR\|(\fIentry\fR(\fIarg\fR))'\*(R'
inside the new thread unit, i.e. \fIentry\fR's return value is fed to an implicit
\fIpth_exit\fR\|(3). So the thread usually can exit by just returning. Nevertheless
the thread can also exit explicitly at any time by calling \fIpth_exit\fR\|(3). But
keep in mind that calling the \s-1POSIX\s0 function \fIexit\fR\|(3) still terminates the
complete process and not just the current thread.
d1662 1
a1662 1
.IX Item "\f(CWPTH_ATTR_NAME\fR (read-write) [\fBchar *\fR]"
@


1.155
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "17-Sep-1999" "GNU Pth 1.2b3" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.2b3 (17-Sep-1999)
@


1.154
log
@*** empty log message ***
@
text
@d1165 1
a1165 1
.Ip "int \fBpth_connect_ev\fR(int \fIs\fR, const struct sockaddr *\fIaddr\fR, int \fIaddrlen\fR, pth_event_t \fIev\fR);" 4
d1171 1
a1171 1
.Ip "int \fBpth_accept_ev\fR(int \fIs\fR, struct sockaddr *\fIaddr\fR, int *\fIaddrlen\fR, pth_event_t \fIev\fR);" 4
d1255 1
a1255 1
.Ip "int \fBpth_connect\fR(int \fIs\fR, const struct sockaddr *\fIaddr\fR, int \fIaddrlen\fR);" 4
d1262 1
a1262 1
.Ip "int \fBpth_accept\fR(int \fIs\fR, struct sockaddr *\fIaddr\fR, int *\fIaddrlen\fR);" 4
d1841 1
a1841 1
.IX Item "int \fBpth_connect_ev\fR(int \fIs\fR, const struct sockaddr *\fIaddr\fR, int \fIaddrlen\fR, pth_event_t \fIev\fR);"
d1843 1
a1843 1
.IX Item "int \fBpth_accept_ev\fR(int \fIs\fR, struct sockaddr *\fIaddr\fR, int *\fIaddrlen\fR, pth_event_t \fIev\fR);"
d1869 1
a1869 1
.IX Item "int \fBpth_connect\fR(int \fIs\fR, const struct sockaddr *\fIaddr\fR, int \fIaddrlen\fR);"
d1871 1
a1871 1
.IX Item "int \fBpth_accept\fR(int \fIs\fR, struct sockaddr *\fIaddr\fR, int *\fIaddrlen\fR);"
@


1.153
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "05-Sep-1999" "GNU Pth 1.2b3" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.2b3 (05-Sep-1999)
@


1.152
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "04-Sep-1999" "GNU Pth 1.2b2" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.2b2 (04-Sep-1999)
@


1.151
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "02-Sep-1999" "GNU Pth 1.2b2" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.2b2 (02-Sep-1999)
@


1.150
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "02-Sep-1999" "GNU Pth 1.2b1" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.2b1 (02-Sep-1999)
@


1.149
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "31-Aug-1999" "GNU Pth 1.2b1" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.2b1 (31-Aug-1999)
@


1.148
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "30-Aug-1999" "GNU Pth 1.1.4" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.1.4 (30-Aug-1999)
@


1.148.2.1
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "01-Sep-1999" "GNU Pth 1.1.5" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.1.5 (01-Sep-1999)
@


1.148.2.2
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "02-Sep-1999" "GNU Pth 1.1.5" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.1.5 (02-Sep-1999)
@


1.148.2.3
log
@*** empty log message ***
@
text
@d659 1
a659 1
.Ip "\f(CWPTH_ATTR_NAME\fR (read-write) [\f(CWchar *\fR]" 4
d731 7
a737 8
\f(CWPTH_ATTR_DEFAULT\fR for default attributes \- which means that thread priority,
joinability and cancel state are inherited from the current thread) with the
starting point at routine \fIentry\fR. This entry routine is called as
``\fIpth_exit\fR\|(\fIentry\fR(\fIarg\fR))'\*(R' inside the new thread unit, i.e. \fIentry\fR's
return value is fed to an implicit \fIpth_exit\fR\|(3). So the thread usually can exit
by just returning. Nevertheless the thread can also exit explicitly at any
time by calling \fIpth_exit\fR\|(3). But keep in mind that calling the \s-1POSIX\s0 function
\fIexit\fR\|(3) still terminates the complete process and not just the current thread.
d1661 1
a1661 1
.IX Item "\f(CWPTH_ATTR_NAME\fR (read-write) [\f(CWchar *\fR]"
@


1.148.2.4
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "25-Sep-1999" "GNU Pth 1.1.6" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.1.6 (25-Sep-1999)
@


1.148.2.5
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "28-Sep-1999" "GNU Pth 1.1.6" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.1.6 (28-Sep-1999)
@


1.147
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "27-Aug-1999" "GNU Pth 1.1.4" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.1.4 (27-Aug-1999)
@


1.146
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "27-Aug-1999" "GNU Pth 1.1.3" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.1.3 (27-Aug-1999)
@


1.145
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "23-Aug-1999" "GNU Pth 1.1.3" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.1.3 (23-Aug-1999)
@


1.144
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "23-Aug-1999" "GNU Pth 1.1.2" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.1.2 (23-Aug-1999)
@


1.143
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "21-Aug-1999" "GNU Pth 1.1.2" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.1.2 (21-Aug-1999)
d763 25
a787 10
.Ip "void \fBpth_yield\fR(void);" 4
This explicitly yields back the execution to the scheduler thread.  Usually
the execution is 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 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.
d1709 1
a1709 1
.IX Item "void \fBpth_yield\fR(void);"
@


1.142
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "21-Aug-1999" "GNU Pth 1.1.1" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.1.1 (21-Aug-1999)
@


1.141
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "20-Aug-1999" "GNU Pth 1.1.1" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.1.1 (20-Aug-1999)
@


1.140
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "19-Aug-1999" "GNU Pth 1.1.0" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.1.0 (19-Aug-1999)
@


1.139
log
@*** empty log message ***
@
text
@d1512 4
@


1.138
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "19-Aug-1999" "GNU Pth 1.1b8" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.1b8 (19-Aug-1999)
@


1.137
log
@*** empty log message ***
@
text
@d857 2
a858 1
structure when it is no longer needed.
@


1.136
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "18-Aug-1999" "GNU Pth 1.1b7" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.1b7 (18-Aug-1999)
@


1.135
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "17-Aug-1999" "GNU Pth 1.1b6" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.1b6 (17-Aug-1999)
@


1.134
log
@*** empty log message ***
@
text
@d1311 1
a1311 1
.Vb 73
d1341 1
d1348 2
a1349 1
\&         printf("ticker: time: %s, average load: %.2f\en", ct, pth_load());
@


1.133
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "17-Aug-1999" "GNU Pth 1.1b5" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.1b5 (17-Aug-1999)
@


1.132
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "13-Aug-1999" "GNU Pth 1.1b5" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.1b5 (13-Aug-1999)
@


1.131
log
@*** empty log message ***
@
text
@d1091 1
a1091 1
returns \f(CWFALSE\fR with \f(CWerrno\fR set to \f(CWEAGAIN\fR.
d1106 1
a1106 1
execution. Instead it returns \f(CWFALSE\fR with \f(CWerrno\fR set to \f(CWEAGAIN\fR.
@


1.130
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "13-Aug-1999" "GNU Pth 1.1b4" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.1b4 (13-Aug-1999)
@


1.129
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "11-Aug-1999" "GNU Pth 1.1b3" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.1b3 (11-Aug-1999)
@


1.128
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "11-Aug-1999" "GNU Pth 1.1.0" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.1.0 (11-Aug-1999)
@


1.127
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "11-Aug-1999" "GNU Pth 1.1b3" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.1b3 (11-Aug-1999)
@


1.126
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "10-Aug-1999" "GNU Pth 1.1b2" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.1b2 (10-Aug-1999)
@


1.125
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "07-Aug-1999" "GNU Pth 1.1b2" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.1b2 (07-Aug-1999)
@


1.124
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "07-Aug-1999" "GNU Pth 1.1b1" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.1b1 (07-Aug-1999)
@


1.123
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "03-Aug-1999" "GNU Pth 1.1b1" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.1b1 (03-Aug-1999)
@


1.122
log
@*** empty log message ***
@
text
@d222 2
a223 1
pth_timeout.
d833 1
a833 1
\f(CWPTH_FDMODE_ERROR\fR on error. Keep in mind that since Pth 1.1 there is no
d835 1
a835 1
mode in order to use it. This is automatically done temporarily inside Pth.
d847 11
d1708 2
@


1.121
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "03-Aug-1999" "GNU Pth 1.0.4" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.0.4 (03-Aug-1999)
@


1.120
log
@*** empty log message ***
@
text
@d264 3
a266 1
pth_cond_notify.
d1055 6
a1060 5
locks (mutex), read-write locks (rwlock) and condition variables (cond). 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. 
d1066 1
a1066 1
the event mechanism.
d1113 13
d1796 4
@


1.119
log
@*** empty log message ***
@
text
@d220 1
a220 1
pth_nonblocking,
d824 11
a834 3
.Ip "int \fBpth_nonblocking\fR(int \fIfd\fR);" 4
This switches filedescriptor \fIfd\fR into non-blocking mode which is a
prerequisite to use it together with the \fBPth\fR library.
d1283 1
a1283 1
.Vb 75
a1301 1
\&     pth_nonblocking(fd);
a1344 1
\&     pth_nonblocking(sa);
d1675 1
a1675 1
.IX Item "int \fBpth_nonblocking\fR(int \fIfd\fR);"
@


1.119.2.1
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "10-Aug-1999" "GNU Pth 1.0.5" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.0.5 (10-Aug-1999)
@


1.119.2.2
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "17-Aug-1999" "GNU Pth 1.0.6" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.0.6 (17-Aug-1999)
d1068 1
a1068 1
returns \f(CWFALSE\fR with \f(CWerrno\fR set to \f(CWEBUSY\fR.
d1083 1
a1083 1
execution. Instead it returns \f(CWFALSE\fR with \f(CWerrno\fR set to \f(CWEBUSY\fR.
@


1.118
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "01-Aug-1999" "GNU Pth 1.0.4" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.0.4 (01-Aug-1999)
@


1.117
log
@*** empty log message ***
@
text
@d1331 1
a1331 1
\&     pth_attr_set(attr, PTH_ATTR_NAME, "ticker")
d1345 1
a1345 1
\&     pth_attr_set(attr, PTH_ATTR_NAME, "handler")
@


1.116
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "30-Jul-1999" "GNU Pth 1.0.4" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.0.4 (30-Jul-1999)
@


1.115
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "30-Jul-1999" "GNU Pth 1.0.3" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.0.3 (30-Jul-1999)
@


1.114
log
@*** empty log message ***
@
text
@d728 1
a728 1
\f(CWPTH_ATTR_NONE\fR for no attributes) with the starting point at routine
d781 1
a781 1
.Ip "int \fBpth_wait\fR(pth_event_t *\fIev\fR);" 4
d1657 1
a1657 1
.IX Item "int \fBpth_wait\fR(pth_event_t *\fIev\fR);"
@


1.113
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "28-Jul-1999" "GNU Pth 1.0.2" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.0.2 (28-Jul-1999)
d726 1
a726 1
.Ip "pth_t \fBpth_spawn\fR(pth_attr_t *\fIattr\fR, void *(*\fIentry\fR)(void *), void *\fIarg\fR);" 4
d1645 1
a1645 1
.IX Item "pth_t \fBpth_spawn\fR(pth_attr_t *\fIattr\fR, void *(*\fIentry\fR)(void *), void *\fIarg\fR);"
@


1.112
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "24-Jul-1999" "GNU Pth 1.0.2" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.0.2 (24-Jul-1999)
@


1.111
log
@*** empty log message ***
@
text
@d735 4
@


1.110
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "22-Jul-1999" "GNU Pth 1.0.1" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.0.1 (22-Jul-1999)
@


1.109
log
@*** empty log message ***
@
text
@d1445 6
d1836 2
@


1.108
log
@*** empty log message ***
@
text
@d1053 1
a1053 1
This dynamically initializes a mutex variable of type ``\f(CWpth_mutex_t *\fR'\*(R'.
d1055 1
a1055 1
*mutex = PTH_MUTEX_INITIALIZER\fR'\*(R'.
d1070 2
a1071 2
``\f(CWpth_rwlock_t *\fR'\*(R'.  Alternatively one can also use static initialization
via ``\f(CWpth_rwlock_t *rwlock = PTH_RWLOCK_INITIALIZER\fR'\*(R'.
d1084 2
a1085 2
``\f(CWpth_cond_t *\fR'\*(R'.  Alternatively one can also use static initialization via
``\f(CWpth_cond_t *cond = PTH_COND_INITIALIZER\fR'\*(R'.
@


1.107
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "19-Jul-1999" "GNU Pth 1.0.1" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.0.1 (19-Jul-1999)
@


1.106
log
@*** empty log message ***
@
text
@d825 7
a831 1
function to avoid temporary structure values.
d1662 2
@


1.105
log
@*** empty log message ***
@
text
@d272 3
a274 1
pth_write_ev.
d286 5
a290 1
pth_write.
d1133 6
d1145 6
d1226 7
d1239 19
d1771 2
d1775 2
d1799 2
d1802 6
@


1.104
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "17-Jul-1999" "GNU Pth 1.0.1" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.0.1 (17-Jul-1999)
@


1.103
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "16-Jul-1999" "GNU Pth 1.0.0" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.0.0 (16-Jul-1999)
@


1.102
log
@*** empty log message ***
@
text
@d272 1
a272 1
pth_write_ev,
d284 1
a284 1
pth_write,
d1377 1
a1377 1
The \fBPth\fR library was designed and implemented between February and June 1999
@


1.101
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "16-Jul-1999" "GNU Pth 1.0b9" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.0b9 (16-Jul-1999)
@


1.100
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "16-Jul-1999" "GNU Pth 1.0b8" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.0b8 (16-Jul-1999)
d287 5
a291 4
provides non-preemptive scheduling for multiple threads of execution
("multithreading") inside even driven applications. All threads runs in the
same address space of the application process, but each thread has it's own
individual program-counter, run-time stack, signal mask and errno variable.
d1313 1
a1313 1
\fIusleep\fR\|(3), \fIsleep\fR\|(3), \fIsigwait\fR\|(3), \fIwaitpid\fR\|(2), \fIselect\fR\|(2), \fIpoll\fR\|(2), \fIconnect\fR\|(2),
@


1.99
log
@*** empty log message ***
@
text
@a271 1
pth_readline_ev.
a283 1
pth_readline.
a1125 6
.Ip "ssize_t \fBpth_readline_ev\fR(int \fIfd\fR, void *\fIbuf\fR, size_t \fIbuflen\fR, pth_event_t \fIev\fR);" 4
This is equal to \fIpth_readline\fR\|(3) (see below), but has an additional event
argument \fIev\fR. When \fIpth_readline\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).
a1206 8
.Ip "ssize_t \fBpth_readline\fR(int \fIfd\fR, void *\fIbuf\fR, size_t \fIbuflen\fR);" 4
This is a convenience function which is based on \fIpth_read\fR\|(3).  It reads bytes
from filedescriptor \fIfd\fR into \fIbuf\fR until a newline (``\f(CW\en\fR'')is found, \s-1EOF\s0
occurred or \fIbuflen\fR is reached. It internally uses thread-local buffering to
be able to read larger chunks of data. Do either use \fIpth_read\fR\|(3) \fIor\fR
\fIpth_readline\fR\|(3) because \fIpth_read\fR\|(3) currently isn't aware of the buffering of
\fIpth_readline\fR\|(3). When you need generalized I/O with buffering then use a real
I/O library and let it use \fIpth_read\fR\|(3)/\fIpth_write\fR\|(3).
a1725 2
.IX Item "ssize_t \fBpth_readline_ev\fR(int \fIfd\fR, void *\fIbuf\fR, size_t \fIbuflen\fR, pth_event_t \fIev\fR);"

a1748 2

.IX Item "ssize_t \fBpth_readline\fR(int \fIfd\fR, void *\fIbuf\fR, size_t \fIbuflen\fR);"
@


1.98
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "14-Jul-1999" "GNU Pth 1.0b7" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.0b7 (14-Jul-1999)
@


1.97
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "14-Jul-1999" "GNU Pth 1.0b6" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.0b6 (14-Jul-1999)
@


1.96
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "11-Jul-1999" "GNU Pth 1.0b5" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.0b5 (11-Jul-1999)
@


1.95
log
@*** empty log message ***
@
text
@d1445 5
@


1.94
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "08-Jul-1999" "GNU Pth 1.0b5" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.0b5 (08-Jul-1999)
d270 1
d283 1
d1116 6
d1203 6
d1733 2
d1758 2
@


1.93
log
@*** empty log message ***
@
text
@d1314 2
a1315 2
\fIusleep\fR\|(3), \fIsleep\fR\|(3), \fIsigwait\fR\|(3), \fIwaitpid\fR\|(2), \fIselect\fR\|(2), \fIconnect\fR\|(2), \fIaccept\fR\|(2),
\fIread\fR\|(2), \fIwrite\fR\|(2).  
d1327 2
a1328 2
mapped: \fIfork\fR\|(2), \fIsleep\fR\|(3), \fIwaitpid\fR\|(2), \fIselect\fR\|(2), \fIconnect\fR\|(2), \fIaccept\fR\|(2),
\fIread\fR\|(2), \fIwrite\fR\|(2). 
@


1.92
log
@*** empty log message ***
@
text
@d587 1
a587 1
This initializes the \fBPth\fR library. It has to be the first \fBPth\fR \s-1API\s0
d1299 37
d1367 1
a1367 7
\fBPth\fR uses an explicit API (i.e. for instance you've to use \fIpth_read\fR\|(3) and
cannot just use \fIread\fR\|(3)) which might by nasty for some users. The reason is
because this way \fBPth\fR doesn't require any system call wrappers which usually
cannot be provided in a portable way. And portability is one of \fBPth\fR\*(R' major
goals.
.PP
Additionally \fBPth\fR (intentionally) provides no replacements for thread-safe
d1750 6
@


1.91
log
@*** empty log message ***
@
text
@d269 1
a269 1
pth_write_ev,
d272 1
d281 1
a281 1
pth_write,
d284 1
d853 15
d1108 6
a1113 6
.Ip "ssize_t \fBpth_write_ev\fR(int \fIfd\fR, const void *\fIbuf\fR, size_t \fInbytes\fR, pth_event_t \fIev\fR);" 4
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).
d1126 6
d1189 6
a1194 6
.Ip "ssize_t \fBpth_write\fR(int \fIfd\fR, const void *\fIbuf\fR, size_t \fInbytes\fR);" 4
This is a variant of the \s-1POSIX\s0 \fIwrite\fR\|(2) function. It writes \fInbytes\fR bytes
from \fIbuf\fR to filedescriptor \fIfd\fR.  The difference between \fIwrite\fR\|(2) and
\fIpth_write\fR\|(2) is that that \fIpth_write\fR\|(2) suspends execution of the current
thread until the filedescriptor is ready for writing.  For more details about
the arguments and return code semantics see \fIwrite\fR\|(2).
d1209 6
d1590 2
d1686 1
a1686 1
.IX Item "ssize_t \fBpth_write_ev\fR(int \fIfd\fR, const void *\fIbuf\fR, size_t \fInbytes\fR, pth_event_t \fIev\fR);"
d1692 2
d1710 1
a1710 1
.IX Item "ssize_t \fBpth_write\fR(int \fIfd\fR, const void *\fIbuf\fR, size_t \fInbytes\fR);"
d1715 2
@


1.90
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "08-Jul-1999" "GNU Pth 1.0b4" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.0b4 (08-Jul-1999)
@


1.89
log
@*** empty log message ***
@
text
@d215 1
d789 6
d1536 2
@


1.88
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "08-Jul-1999" "GNU Pth 1.0.4" "GNU Portable Threads"
d193 1
a193 1
GNU Pth 1.0.4 (08-Jul-1999)
@


1.87
log
@*** empty log message ***
@
text
@d191 1
a191 1
\fBGNU Pth\fR \- GNU Portable Threads
d1380 1
a1380 1
.IX Name "B<GNU Pth> - GNU Portable Threads"
@


1.86
log
@*** empty log message ***
@
text
@d632 2
a633 2
current \s-1PTH\s0 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,
@


1.85
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "08-Jul-1999" "PTH 1.0.4" "GNU Portable Threads"
@


1.84
log
@*** empty log message ***
@
text
@d191 1
a191 1
\fBPth\fR \- GNU Portable Threads
d193 1
a193 1
Pth 1.0.4 (08-Jul-1999)
d1380 1
a1380 1
.IX Name "B<Pth> - GNU Portable Threads"
@


1.83
log
@*** empty log message ***
@
text
@d191 1
a191 1
\fBGNU pth\fR \- GNU Portable Threads
d193 1
a193 1
GNU pth 1.0.4 (08-Jul-1999)
d283 1
a283 1
\fBPTH\fR is a very portable POSIX/ANSI\-C based library for Unix platforms which
d298 1
a298 1
Additionally PTH provides an optional emulation API for POSIX.1c threads
d339 1
a339 1
understand \fB\s-1PTH\s0\fR only the basic knowledge about threading is actually
d342 1
a342 1
you to use \fB\s-1PTH\s0\fR.
d477 1
a477 1
.Sh "The Compromise of \s-1PTH\s0"
d479 2
a480 2
to avoid their bad aspects? That's the general intention and goal of \fB\s-1PTH\s0\fR.
In detail this means that \fB\s-1PTH\s0\fR implements the easy to program threads of
d487 1
a487 1
\fB\s-1PTH\s0\fR. The following list summarizes a few essential points:
d489 1
a489 1
\fB\s-1PTH\s0 provides maximum portability, but \s-1NOT\s0 the fanciest features\fR. 
d499 1
a499 1
\fB\s-1PTH\s0 increases the responsiveness and concurrency of an event driven
d509 1
a509 1
occurs as it is the case for preemptive scheduling. That's why \fB\s-1PTH\s0\fR is
d512 1
a512 1
\fB\s-1PTH\s0 requires thread-safe functions, but \s-1NOT\s0 reentrant functions\fR. 
d518 1
a518 1
Especially this means that under \fB\s-1PTH\s0\fR more existing third-party libraries
d522 1
a522 1
\fB\s-1PTH\s0 doesn't require any kernel support, but can \s-1NOT\s0
d525 2
a526 2
This means that \fB\s-1PTH\s0\fR runs on mostly all types of Unix kernels, because the
kernel does not even recognize the \fB\s-1PTH\s0\fR threads (because they are
d532 2
a533 2
To better understand the \fB\s-1PTH\s0\fR \s-1API\s0 it is reasonable to first understand the
life cycle of a thread in the \fB\s-1PTH\s0\fR threading system. It can be illustrated
d577 1
a577 1
In the following the \fBPTH\fR \fIApplication Programmers Interface\fR (API) is
d584 1
a584 1
This initializes the \fB\s-1PTH\s0\fR library. It has to be the first \fB\s-1PTH\s0\fR \s-1API\s0
d590 1
a590 1
This kills the \fB\s-1PTH\s0\fR library. It should be the last \fB\s-1PTH\s0\fR \s-1API\s0 function call
d596 1
a596 1
This is a generalized query/control function for the \fB\s-1PTH\s0\fR library.  The
d634 1
a634 1
patchlevel=2, etc). For instance \s-1PTH\s0 version 1.0b1 is encoded as 0x100101.
d639 1
a639 1
Attribute objects are used in \fB\s-1PTH\s0\fR for two things: First stand-alone/unbound
d715 1
a715 1
the \fB\s-1PTH\s0\fR library.
d751 1
a751 1
a chance to execute, too.  This obviously is the cooperating part of \fB\s-1PTH\s0\fR.
d762 1
a762 1
of the non-preemptive nature of \fB\s-1PTH\s0\fR it can last longer (when another thread
d785 1
a785 1
``\f(CWpth_exit(PTH_CANCELED)\fR'\*(R' at one of his cancellation points.  In \s-1PTH\s0
d806 1
a806 1
prerequisite to use it together with the \fB\s-1PTH\s0\fR library.
d811 1
a811 1
\fB\s-1PTH\s0\fR supports \s-1POSIX\s0 style thread cancellation via \fIpth_cancel\fR\|(3) and the
d831 1
a831 1
\fB\s-1PTH\s0\fR has a very flexible event facility which is linked into the scheduler
d849 1
a849 1
the second additional argument. Keep in mind that the \fB\s-1PTH\s0\fR scheduler doesn't
d1005 1
a1005 1
in mind that in a non-preemptive threading system like \fB\s-1PTH\s0\fR this might sound
d1110 1
a1110 1
because of the non-preemptive scheduling nature of \fB\s-1PTH\s0\fR, it can be awakened
d1118 1
a1118 1
non-preemptive scheduling nature of \fB\s-1PTH\s0\fR, it can be awakened later, of
d1130 1
a1130 1
This is the \s-1PTH\s0 thread-related equivalent of \s-1POSIX\s0 \fIsigprocmask\fR\|(2) respectively
d1132 1
a1132 1
to \fIsigprocmask\fR\|(2), because \fB\s-1PTH\s0\fR internally just uses \fIsigprocmask\fR\|(2) here. So
d1184 1
a1184 1
intended to show you the look and feel of \fBPTH\fR.
d1264 1
a1264 1
\fBPTH\fR is very portable because it has only one part which perhaps has to be
d1272 1
a1272 1
switched. Additionally the \fBPTH\fR dispatcher switches also the global Unix
d1277 1
a1277 1
The \fBPTH\fR event manager is mainly \fIselect\fR\|(2) and \fIgettimeofday\fR\|(2) based, i.e.
d1294 1
a1294 1
\fBPTH\fR uses an explicit API (i.e. for instance you've to use \fIpth_read\fR\|(3) and
d1296 2
a1297 2
because this way \fBPTH\fR doesn't require any system call wrappers which usually
cannot be provided in a portable way. And portability is one of \fBPTH\fR\*(R' major
d1300 1
a1300 13
Additionally \fBPTH\fR currently doesn't provide the standardized POSIX Threading
API (\*(R"\fIpthread\fR"), although the \fBPTH\fR API is very close to it.  The reason
for this is that \fBPTH\fR\*(R' API is intentionally more flexible. For instance
there is no explicit event mechanism in POSIX threads, etc. But it is
clear that for portability reasons and easy upgrading of applications a
\fIpthread\fR\|(3) compatible wrapper API for \fBPTH\fR is required sooner or later.
Development for such a wrapper library has already started, but it will
last until \fBPTH\fR version 1.1 before this additional API can be finally
released. Actually this library just maps \fIpth_xxx()\fR functions to
\fIpthread_xxx()\fR functions and tries to emulate the POSIX return value
semantics.
.PP
Finally \fBPTH\fR (intentionally) provides no replacements for thread-safe
d1311 1
a1311 1
The \fBPTH\fR library was designed and implemented between February and June 1999
d1317 1
a1317 1
\fBPTH\fR was then implemented in order to combine the \fInon-preemptive\fR approach
d1380 1
a1380 1
.IX Name "B<GNU pth> - GNU Portable Threads"
d1438 1
a1438 1
.IX Subsection "The Compromise of \s-1PTH\s0"
@


1.82
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "07-Jul-1999" "PTH 1.0b3" "GNU Portable Threads"
d193 1
a193 1
GNU pth 1.0b3 (07-Jul-1999)
@


1.81
log
@*** empty log message ***
@
text
@d247 7
a271 1
pth_fork,
d964 38
a1105 7
.Ip "pid_t \fBpth_fork\fR(void)" 4
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.
d1416 4
d1616 14
a1664 2

.IX Item "pid_t \fBpth_fork\fR(void)"
@


1.80
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "04-Jul-1999" "PTH 1.0b3" "GNU Portable Threads"
d193 1
a193 1
GNU pth 1.0b3 (04-Jul-1999)
@


1.79
log
@*** empty log message ***
@
text
@d227 2
d879 19
d1534 4
@


1.78
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "04-Jul-1999" "PTH 1.0b2" "GNU Portable Threads"
d193 1
a193 1
GNU pth 1.0b2 (04-Jul-1999)
@


1.77
log
@*** empty log message ***
@
text
@d191 1
a191 1
\fBPTH\fR \- GNU Portable Threads
d193 1
a193 1
PTH 1.0b2 (04-Jul-1999)
d1334 1
a1334 1
.IX Name "B<PTH> - GNU Portable Threads"
@


1.76
log
@*** empty log message ***
@
text
@d275 1
a275 1
\fBPTH\fR is a portable POSIX/ANSI\-C based library for Unix platforms which
d289 4
@


1.75
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "28-Jun-1999" "PTH 1.0b2" "GNU Portable Threads"
d193 1
a193 1
PTH 1.0b2 (28-Jun-1999)
@


1.74
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "28-Jun-1999" "PTH 1.0b2" "Non-Preemtive Thread Scheduling Library"
d191 1
a191 1
\fBPTH\fR \- \fBN\fRon-\fBP\fRreemtive Thread \fBS\fRcheduling Library
d1330 1
a1330 1
.IX Name "B<PTH> - B<N>on-B<P>reemtive Thread B<S>cheduling Library"
@


1.73
log
@*** empty log message ***
@
text
@d572 1
a572 1
This initialized the \fB\s-1PTH\s0\fR library. It has to be the first \fB\s-1PTH\s0\fR \s-1API\s0
@


1.72
log
@*** empty log message ***
@
text
@d1281 7
a1290 3
.PP
``comp.programming.threads Frequently Asked Questions (F.A.Q.)'\*(R',
http://www.lambdacs.com/newsgroup/\s-1FAQ\s0.html
@


1.71
log
@*** empty log message ***
@
text
@d618 1
a618 1
.Ip "int \fBpth_version\fR(void);" 4
d1410 1
a1410 1
.IX Item "int \fBpth_version\fR(void);"
@


1.70
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "28-Jun-1999" "PTH 1.0b1" "Non-Preemtive Thread Scheduling Library"
d193 1
a193 1
PTH 1.0b1 (28-Jun-1999)
@


1.69
log
@*** empty log message ***
@
text
@d1124 1
a1124 1
.Vb 72
d1179 5
a1183 2
\&     attr = pth_attr("ticker", 0, 0, 32*1024, FALSE);
\&     pth_spawn(&attr, ticker, NULL);
d1194 1
a1194 1
\&     attr = pth_attr("handler", 0, PTH_FLAG_NOJOIN, 32*1024, NULL);
d1197 1
a1197 1
\&         pth_spawn(&attr, handler, (void *)sw);
d1280 31
d1609 6
@


1.68
log
@*** empty log message ***
@
text
@d198 2
a199 1
pth_ctrl.
d618 8
d1375 2
@


1.67
log
@*** empty log message ***
@
text
@d634 1
a634 1
\f(CWPTH_CANCEL_DISABLE\fR and \f(CWPTH_CANCEL_DEFERRED\fR and
d798 1
a798 1
\f(CWPTH_CANCEL_DEFERRED\fR and \f(CWPTH_CANCEL_ASYNCHRONOUS\fR.
@


1.66
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "26-Jun-1999" "PTH 0.9.22" "Non-Preemtive Thread Scheduling Library"
d193 1
a193 1
PTH 0.9.22 (26-Jun-1999)
d717 8
a724 6
This function raises a signal to thread \fItid\fR. Currently this functionality
of sending a signal to just a particular thread is still not implemented, so
usually this function always returns \f(CWFALSE\fR with errno set to \f(CWENOSYS\fR. But
when \fIsig\fR is 0 \s-1POSIX\s0 style thread checking is at least possible, i.e.
``\f(CWpth_raise(tid, 0)\fR'\*(R' returns \f(CWTRUE\fR when thread \fItid\fR exists in the
\fB\s-1PTH\s0\fR system.
@


1.65
log
@*** empty log message ***
@
text
@a209 2
pth_sigmask,
pth_sigraise,
d214 1
d266 1
d716 1
a716 7
.Ip "int \fBpth_sigmask\fR(int \fIhow\fR, const sigset_t *\fIset\fR, sigset_t *\fIoset\fR)" 4
This is the \s-1PTH\s0 thread-related equivalent of \s-1POSIX\s0 \fIsigprocmask\fR\|(2). The
arguments \fIhow\fR, \fIset\fR and \fIoset\fR directly relate to \fIsigprocmask\fR\|(2),
because \fB\s-1PTH\s0\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_sigraise\fR(pth_t \fItid\fR, int \fIsig\fR)" 4
d721 1
a721 1
``\f(CWpth_sigraise(tid, 0)\fR'\*(R' returns \f(CWTRUE\fR when thread \fItid\fR exists in the
d1056 6
d1415 1
a1415 3
.IX Item "int \fBpth_sigmask\fR(int \fIhow\fR, const sigset_t *\fIset\fR, sigset_t *\fIoset\fR)"

.IX Item "int \fBpth_sigraise\fR(pth_t \fItid\fR, int \fIsig\fR)"
d1538 2
@


1.64
log
@*** empty log message ***
@
text
@d657 2
a658 2
The scheduling state of the thread, i.e. either \f(CWpth_state_new\fR,
\f(CWpth_state_ready\fR, \f(CWpth_state_waiting\fR, or \f(CWpth_state_dead\fR
@


1.63
log
@*** empty log message ***
@
text
@d199 7
a206 1
pth_attr,
a209 1
pth_priority,
a215 1
pth_detach,
d220 2
a221 1
pth_time.
d617 75
a694 15
.Ip "pth_attr_t \fBpth_attr\fR(char *\fIname\fR, int \fIprio\fR, unsigned int \fIflags\fR, unsigned int \fIstacksize\fR, void *\fIstackaddr\fR);" 4
This is a constructor for \f(CWpth_attr_t\fR structures which can be used for the
first argument of \fIpth_spawn\fR\|(3) when it's not \f(CWPTH_ATTR_NULL\fR. \fIname\fR is a
string assigned to the thread which is mainly interested for debugging.
\fIprio\fR is the priority of the thread ranging from \f(CWPTH_PRIO_MIN\fR to
\f(CWPTH_PRIO_MAX\fR; the default is \f(CWPTH_PRIO_STD\fR. \fIflags\fR can be either
\f(CWPTH_FLAG_NONE\fR (no flags) or \f(CWPTH_FLAG_NOJOIN\fR (indicates that the thread
cannot be joined, i.e. after termination its immediately kicked out of the
system instead of inserted into the dead queue). \fIstacksize\fR is the number of
bytes the stack for the thread is in size. Use lower values than 32768 (32KB)
with care. Finally \fIstackaddr\fR can be a dynamically pre-allocated chunk of
memory (minimum \fIstacksize\fR in length!) which should be used for the stack
(when the thread terminates a \fIfree\fR\|(3) is done). When \fIstackaddr\fR is \f(CWNULL\fR
(the usual case) then the stack is allocated automatically by the \fB\s-1PTH\s0\fR
library.
a715 4
.Ip "int \fBpth_priority\fR(pth_t \fItid\fR, int \fIprio\fR);" 4
This overrides the priority of the thread \fItid\fR with \fIprio\fR.  The current
priority of a thread can be obtained via ``\f(CWpth_ctrl(PTH_CTRL_GETPRIO,
tid)\fR'\*(R'.
a770 5
.Ip "int \fBpth_detach\fR(pth_t \fItid\fR);" 4
This function is used to indicate to the implementation that storage for the
thread \fItid\fR can be reclaimed when that thread terminates, i.e. it just
detaches the thread by marking it unjoinable (see \fIpth_attr\fR\|(3) and
\f(CWPTH_FLAG_NOJOIN\fR).
d1291 2
d1365 42
a1408 2
.IX Item "pth_attr_t \fBpth_attr\fR(char *\fIname\fR, int \fIprio\fR, unsigned int \fIflags\fR, unsigned int \fIstacksize\fR, void *\fIstackaddr\fR);"

a1414 2
.IX Item "int \fBpth_priority\fR(pth_t \fItid\fR, int \fIprio\fR);"

a1425 2

.IX Item "int \fBpth_detach\fR(pth_t \fItid\fR);"
@


1.62
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "26-Jun-1999" "PTH 0.9.21" "Non-Preemtive Thread Scheduling Library"
d193 1
a193 1
PTH 0.9.21 (26-Jun-1999)
@


1.61
log
@*** empty log message ***
@
text
@a203 1
pth_equal,
a650 4
.Ip "int \fBpth_equal\fR(pth_t \fItid1\fR, pth_t \fItid2\fR);" 4
This compares two thread handles and returns \f(CWTRUE\fR when they are equal, i.e.
when they describe the same thread. For portability reasons do not compare
\f(CWpth_t\fR variables directly via ``\f(CW==\fR'\*(R'.
a1315 2

.IX Item "int \fBpth_equal\fR(pth_t \fItid1\fR, pth_t \fItid2\fR);"
@


1.60
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "25-Jun-1999" "PTH 0.9.20" "Non-Preemtive Thread Scheduling Library"
d193 1
a193 1
PTH 0.9.20 (25-Jun-1999)
@


1.59
log
@*** empty log message ***
@
text
@d207 1
d666 7
d1327 2
@


1.58
log
@*** empty log message ***
@
text
@d902 1
a902 1
.Ip "int \fBpth_rwlock_acquire\fR(pth_rwlock_t *\fIrwlock\fR, int \fIop\fR, pth_event_t \fIev\fR);" 4
d908 2
a909 1
the locking timeout, etc,
d1410 1
a1410 1
.IX Item "int \fBpth_rwlock_acquire\fR(pth_rwlock_t *\fIrwlock\fR, int \fIop\fR, pth_event_t \fIev\fR);"
@


1.57
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "23-Jun-1999" "PTH 0.9.20" "Non-Preemtive Thread Scheduling Library"
d193 1
a193 1
PTH 0.9.20 (23-Jun-1999)
@


1.56
log
@*** empty log message ***
@
text
@d886 1
a886 1
.Ip "int \fBpth_mutex_acquire\fR(pth_mutex_t *\fImutex\fR, pth_event_t \fIev\fR);" 4
d893 2
d1403 1
a1403 1
.IX Item "int \fBpth_mutex_acquire\fR(pth_mutex_t *\fImutex\fR, pth_event_t \fIev\fR);"
@


1.55
log
@*** empty log message ***
@
text
@d829 1
a829 1
.Ip "void \fBpth_event_free\fR(pth_event_t \fIev\fR, int \fImode\fR);" 4
d1369 1
a1369 1
.IX Item "void \fBpth_event_free\fR(pth_event_t \fIev\fR, int \fImode\fR);"
@


1.54
log
@*** empty log message ***
@
text
@d639 1
a639 1
.Ip "void \fBpth_once\fR(pth_once_t *\fIctrlvar\fR, void (*\fIfunc\fR)(void *), void *\fIarg\fR);" 4
d657 2
a658 1
priority of a thread can be obtained via ``\f(CWpth_ctrl(PTH_CTRL_GETPRIO, tid)\fR'\*(R'.
d675 1
a675 1
.Ip "void \fBpth_nap\fR(pth_time_t \fInaptime\fR);" 4
d1307 1
a1307 1
.IX Item "void \fBpth_once\fR(pth_once_t *\fIctrlvar\fR, void (*\fIfunc\fR)(void *), void *\fIarg\fR);"
d1319 1
a1319 1
.IX Item "void \fBpth_nap\fR(pth_time_t \fInaptime\fR);"
@


1.53
log
@*** empty log message ***
@
text
@d206 1
d658 6
d1313 2
@


1.52
log
@*** empty log message ***
@
text
@d374 1
a374 1
.Ip "\fBo\fR \fBreentrant\fR and \fBthread-safe\fR functions" 2
d387 9
d997 4
a1000 1
the \fIpth_sigwait()\fR call.
d1255 1
a1255 1
.IX Item "\fBo\fR \fBreentrant\fR and \fBthread-safe\fR functions"
@


1.51
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "21-Jun-1999" "PTH 0.9.19" "Non-Preemtive Thread Scheduling Library"
d193 1
a193 1
PTH 0.9.19 (21-Jun-1999)
d852 1
a852 1
.Sh "\fBSynchronization\fR"
d1375 1
a1375 1
.IX Subsection "\fBSynchronization\fR"
@


1.50
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "20-Jun-1999" "PTH 0.9.18" "Non-Preemtive Thread Scheduling Library"
d193 1
a193 1
PTH 0.9.18 (20-Jun-1999)
@


1.49
log
@*** empty log message ***
@
text
@d1142 12
@


1.48
log
@*** empty log message ***
@
text
@d239 1
a239 1
.Ip "\fBMutual Exclusion\fR" 4
d241 8
a248 3
pth_mutex_lock,
pth_mutex_unlock,
pth_mutex_holder.
d852 1
a852 1
.Sh "\fBMutual Exclusion\fR"
d854 5
a858 5
locks. Keep in mind that in a non-preemptive threading system like \fB\s-1PTH\s0\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. 
d866 1
a866 1
This dynamically initialized a mutex variable of type ``\f(CWpth_mutex_t *\fR'\*(R'.
d869 7
a875 9
.Ip "int \fBpth_mutex_acquire\fR(pth_mutex_t *\fImutex\fR, int \fIpoll\fR, pth_event_t \fIev\fR);" 4
This acquires a mutex \fImutex\fR. When \fIpoll\fR is \f(CWTRUE\fR the mutex is only
tried to be acquired. When it is already locked \f(CWFALSE\fR is returned
immediately. When \fIpoll\fR is \f(CWFALSE\fR and the mutex is already locked the
thread's execution is suspended until the mutex is unlocked again or
additionally the extra events in \fIev\fR occurred (when \fIev\fR is not \f(CWNULL\fR).
Recursive locking is 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.
d877 1
a877 1
This decrements the recursion count on \fImutex\fR and when it is zero it
d879 29
a907 3
.Ip "pth_t \fBpth_mutex_holder\fR(pth_mutex_t *\fImutex\fR);" 4
This returns the thread id of the holder of mutex \fImutex\fR. \f(CWNULL\fR is
returned when \fImutex\fR is currently not acquired by a thread.
d1209 1
a1209 1
.IX Item "\fBMutual Exclusion\fR"
d1363 1
a1363 1
.IX Subsection "\fBMutual Exclusion\fR"
d1367 1
a1367 1
.IX Item "int \fBpth_mutex_acquire\fR(pth_mutex_t *\fImutex\fR, int \fIpoll\fR, pth_event_t \fIev\fR);"
d1371 11
a1381 1
.IX Item "pth_t \fBpth_mutex_holder\fR(pth_mutex_t *\fImutex\fR);"
@


1.47
log
@*** empty log message ***
@
text
@d242 2
a243 1
pth_mutex_unlock.
d876 3
d1341 2
@


1.46
log
@*** empty log message ***
@
text
@d846 1
a846 1
.Sh "\fBMutual Exclusion Lock\fR"
d1330 1
a1330 1
.IX Subsection "\fBMutual Exclusion Lock\fR"
@


1.45
log
@*** empty log message ***
@
text
@d239 4
d846 29
d1176 2
d1329 8
@


1.44
log
@*** empty log message ***
@
text
@d210 1
d680 5
d1222 2
@


1.43
log
@*** empty log message ***
@
text
@d720 1
a720 1
``C<\fIpth_exit\fR\|(\s-1PTH_CANCELED\s0)'\*(R'.
@


1.42
log
@*** empty log message ***
@
text
@d672 1
a672 1
performed. When its \f(CWPTH_CANCEL_DEFERED\fR again the calcellation request is
d710 4
a713 4
\f(CWPTH_CANCEL_DEFERED\fR and \f(CWPTH_CANCEL_ASYNCHRONOUS\fR.
\f(CWPTH_CANCEL_ENABLE|PTH_CANCEL_DEFERED\fR is the default state where
cancellation is possible but only at cancellation points. Use
\f(CWPTH_CANCEL_DISABLE\fR to complete disable cancellation for a thread and
@


1.41
log
@*** empty log message ***
@
text
@d209 1
d215 3
d667 12
d701 20
d1129 2
d1215 2
d1226 6
@


1.40
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "19-Jun-1999" "PTH 0.9.18" "Non-Preemtive Thread Scheduling Library"
d193 1
a193 1
PTH 0.9.18 (19-Jun-1999)
@


1.39
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "18-Jun-1999" "PTH 0.9.17" "Non-Preemtive Thread Scheduling Library"
d193 1
a193 1
PTH 0.9.17 (18-Jun-1999)
@


1.38
log
@*** empty log message ***
@
text
@d255 2
a256 2
("multi-threading") inside server applications.  All threads runs in the same
address space of the server application, but each thread has it's own
d260 29
a288 25
are managed by a priority- and event-based non-preemptive scheduler. The
intention is that this way one can achieve better portability and run-time
performance than with preemptive scheduling.  The event facility allows
threads to wait until various types of events occur, including pending I/O on
filedescriptors, asynchronous signals, elapsed timers, pending I/O on message
ports, thread and process termination, and even customized callback functions.
.Sh "Background"
When programming server type applications, lots of regular jobs and one-shot
requests have to processed in parallel. To achieve this in an efficient way on
uniprocessor machines the idea of multitasking is implemented by the operation
system which can be used by the applications to spawn multiple instances of
itself. On Unix the kernel implements multitasking in a preemptive and
priority-based way through heavy-weight processes spawned with \fIfork\fR\|(2).  These
processes do usually \fInot\fR share a common address space. Instead they are
clearly separated from each other and were created by direct cloning a process
address space. 
.PP
The drawbacks are obvious: Sharing data is complicated and can usually only
solved in an efficient way through shared memory (which itself is not very
portable). Synchronization is complicated because of the preemptive nature of
the Unix scheduler. The machine resources can be exhausted very quickly when
the server application has to serve too much longer running requests occur
(heavy-weight processes cost memory). Additionally when for each request a
sub-process is spawned to handle it, the server performance is horrible
(heavy-weight processes cost time to spawn). And finally the server
d290 82
a371 13
problems. Lot's of tricks are done in practice to overcome these problems
(ranging from pre-forked sub-process pools to semi-serialized processing,
etc). 
.PP
Nevertheless one the most elegant ways to solve the 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 multithreading. But those
light-weight processes are not supported by all Unix kernels. And even where
kernel threads exists, the thread context switching is usually still too
expensive. So the usual way to solve this is to implement user-land threads
where the process is split into multiple threads of execution by the
application itself and without the knowledge of the kernel and where context
switches can be done faster.
d373 1
a373 1
User-land threads can be implemented in in various way. The two classical
d375 4
a378 2
.Ip "\fB1. Matrix-based explicit dispatching between small units of execution:\fR " 3
Here the global procedures of the server application are split into small
d383 2
a384 2
units by calling one function after each other controlled by this matrix.
The treads are created by more than one jump-trail through this matrix and by
d386 1
a386 2
events.  Examples of this is the \fIiMatix\fR \fBLibero\fR/\fB\s-1SMT\s0\fR based \fBxitami\fR
web server or the \fBSquid\fR web proxy server. 
d390 9
a398 9
matrix and the scheduling is done explicitly by the application itself) and
that it's 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's complicated to write large
server applications with this approach, because in large applications one
quickly get hundreds of execution units and the control flow inside such an
application is very hard to understand (because it's interrupted by function
borders and one always has to use the global matrix to follow it).
d400 5
a404 3
saves memory it's often nasty because one cannot switch between threads in the
middle of a function. The scheduling borders are function borders.
.Ip "\fB2. Queue-based based implicit scheduling between threads of execution:\fR " 3
d412 1
a412 2
synchronization things) doesn't have to care about this.  Examples of this
approach are the various \s-1POSIX\s0 thread ("pthread") based server applications.
d415 3
a417 3
because the control flow of a thread directly follows a procedure without
forced interrupts through function borders. Additionally the programming is
very similar to the \fIfork\fR\|(2) approach.
d419 2
a420 2
The disadvantage is that although the general performance is increased
compared to using approaches with heavy-weight processes, it's decreased
d423 1
a423 1
switch costs some overhead even when it's a lot cheaper than a kernel-level
d425 3
a427 3
Finally there is no really portable \s-1ANSI\s0 C & \s-1POSIX\s0 based way to implement
preemptive threads yourself. Either the platform already has threads or one has
to hope that some semi-portable package exists for it. And even those
d434 1
a434 1
.Sh "The Compromise"
d436 52
a487 4
to avoid their bad aspects? That's the general intention of \fB\s-1PTH\s0\fR. In detail
this means that \fB\s-1PTH\s0\fR implements the easy to program threads of execution but
in a way which doesn't have the portability side-effects of preemptive
scheduling. This means that instead a non-preemptive scheduling is used. 
d489 3
a491 3
To better understand the \fB\s-1PTH\s0\fR \s-1API\s0 its reasonable to first understand the
life cycle of a thread in the \fB\s-1PTH\s0\fR system. It can be illustrated with the
following graph:
d497 3
a499 3
\&       +--> READY---+
\&       |      ^     |
\&       |      |     V
d501 3
a503 3
\&                    |
\&                    V
\&                  DEAD
d505 1
a505 1
When a new thread is created it is moved into the \fB\s-1NEW\s0\fR queue of the
d508 1
a508 1
want to perform a \s-1CPU\s0 burst. They are queued  in priority order.  Per
d510 2
a511 2
priority only.  The assigned queue priority for all remaining threads every
time is increased by one to prevent thread starvation.
d514 7
a520 6
thread (there is always just one \fB\s-1RUNNING\s0\fR thread, of course). After this
thread yields execution (either explicitly or implicitly by calling a function
which would block) there are three possibilities: Either it has terminated,
then it's moved to the \fB\s-1DEAD\s0\fR queue, or it has events on which it wants to
wait, then its moved into the \fB\s-1WAITING\s0\fR queue. Else it is assumed it wants to
perform more \s-1CPU\s0 bursts and enters the \fB\s-1READY\s0\fR queue again. 
d524 1
a524 1
occured, its immediately moved to the \fB\s-1READY\s0\fR queue, too.
d528 5
a532 4
scheduler and the scheduler invokes a thread. 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 its joinable
it enter the \fB\s-1DEAD\s0\fR queue.  There is remains until another thread joins it.
d534 3
a536 2
In the following the \fBPTH\fR Application Programmers Interface (API) is
discussed in detail.
d632 1
a632 1
priority of a thread can be obtained via ``\fIpth_ctrl\fR\|(\s-1PTH_CTRL_GETPRIO\s0, tid)'\*(R'.
a915 30
.SH "IMPLEMENTATION NOTES"
\fBPTH\fR is very portable because it has only one part which perhaps have 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
\fIsigstack\fR\|(2) or \fIsigaltstack\fR\|(2) [see \f(CWpth_mctx.c\fR for details]. Any other code
is plain POSIX and ANSI C based. 
.PP
The context switching is done via POSIX [sig]\fIsetjmp\fR\|(3) and [sig]\fIlongjmp\fR\|(3).
Here all CPU registers, the program counter and the stack pointer are
switched. Additionally the \fBPTH\fR dispatcher switches also the global Unix
\f(CWerrno\fR variable [see \f(CWpth_mctx.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
calculations and both the time and all I/O events are implemented via a single
\fIselect\fR\|(2) call [see \f(CWpth_sched.c\fR for details].
.PP
The thread control block management is done via 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(CWpth_tcb.h\fR and \f(CWpth_pqueue.c\fR for
details].
.PP
Most time critical sections (especially the dispatcher and event manager) are
speeded up by inlined functions (implemented as ANSI C macros). Additionally
any debugging code is \fIcompletely\fR removed from the source when not built
with \f(CW-DPTH_DEBUG\fR (see \f(CW--enable-debug\fR), i.e. not only stub functions
remain [see \f(CWpth_debug.h\fR for details].
d997 30
a1026 2
.SH "BUGS"
No real bugs currently known.
d1028 2
a1029 2
\fBPTH\fR uses an explicit API (i.e. for instance you've to use \fIpth_read()\fR and
cannot just use \fIread()\fR) which might by nasty for some users. The reason is
d1034 10
a1043 16
Finally \fBPTH\fR (intentionally) provides no replacements for non-reentrant
(e.g. \fIstrtok\fR\|(3) which uses a static internal buffer) or synchronous system
functions (e.g. \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 reentrant functions possibly
against an existing \f(CWlibc_r\fR of the platform vendor).  For an asynchronous
DNS resolver library use either the new \f(CWlibresolv\fR from \fBBIND 8\fR ( see
ftp://ftp.isc.org/isc/bind/ ) or the forthcoming GNU \fBadns\fR package from Ian
Jackson ( see http://www.gnu.org/software/adns/adns.html ).
.SH "SEE ALSO"
pth-\fIconfig\fR\|(1), \fIpthread\fR\|(3).
.PP
\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).
d1060 9
a1068 3
test version of Apache. The concept and API of message ports was borrowed from
AmigaOS\*(R' \fBExec\fR. The concept and idea for the flexible event mechanism came
from \fIPaul Vixie\fR's \fBeventlib\fR (part of \fBBIND8\fR).
d1105 15
a1119 1
.IX Subsection "Background"
d1123 3
a1125 1
.IX Item "\fB1. Matrix-based explicit dispatching between small units of execution:\fR "
d1127 1
a1127 1
.IX Item "\fB2. Queue-based based implicit scheduling between threads of execution:\fR "
d1129 7
a1135 1
.IX Subsection "The Compromise"
a1276 2
.IX Header "IMPLEMENTATION NOTES"

d1279 1
a1279 1
.IX Header "BUGS"
d1283 2
a1285 2

.IX Header "HISTORY"
@


1.37
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "12-Jun-1999" "PTH 1.0.0" "Non-Preemtive Thread Scheduling Library"
d193 1
a193 1
PTH 1.0.0 (12-Jun-1999)
@


1.36
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "09-Jun-1999" "PTH 0.9.16" "Non-Preemtive Thread Scheduling Library"
d193 1
a193 1
PTH 0.9.16 (09-Jun-1999)
@


1.35
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "04-Jun-1999" "PTH 0.9.16" "Non-Preemtive Thread Scheduling Library"
d193 1
a193 1
PTH 0.9.16 (04-Jun-1999)
d235 1
d246 1
d679 6
d743 1
a743 1
This is a variant of the \s-1POSIX\s0 \fIwaitpid\fR\|(2) function. It suspends suspends the
d749 6
d1097 2
d1118 2
@


1.34
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "04-Jun-1999" "PTH 0.9.15" "Non-Preemtive Thread Scheduling Library"
d193 1
a193 1
PTH 0.9.15 (04-Jun-1999)
d255 1
a255 1
individual run-time stack and program-counter.
d260 4
a263 4
performance than with preemptive scheduling.  The event facility allows threads
to wait until various types of events occur, including pending I/O on
filedescriptors, elapsed timers, pending I/O on message ports, thread and
process termination, and even customized callback functions.
@


1.33
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "03-Jun-1999" "PTH 0.9.15" "Non-Preemtive Thread Scheduling Library"
d193 1
a193 1
PTH 0.9.15 (03-Jun-1999)
@


1.32
log
@*** empty log message ***
@
text
@d571 10
a580 7
.Ip "\f(CWPTH_EVENT_SIG\fR" 8
This is a signal event. The additional argument has to be a signal number
(``\f(CWSIG\fR\fIname\fR''). This event wait until the signal is pending. Keep in mind
that the \fB\s-1PTH\s0\fR scheduler doesn't block signals itself.  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(CWpth_event(PTH_EVENT_SIG,
SIGUSR1)\fR'\*(R'.
d1033 1
a1033 1
.IX Item "\f(CWPTH_EVENT_SIG\fR"
@


1.31
log
@*** empty log message ***
@
text
@d621 3
a623 1
returns this new reached event.
@


1.30
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "01-Jun-1999" "PTH 0.9.14" "Non-Preemtive Thread Scheduling Library"
d193 1
a193 1
PTH 0.9.14 (01-Jun-1999)
@


1.29
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "01-Jun-1999" "PTH 0.9.13" "Non-Preemtive Thread Scheduling Library"
d193 1
a193 1
PTH 0.9.13 (01-Jun-1999)
@


1.28
log
@*** empty log message ***
@
text
@d215 1
a215 1
pth_event
d251 2
a252 2
\fBPTH\fR is a maximum portable POSIX/ANSI\-C based library for Unix platforms
which provides non-preemptive scheduling for multiple threads of execution
d472 5
a476 1
with care.
d503 1
a503 1
This overrides the priority of the thread \fIthread\fR with \fIprio\fR.  The current
d528 7
a534 7
the various \fIpth_event_xxx()\fR functions). Its 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 after tagging them as occured. 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 occured events and the
application can use \fIpth_event_occurred\fR\|(3) to test which events occured.
d555 1
a555 1
This is a constructor for a pth_time_t structure which is a convenient
d562 47
a608 2
This creates a new event ring consisting of a single event.
Its type is specified by \fIspec\fR. ???\s-1MORE\s0 \s-1DETAILS\s0???
d611 3
a613 1
and returns \fIev\fR. The end of the argument list has to be a \f(CWNULL\fR argument.
d615 3
a617 2
This isolates the event \fIev\fR from possibly appended
events in the event ring.
d619 3
a621 2
This walks to the next or previews event in the event ring \fIev\fR and
returns this event.
d623 8
a630 3
This checks whether the event \fIev\fR occurred.
.Ip "void \fBpth_event_free\fR(pth_event_t \fIev\fR, int \fIall\fR);" 4
This deallocates the event \fIev\fR or all events appended to it.
d773 11
a783 9
ported to new platforms (the machine context initialization). But its written
in a way which works on mostly all Unix platforms which support \fIsigstack\fR\|(2) or
\fIsigaltstack\fR\|(2) [see \f(CWpth_mctx.c\fR for details]. Any other code is plain POSIX
and ANSI C based. 
.PP
The context switching is done via POSIX \fIsetjmp\fR\|(3) and \fIlongjmp\fR\|(3).  Here all
CPU registers, the program counter and the stack pointer are switched.
Additionally the \fBPTH\fR dispatcher switches also the global Unix \f(CWerrno\fR
variable [see \f(CWpth_mctx.c\fR for details].
d786 1
a786 1
the current time is fetched via \fIgettimeofday\fR\|(2) on every context switch for
d791 1
a791 1
data structure overhead. For this the queue linkage variables are part of the
d875 1
a875 1
\&     attr = pth_attr("handler", 0, 0, 32*1024, FALSE);
a890 2
Additionally \fBPTH\fR still lacks support for per-thread signal handling.
.PP
d904 3
a906 2
\fIsigstack\fR\|(2), \fIsigaltstack\fR\|(2), \fIsigaction\fR\|(2), \fIsigemptyset\fR\|(2), \fIsigaddset\fR\|(2), \fIsigprocmask\fR\|(2).
\fIsetjmp\fR\|(3), \fIlongjmp\fR\|(3), \fIselect\fR\|(2), \fIgettimeofday\fR\|(2).
d908 1
a908 1
The \fBPTH\fR library was designed and implemented between February and May 1999
d911 2
a912 2
\fILars Eilebrecht\fR and \fIRalph Babel\fR related to an experimental (matrix based)
non-preemptive \*(C+ scheduler class written by \fIPeter Simons\fR. 
d1026 14
d1048 1
a1048 1
.IX Item "void \fBpth_event_free\fR(pth_event_t \fIev\fR, int \fIall\fR);"
@


1.27
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "30-May-1999" "PTH 0.9.12" "Non-Preemtive Thread Scheduling Library"
d193 1
a193 1
PTH 0.9.12 (30-May-1999)
@


1.26
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "30-May-1999" "PTH 0.9.12" "Non-Preemptive Thread Scheduling Library"
d462 1
a462 1
.Ip "pth_attr_t \fBpth_attr\fR(char *\fIname\fR, int \fIprio\fR, unsigned int \fIflags\fR, unsigned int \fIstacksize\fR);" 4
d522 1
a522 1
.Ip "int \fBpth_wait\fR(pth_event_t *\fIev_waiting\fR, pth_event_t *\fIev_occurred\fR);" 4
d524 1
a524 1
the various \fIpth_event_xxx()\fR functions). Its modeled like \fIselect\fR\|(2), i.e.  one
d526 5
a530 10
\fIev_waiting\fR) on which the current thread wants to wait.  The scheduler
awakes the thread when one ore more of them occurred after moving them from
\fIev_waiting\fR to \fIev_occurred\fR (the second event ring). Both arguments are
\fIpointers\fR to event rings. \fIev_occurred\fR is usually just a pointer to a
\f(CWpth_event_t\fR variable (which needs not to be initialized but can be).  
.Sp
When \fIev_occurred\fR is specified as \f(CWNULL\fR, the scheduler doesn't move the
occurred events out of \fIev_waiting\fR, i.e. the application then has to use
\fIpth_event_occurred\fR\|(3) explicitly on all events in \fIev_waiting\fR to find out
which one has occurred, but this way it can reuse the \fIev_waiting\fR event ring.
d935 1
a935 1
.IX Item "pth_attr_t \fBpth_attr\fR(char *\fIname\fR, int \fIprio\fR, unsigned int \fIflags\fR, unsigned int \fIstacksize\fR);"
d951 1
a951 1
.IX Item "int \fBpth_wait\fR(pth_event_t *\fIev_waiting\fR, pth_event_t *\fIev_occurred\fR);"
@


1.25
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "28-May-1999" "PTH 0.9.11" "Non-Preemptive Thread Scheduling Library"
d193 1
a193 1
PTH 0.9.11 (28-May-1999)
@


1.24
log
@*** empty log message ***
@
text
@d235 2
d246 1
d567 1
a567 1
and returns \fIev\fR.
d619 12
d683 7
d1010 4
d1029 2
@


1.23
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "28-May-1999" "PTH 0.9.10" "Non-Preemptive Thread Scheduling Library"
d193 1
a193 1
PTH 0.9.10 (28-May-1999)
@


1.22
log
@*** empty log message ***
@
text
@@


1.21
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "25-May-1999" "PTH 1.0.0" "Non-Preemptive Thread Scheduling Library"
d193 1
a193 1
PTH 1.0.0 (25-May-1999)
@


1.20
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "25-May-1999" "PTH 0.9.9" "Non-Preemptive Thread Scheduling Library"
d193 1
a193 1
PTH 0.9.9 (25-May-1999)
@


1.19
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "24-May-1999" "PTH 0.9.8" "Non-Preemptive Thread Scheduling Library"
d193 1
a193 1
PTH 0.9.8 (24-May-1999)
@


1.18
log
@*** empty log message ***
@
text
@d823 3
a825 3
DNS resolver library use either the new \f(CWlibresolv\fR from \fBBIND 8\fR (see
ftp://ftp.isc.org/isc/bind/) or the forthcoming GNU \fBadns\fR package from Ian
Jackson (see http://www.gnu.org/software/adns/adns.html).
d835 1
a835 1
\fILars Eilebrecht\fR and \fIRalf Babel\fR related to an experimental (matrix based)
d846 1
a846 1
threading library (\fBrsthread\fR) written by \fIRobert S. Tau\fR for an ancient
@


1.17
log
@*** empty log message ***
@
text
@d816 1
a816 1
Finally N<PTH> (intentionally) provides no replacements for non-reentrant
@


1.16
log
@*** empty log message ***
@
text
@d360 43
d815 11
d895 2
@


1.15
log
@*** empty log message ***
@
text
@d657 1
a657 1
\fIsigaltstack\fR\|(2) [see C<pth_mctx.c for details]. Any other code is plain POSIX
@


1.14
log
@*** empty log message ***
@
text
@d653 28
d955 2
@


1.13
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "23-May-1999" "PTH 0.9.7" "Non-Preemptive Thread Scheduling Library"
d193 1
a193 1
PTH 0.9.7 (23-May-1999)
d219 1
a219 1
pth_event_occured,
d288 1
a288 1
leight-weight processes are not supported by all Unix kernels. And even where
d305 1
a305 1
switching between these jump-trails controlled by corresponding occured
d317 1
a317 1
quickly get hundrets of execution units and the control flow inside such an
d369 1
a369 1
begin of the \fImain()\fR function of the application. This implicity spawns the
d435 1
a435 1
complete processo and not just the current thread.
d437 1
a437 1
This is a convienience function which uses a control variable of type
d469 1
a469 1
nor that the threas is awakened exactly after \fInaptime\fR has elapsed. It's
d471 1
a471 1
of the non-preemtive nature of \fB\s-1PTH\s0\fR it can last longer (when another thread
d476 1
a476 1
.Ip "int \fBpth_wait\fR(pth_event_t *\fIev_waiting\fR, pth_event_t *\fIev_occured\fR);" 4
d481 3
a483 3
awakes the thread when one ore more of them occured after moving them from
\fIev_waiting\fR to \fIev_occured\fR (the second event ring). Both arguments are
\fIpointers\fR to event rings. \fIev_occured\fR is usually just a pointer to a
d486 4
a489 4
When \fIev_occured\fR is specified as \f(CWNULL\fR, the scheduler doesn't move the
occured events out of \fIev_waiting\fR, i.e. the application then has to use
\fIpth_event_occured\fR\|(3) explicitly on all events in \fIev_waiting\fR to find out
which one has occured, but this way it can reuse the \fIev_waiting\fR event ring.
d510 1
a510 1
This is a constructor for a pth_time_t structure which is a convinient
d528 2
a529 2
.Ip "int \fBpth_event_occured\fR(pth_event_t \fIev\fR);" 4
This checks whether the event \fIev\fR occured.
d537 1
a537 1
can specifiy a destructor function which is called on the current threads
d574 1
a574 1
This is equal to \fIpth_write\fR\|(3) (see below), but has an addtional event argument
d580 1
a580 1
This is equal to \fIpth_read\fR\|(3) (see below), but has an addtional event argument
d586 1
a586 1
This is equal to \fIpth_readline\fR\|(3) (see below), but has an addtional event
d646 1
a646 1
This is a convienience function which is based on \fIpth_read\fR\|(3).  It reads bytes
d648 1
a648 1
occured or \fIbuflen\fR is reached. It internally uses thread-local buffering to
d850 1
a850 1
.IX Item "int \fBpth_wait\fR(pth_event_t *\fIev_waiting\fR, pth_event_t *\fIev_occured\fR);"
d872 1
a872 1
.IX Item "int \fBpth_event_occured\fR(pth_event_t \fIev\fR);"
@


1.12
log
@*** empty log message ***
@
text
@d367 5
a371 2
This initialized the \fB\s-1PTH\s0\fR library. It has to be the first \fIpth_xxx()\fR call
made by an application.
d373 5
d379 8
a386 1
\&...
d388 25
a412 5
This returns a floating point value describing the exponential averaged load
of the scheduler. 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. A higher load means there a more threads ready
who want to do \s-1CPU\s0 bursts. The average load value is adjusted once per second.
d414 13
a426 2
The following functions control the threading itself.
.Ip "pth_attr_t \fBpth_attr\fR(char *\fIname\fR, int \fIprio\fR, unsigned int \fIflags\fR, unsigned int \fIstacksize\fR, int \fIjoinable\fR);" 4
d428 15
a442 5
This spawns a new thread with the attributes given in \fIattr\fR with the start
point at routine \fIentry\fR. This entry routine is called as \fIentry\fR(\fIarg\fR)
inside the new thread. When \fIentry\fR returns an implicit \fIpth_exit\fR\|(\s-1NULL\s0) is
done.
.Ip "void \fBpth_once\fR(pth_once_t *\fIoncectrl\fR, void (*\fIconstructor\fR)(void *), void *\fIarg\fR);" 4
d444 11
a454 2
.Ip "int \fBpth_equal\fR(pth_t \fIthread1\fR, pth_t \fIthread2\fR);" 4
.Ip "void \fBpth_priority\fR(pth_t \fIthread\fR, int \fIprio\fR);" 4
d456 9
d466 31
a496 2
.Ip "int \fBpth_wait\fR(pth_event_t *\fIev_pending\fR, pth_event_t *\fIev_occured\fR);" 4
.Ip "int \fBpth_join\fR(pth_t \fIthread\fR, void **\fIvalue\fR);" 4
d498 6
d505 1
d507 2
d510 2
d513 3
d517 2
d520 2
d523 2
d526 2
d529 1
d531 1
d533 2
d536 3
d540 1
d542 1
d544 1
d546 2
d549 3
d553 2
d556 2
d559 1
d561 1
d563 3
d567 1
d569 4
d574 5
d580 5
d586 5
d592 3
d634 5
a638 5
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).  For more
details about the arguments and return code semantics see \fIaccept\fR\|(2).
d640 5
d646 7
d824 8
d834 1
a834 1
.IX Item "pth_attr_t \fBpth_attr\fR(char *\fIname\fR, int \fIprio\fR, unsigned int \fIflags\fR, unsigned int \fIstacksize\fR, int \fIjoinable\fR);"
d838 1
a838 1
.IX Item "void \fBpth_once\fR(pth_once_t *\fIoncectrl\fR, void (*\fIconstructor\fR)(void *), void *\fIarg\fR);"
d842 1
a842 1
.IX Item "int \fBpth_equal\fR(pth_t \fIthread1\fR, pth_t \fIthread2\fR);"
d844 1
a844 1
.IX Item "void \fBpth_priority\fR(pth_t \fIthread\fR, int \fIprio\fR);"
d850 1
a850 1
.IX Item "int \fBpth_wait\fR(pth_event_t *\fIev_pending\fR, pth_event_t *\fIev_occured\fR);"
d852 1
a852 1
.IX Item "int \fBpth_join\fR(pth_t \fIthread\fR, void **\fIvalue\fR);"
@


1.11
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "23-May-1999" "PTH 0.9.7" "Non-Preemtive Thread Scheduling Library"
d431 7
a437 4
This is a variant of 4.3BSD's \fIusleep\fR\|(3) function. It suspends the current
threads execution until \fIusec\fR microsecond (= \fIusec\fR * 1/1000000s) elapsed.
The thread is guarrantied to not awakened before this time, but because of the
non-preemptive scheduling nature of \fB\s-1PTH\s0\fR, it can be awakened a lot later.
d439 7
d447 6
d454 7
d462 5
@


1.10
log
@*** empty log message ***
@
text
@d249 1
a249 1
which provides non-preemtive scheduling for multiple threads of execution
d255 1
a255 1
are managed by a priority- and event-based non-preemtive scheduler. The
d257 1
a257 1
performance than with preemtive scheduling.  The event facility allows threads
d266 1
a266 1
itself. On Unix the kernel implements multitasking in a preemtive and
d274 1
a274 1
portable). Synchronization is complicated because of the preemtive nature of
d327 1
a327 1
still interrupted \- even in the middle of a function.  Actually in a preemtive
d341 1
a341 1
compared to the matrix-approach above. Because the implicit preemtive
d344 1
a344 1
context switch) than the explicit cooperative/non-preemtive scheduling.
d346 1
a346 1
preemtive threads yourself. Either the platform already has threads or one has
d353 1
a353 1
from synchronization and portability problems caused by its preemtive nature.
d358 2
a359 2
in a way which doesn't have the portability side-effects of preemtive
scheduling. This means that instead a non-preemtive scheduling is used. 
d423 7
d431 4
d539 1
a539 1
by \fIRalf S. Engelschall\fR after evaluating various (mostly preemtive) thread
d542 1
a542 1
non-preemtive \*(C+ scheduler class written by \fIPeter Simons\fR. 
d544 1
a544 1
\fBPTH\fR was then implemented in order to combine the \fInon-preemtive\fR approach
d549 1
a549 1
So the essential idea for the non-preemtive approach was taken over from
d691 2
@


1.9
log
@*** empty log message ***
@
text
@d239 1
@


1.8
log
@*** empty log message ***
@
text
@d198 1
a198 2
pth_stat,
pth_load.
d363 2
d366 2
d369 8
a376 2
.Ip "unsigned int \fBpth_stat\fR(int \fItype\fR);" 4
.Ip "float \fBpth_load\fR(void);" 4
d497 1
a497 1
\&     sar.sin_family      = AF_INET;
d499 1
a499 1
\&     sar.sin_port        = htons(port);
d510 10
d521 4
a524 1
pth-\fIconfig\fR\|(1), \fIpthread\fR\|(3), \fIfork\fR\|(2).
d526 4
a529 4
The \fBPTH\fR library was designed and implemented between February and May
1999 by \fIRalf S. Engelschall\fR after evaluating various (mostly preemtive)
thread libraries and intensive discussions with \fIPeter Simons\fR, \fIMartin
Kraemer\fR and \fILars Eilebrecht\fR related to an experimental (matrix based)
d535 1
a535 5
programming). Some code inspiration also came from an old (never publically
released) threading library written by \fIRobert S. Tau\fR.  Additionally the
concept and API of message ports was borrowed from AmigaOS\*(R' \fIExec\fR after,
while the idea for the event mechanism itself came from \fIPaul Vixie\fR's
\fIeventlib\fR.
d537 7
a543 5
So, the essential idea for the non-preemtive approach was take over from
\fIPeter Simons\fR scheduler.  The priority based scheduling algorithm was
contributed by \fIMartin Kraemer\fR.  initial. Some hard-core for the machine
context switching was borrowed from \fIRobert S. Tau\fR's threading library.  The
implementation of \fBPTH\fR itself was done by \fIRalf S. Engelschall\fR.
d598 1
a598 3
.IX Item "unsigned int \fBpth_stat\fR(int \fItype\fR);"

.IX Item "float \fBpth_load\fR(void);"
d695 4
@


1.7
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "22-May-1999" "PTH 0.9.6" "Non-Preemtive Thread Scheduling Library"
d193 1
a193 1
PTH 0.9.6 (22-May-1999)
d198 2
a199 1
pth_stat.
d248 5
a252 5
\fBPTH\fR is a POSIX/ANSI\-C based library for Unix platforms which provides
non-preemtive scheduling for multiple threads of execution ("multi-threading")
inside server applications.  All threads runs in the same address space of the
server application, but each thread has it's own individual run-time stack and
program-counter.
d331 2
a332 1
synchronization things) doesn't have to care about this.
d358 2
a359 2
in a way which doesn't have the side-effects of preemtive scheduling. This
means that instead a non-preemtive scheduling is used. 
d364 4
a367 1
\&...
d370 1
d376 9
d386 2
d389 6
d396 4
d401 7
d409 3
d413 7
d421 80
a500 1
\&...
d574 8
d584 2
d588 18
d608 4
d614 12
d628 8
d638 14
d654 6
d661 14
@


1.6
log
@*** empty log message ***
@
text
@d249 3
a251 3
inside high-performance server applications.  All threads runs in the same
address space of the server application, but each thread has it's own
individual run-time stack and program-counter.
@


1.5
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "21-May-1999" "PTH 0.9.6" "Non-Preemtive Scheduler"
d191 1
a191 1
\fBPTH\fR \- \fBN\fRon-\fBP\fRreemtive \fBS\fRcheduling Library
d193 1
a193 1
PTH 0.9.6 (21-May-1999)
d411 1
a411 1
.IX Name "B<PTH> - B<N>on-B<P>reemtive B<S>cheduling Library"
@


1.4
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "19-May-1999" "PTH 0.9.4" "Non-Preemtive Scheduler"
d191 1
a191 1
\fBPTH\fR \- Non-Preemtive Scheduling Library
d193 1
a193 1
PTH 0.9.4 (19-May-1999)
d195 52
d248 4
a251 6
non-preemtive scheduling for multiple threads of execution
(\*(R"\fImulti-threading\fR") inside high-performance server applications.  All
threads runs in the same address space of the server application, but each
thread has it's own individual run-time stack and program-counter. The API is
very similar to the POSIX threads API (\*(R"\fIpthreads\fR"), i.e. one can spawn and
join threads.  
d253 7
a259 8
But the thread scheduling itself is done in a cooperative instead of the usual
preemtive way.  The threads are managed by a priority- and event-based
non-preemtive scheduler. The intention is to achieve this way better
portability and run-time performance.  The event facility allows threads to
wait until various types of events occur, including filedescriptor I/O,
elapsed timers, raised signals, message port I/O, thread and process
termination, etc.
.SH "DESCRIPTION"
d268 2
a269 1
clearly separated from each other. 
d274 2
a275 2
the Unix scheduler.  The machine resources can be exhausted very quickly when
the server application has to serve too much one-shot requests at once
d281 2
a282 1
(ranging from pre-forked sub-process pools to semi-serialized processing). 
d284 9
a292 7
Nevertheless the most elegant way to solve the resource and data sharing
problems would be to have multiple \fIlight-weight\fR threads of execution inside
a (heavy-weight) process, i.e. to use multithreading. But those leight-weight
processes are not supported by all Unix kernels. So the usual way to solve
this is to implement user-land threads where the process is split into
multiple threads of execution by the application itself and without the
knowledge of the kernel.
d295 5
a299 6
approaches exists:
.Ip "\fB1.\fR" 3
\fBmatrix-based explicit dispatching between small units of execution:\fR Here the
global procedures of the server application are split into small execution
units (each has to run maximal a few milliseconds) and those units are
implemented by separate program functions. Then a global matrix is created
d303 4
a306 2
Examples of this is the iMatix Libero/\s-1SMT\s0 based xitami server or the Squid web
proxy server. 
d309 4
a312 4
possible (because one can fine-tune the threads of execution because the
scheduling is done explicitly by the application itself) and that it's very
portable (because the matrix is just an ordinary data structure and functions
are a standard feature of \s-1ANSI\s0 C).
d319 12
a330 10
.Ip "\fB2.\fR" 3
\fBqueue-based based implicit scheduling between threads of execution:\fR Here
the idea is that one programs as with \fIfork\fR\|(2)'ed 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 execution control is interrupted, of course.
Actually in a preemtive way similar to what the kernel does for the
heavy-weight processes, i.e. every few milliseconds the scheduler switches
between the threads of execution. But the thread itself doesn't recognize this
and usually (except for synchronization things) doesn't have to care about
this.
d334 2
a335 2
forced interrupts. Additionally the programming is very similar to the \fIfork\fR\|(2)
approach.
d343 1
a343 3
Additionally one more side-effect of this preemtive approach is that one
large procedures via implicit preemtion (e.g. \s-1POSIX\s0 threads).  And finally
there is no really portable \s-1ANSI\s0 C & \s-1POSIX\s0 based way to implement
d352 1
a352 1
.SH "The Compromise"
d354 8
a361 5
to avoid their bad aspects? That's The general intention of \fBPTH\fR. In detail
this means that \fBPTH\fR implements the easy to program threads of execution but
in a way which doesn't have the side-effects. This means that instead of
preemtive scheduling a non-preemtive scheduling is used. 
.SH "FUNCTIONS"
d363 13
d381 5
a385 5
The \fBPTH\fR library was designed between February 1999 and May 1999 by \fIRalf
S.  Engelschall\fR after evaluating various (mostly preemtive) thread libraries
and intensive discussions with \fIPeter Simons\fR, \fIMartin Kraemer\fR and \fILars
Eilebrecht\fR related to an experimental (matrix based) non-preemtive \*(C+
scheduler class written by \fIPeter Simons\fR. 
d411 1
a411 1
.IX Name "B<PTH> - Non-Preemtive Scheduling Library"
d419 16
d441 19
a459 1
.IX Item "\fB1.\fR"
d461 1
a461 1
.IX Item "\fB2.\fR"
d463 1
a463 1
.IX Header "The Compromise"
d465 1
a465 1
.IX Header "FUNCTIONS"
@


1.3
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "14-May-1999" "PTH 0.9.3" "Non-Preemtive Scheduler"
d193 1
a193 1
PTH 0.9.3 (14-May-1999)
d320 5
a324 2
programming). Additional code inspiration came from an old (never publically
released) threading library written by \fIRobert S. Tau\fR. 
d329 1
a329 1
context switching was borrowed from \fIRobert S. Tau\fR's threading library. The
@


1.2
log
@*** empty log message ***
@
text
@d96 1
a96 1
.TH pth 3 "13-May-1999" "PTH 0.9.1" "Non-Preemtive Scheduler"
d193 1
a193 1
PTH 0.9.1 (13-May-1999)
@


1.1
log
@Initial revision
@
text
@d96 1
a96 1
.TH pth 3 "13-May-1999" "PTH 0.9.0" "Non-Preemtive Scheduler"
d191 1
a191 1
\fBpth\fR \- Non-Preemtive Scheduler
d193 1
a193 1
PTH 0.9.0 (13-May-1999)
d195 15
a209 1
\&...
d311 17
a327 13
The \fBPTH\fR library was written between February 1999 and May 1999 by Ralf S.
Engelschall. It was inspired by an experimental (matrix based) non-preemtive
\*(C+ scheduler class written by Peter Simons and a thread-package by Robert S.
Tau. Ralf S. Engelschall combined the non-preemtive approach with the popular
idea of threads of executions one can found in POSIX thread libraries after
receiving excellent hints from Peter Simons, Martin Kraemer and Lars
Eilebrecht. 
.PP
The non-preemtive nature was takeb over from Peter Simons. The priority based
scheduling algorithm was contributed by Martin Kraemer.  So the original
intention of \fBPTH\fR was to combine the speed and simplicity of matrix based
dispatching libraries with the programming idea of multiple threads of
execution from the preemtive POSIX threading libraries.
d338 1
a338 1
.IX Name "B<pth> - Non-Preemtive Scheduler"
@


1.1.1.1
log
@Import of PTH into CVS
@
text
@@