1 PTHREADS-WIN32
2 ==============
3
4 Pthreads-win32 is free software, distributed under the GNU Lesser
5 General Public License (LGPL). See the file 'COPYING.LIB' for terms
6 and conditions. Also see the file 'COPYING' for information
7 specific to pthreads-win32, copyrights and the LGPL.
8
9
10 What is it?
11 -----------
12
13 Pthreads-win32 is an Open Source Software implementation of the
14 Threads component of the POSIX 1003.1c 1995 Standard (or later)
15 for Microsoft's Win32 environment. Some functions from POSIX
16 1003.1b are also supported including semaphores. Other related
17 functions include the set of read-write lock functions. The
18 library also supports some of the functionality of the Open
19 Group's Single Unix specification, version 2, namely mutex types,
20 plus some common and pthreads-win32 specific non-portable
21 routines (see README.NONPORTABLE).
22
23 See the file "ANNOUNCE" for more information including standards
24 conformance details and the list of supported and unsupported
25 routines.
26
27
28 Prerequisites
29 -------------
30 MSVC or GNU C (MinGW32 MSys development kit)
31 To build from source.
32
33 QueueUserAPCEx by Panagiotis E. Hadjidoukas
34 To support any thread cancelation in C++ library builds or
35 to support cancelation of blocked threads in any build.
36 This library is not required otherwise.
37
38 For true async cancelation of threads (including blocked threads).
39 This is a DLL and Windows driver that provides pre-emptive APC
40 by forcing threads into an alertable state when the APC is queued.
41 Both the DLL and driver are provided with the pthreads-win32.exe
42 self-unpacking ZIP, and on the pthreads-win32 FTP site (in source
43 and pre-built forms). Currently this is a separate LGPL package to
44 pthreads-win32. See the README in the QueueUserAPCEx folder for
45 installation instructions.
46
47 Pthreads-win32 will automatically detect if the QueueUserAPCEx DLL
48 QuserEx.DLL is available and whether the driver AlertDrv.sys is
49 loaded. If it is not available, pthreads-win32 will simulate async
50 cancelation, which means that it can async cancel only threads that
51 are runnable. The simulated async cancellation cannot cancel blocked
52 threads.
53
54 [FOR SECURITY] To be found Quserex.dll MUST be installed in the
55 Windows System Folder. This is not an unreasonable constraint given a
56 driver must also be installed and loaded at system startup.
57
58
59 Library naming
60 --------------
61
62 Because the library is being built using various exception
63 handling schemes and compilers - and because the library
64 may not work reliably if these are mixed in an application,
65 each different version of the library has it's own name.
66
67 Note 1: the incompatibility is really between EH implementations
68 of the different compilers. It should be possible to use the
69 standard C version from either compiler with C++ applications
70 built with a different compiler. If you use an EH version of
71 the library, then you must use the same compiler for the
72 application. This is another complication and dependency that
73 can be avoided by using only the standard C library version.
74
75 Note 2: if you use a standard C pthread*.dll with a C++
76 application, then any functions that you define that are
77 intended to be called via pthread_cleanup_push() must be
78 __cdecl.
79
80 Note 3: the intention was to also name either the VC or GC
81 version (it should be arbitrary) as pthread.dll, including
82 pthread.lib and libpthread.a as appropriate. This is no longer
83 likely to happen.
84
85 Note 4: the compatibility number was added so that applications
86 can differentiate between binary incompatible versions of the
87 libs and dlls.
88
89 In general:
90 pthread[VG]{SE,CE,C}[c].dll
91 pthread[VG]{SE,CE,C}[c].lib
92
93 where:
94 [VG] indicates the compiler
95 V - MS VC, or
96 G - GNU C
97
98 {SE,CE,C} indicates the exception handling scheme
99 SE - Structured EH, or
100 CE - C++ EH, or
101 C - no exceptions - uses setjmp/longjmp
102
103 c - DLL compatibility number indicating ABI and API
104 compatibility with applications built against
105 a snapshot with the same compatibility number.
106 See 'Version numbering' below.
107
108 The name may also be suffixed by a 'd' to indicate a debugging version
109 of the library. E.g. pthreadVC2d.lib. Debugging versions contain
110 additional information for debugging (symbols etc) and are often not
111 optimised in any way (compiled with optimisation turned off).
112
113 Examples:
114 pthreadVSE.dll (MSVC/SEH)
115 pthreadGCE.dll (GNUC/C++ EH)
116 pthreadGC.dll (GNUC/not dependent on exceptions)
117 pthreadVC1.dll (MSVC/not dependent on exceptions - not binary
118 compatible with pthreadVC.dll)
119 pthreadVC2.dll (MSVC/not dependent on exceptions - not binary
120 compatible with pthreadVC1.dll or pthreadVC.dll)
121
122 The GNU library archive file names have correspondingly changed to:
123
124 libpthreadGCEc.a
125 libpthreadGCc.a
126
127
128 Versioning numbering
129 --------------------
130
131 Version numbering is separate from the snapshot dating system, and
132 is the canonical version identification system embedded within the
133 DLL using the Microsoft version resource system. The versioning
134 system chosen follows the GNU Libtool system. See
135 http://www.gnu.org/software/libtool/manual.html section 6.2.
136
137 See the resource file 'version.rc'.
138
139 Microsoft version numbers use 4 integers:
140
141 0.0.0.0
142
143 Pthreads-win32 uses the first 3 following the Libtool convention.
144 The fourth is commonly used for the build number, but will be reserved
145 for future use.
146
147 current.revision.age.0
148
149 The numbers are changed as follows:
150
151 1. If the library source code has changed at all since the last update,
152 then increment revision (`c:r:a' becomes `c:r+1:a').
153 2. If any interfaces have been added, removed, or changed since the last
154 update, increment current, and set revision to 0.
155 3. If any interfaces have been added since the last public release, then
156 increment age.
157 4. If any interfaces have been removed or changed since the last public
158 release, then set age to 0.
159
160
161 DLL compatibility numbering is an attempt to ensure that applications
162 always load a compatible pthreads-win32 DLL by using a DLL naming system
163 that is consistent with the version numbering system. It also allows
164 older and newer DLLs to coexist in the same filesystem so that older
165 applications can continue to be used. For pre .NET Windows systems,
166 this inevitably requires incompatible versions of the same DLLs to have
167 different names.
168
169 Pthreads-win32 has adopted the Cygwin convention of appending a single
170 integer number to the DLL name. The number used is based on the library
171 version number and is computed as 'current' - 'age'.
172
173 (See http://home.att.net/~perlspinr/libversioning.html for a nicely
174 detailed explanation.)
175
176 Using this method, DLL name/s will only change when the DLL's
177 backwards compatibility changes. Note that the addition of new
178 'interfaces' will not of itself change the DLL's compatibility for older
179 applications.
180
181
182 Which of the several dll versions to use?
183 -----------------------------------------
184 or,
185 ---
186 What are all these pthread*.dll and pthread*.lib files?
187 -------------------------------------------------------
188
189 Simple, use either pthreadGCv.* if you use GCC, or pthreadVCv.* if you
190 use MSVC - where 'v' is the DLL versioning (compatibility) number.
191
192 Otherwise, you need to choose carefully and know WHY.
193
194 The most important choice you need to make is whether to use a
195 version that uses exceptions internally, or not. There are versions
196 of the library that use exceptions as part of the thread
197 cancelation and exit implementation. The default version uses
198 setjmp/longjmp.
199
200 There is some contension amongst POSIX threads experts as
201 to how POSIX threads cancelation and exit should work
202 with languages that use exceptions, e.g. C++ and even C
203 (Microsoft's Structured Exceptions).
204
205 The issue is: should cancelation of a thread in, say,
206 a C++ application cause object destructors and C++ exception
207 handlers to be invoked as the stack unwinds during thread
208 exit, or not?
209
210 There seems to be more opinion in favour of using the
211 standard C version of the library (no EH) with C++ applications
212 for the reason that this appears to be the assumption commercial
213 pthreads implementations make. Therefore, if you use an EH version
214 of pthreads-win32 then you may be under the illusion that
215 your application will be portable, when in fact it is likely to
216 behave differently when linked with other pthreads libraries.
217
218 Now you may be asking: then why have you kept the EH versions of
219 the library?
220
221 There are a couple of reasons:
222 - there is division amongst the experts and so the code may
223 be needed in the future. Yes, it's in the repository and we
224 can get it out anytime in the future, but it would be difficult
225 to find.
226 - pthreads-win32 is one of the few implementations, and possibly
227 the only freely available one, that has EH versions. It may be
228 useful to people who want to play with or study application
229 behaviour under these conditions.
230
231 Notes:
232
233 [If you use either pthreadVCE or pthreadGCE]
234
235 1. [See also the discussion in the FAQ file - Q2, Q4, and Q5]
236
237 If your application contains catch(...) blocks in your POSIX
238 threads then you will need to replace the "catch(...)" with the macro
239 "PtW32Catch", eg.
240
241 #ifdef PtW32Catch
242 PtW32Catch {
243 ...
244 }
245 #else
246 catch(...) {
247 ...
248 }
249 #endif
250
251 Otherwise neither pthreads cancelation nor pthread_exit() will work
252 reliably when using versions of the library that use C++ exceptions
253 for cancelation and thread exit.
254
255 This is due to what is believed to be a C++ compliance error in VC++
256 whereby you may not have multiple handlers for the same exception in
257 the same try/catch block. GNU G++ doesn't have this restriction.
258
259
260 Other name changes
261 ------------------
262
263 All snapshots prior to and including snapshot 2000-08-13
264 used "_pthread_" as the prefix to library internal
265 functions, and "_PTHREAD_" to many library internal
266 macros. These have now been changed to "ptw32_" and "PTW32_"
267 respectively so as to not conflict with the ANSI standard's
268 reservation of identifiers beginning with "_" and "__" for
269 use by compiler implementations only.
270
271 If you have written any applications and you are linking
272 statically with the pthreads-win32 library then you may have
273 included a call to _pthread_processInitialize. You will
274 now have to change that to ptw32_processInitialize.
275
276
277 Cleanup code default style
278 --------------------------
279
280 Previously, if not defined, the cleanup style was determined automatically
281 from the compiler used, and one of the following was defined accordingly:
282
283 __CLEANUP_SEH MSVC only
284 __CLEANUP_CXX C++, including MSVC++, GNU G++
285 __CLEANUP_C C, including GNU GCC, not MSVC
286
287 These defines determine the style of cleanup (see pthread.h) and,
288 most importantly, the way that cancelation and thread exit (via
289 pthread_exit) is performed (see the routine ptw32_throw()).
290
291 In short, the exceptions versions of the library throw an exception
292 when a thread is canceled, or exits via pthread_exit(). This exception is
293 caught by a handler in the thread startup routine, so that the
294 the correct stack unwinding occurs regardless of where the thread
295 is when it's canceled or exits via pthread_exit().
296
297 In this snapshot, unless the build explicitly defines (e.g. via a
298 compiler option) __CLEANUP_SEH, __CLEANUP_CXX, or __CLEANUP_C, then
299 the build NOW always defaults to __CLEANUP_C style cleanup. This style
300 uses setjmp/longjmp in the cancelation and pthread_exit implementations,
301 and therefore won't do stack unwinding even when linked to applications
302 that have it (e.g. C++ apps). This is for consistency with most/all
303 commercial Unix POSIX threads implementations.
304
305 Although it was not clearly documented before, it is still necessary to
306 build your application using the same __CLEANUP_* define as was
307 used for the version of the library that you link with, so that the
308 correct parts of pthread.h are included. That is, the possible
309 defines require the following library versions:
310
311 __CLEANUP_SEH pthreadVSE.dll
312 __CLEANUP_CXX pthreadVCE.dll or pthreadGCE.dll
313 __CLEANUP_C pthreadVC.dll or pthreadGC.dll
314
315 It is recommended that you let pthread.h use it's default __CLEANUP_C
316 for both library and application builds. That is, don't define any of
317 the above, and then link with pthreadVC.lib (MSVC or MSVC++) and
318 libpthreadGC.a (MinGW GCC or G++). The reason is explained below, but
319 another reason is that the prebuilt pthreadVCE.dll is currently broken.
320 Versions built with MSVC++ later than version 6 may not be broken, but I
321 can't verify this yet.
322
323 WHY ARE WE MAKING THE DEFAULT STYLE LESS EXCEPTION-FRIENDLY?
324 Because no commercial Unix POSIX threads implementation allows you to
325 choose to have stack unwinding. Therefore, providing it in pthread-win32
326 as a default is dangerous. We still provide the choice but unless
327 you consciously choose to do otherwise, your pthreads applications will
328 now run or crash in similar ways irrespective of the pthreads platform
329 you use. Or at least this is the hope.
330
331
332 Building under VC++ using C++ EH, Structured EH, or just C
333 ----------------------------------------------------------
334
335 From the source directory run nmake without any arguments to list
336 help information. E.g.
337
338 $ nmake
339
340 Microsoft (R) Program Maintenance Utility Version 6.00.8168.0
341 Copyright (C) Microsoft Corp 1988-1998. All rights reserved.
342
343 Run one of the following command lines:
344 nmake clean VCE (to build the MSVC dll with C++ exception handling)
345 nmake clean VSE (to build the MSVC dll with structured exception handling)
346 nmake clean VC (to build the MSVC dll with C cleanup code)
347 nmake clean VCE-inlined (to build the MSVC inlined dll with C++ exception handling)
348 nmake clean VSE-inlined (to build the MSVC inlined dll with structured exception handling)
349 nmake clean VC-inlined (to build the MSVC inlined dll with C cleanup code)
350 nmake clean VC-static (to build the MSVC static lib with C cleanup code)
351 nmake clean VCE-debug (to build the debug MSVC dll with C++ exception handling)
352 nmake clean VSE-debug (to build the debug MSVC dll with structured exception handling)
353 nmake clean VC-debug (to build the debug MSVC dll with C cleanup code)
354 nmake clean VCE-inlined-debug (to build the debug MSVC inlined dll with C++ exception handling)
355 nmake clean VSE-inlined-debug (to build the debug MSVC inlined dll with structured exception handling)
356 nmake clean VC-inlined-debug (to build the debug MSVC inlined dll with C cleanup code)
357 nmake clean VC-static-debug (to build the debug MSVC static lib with C cleanup code)
358
359
360 The pre-built dlls are normally built using the *-inlined targets.
361
362 You can run the testsuite by changing to the "tests" directory and
363 running nmake. E.g.:
364
365 $ cd tests
366 $ nmake
367
368 Microsoft (R) Program Maintenance Utility Version 6.00.8168.0
369 Copyright (C) Microsoft Corp 1988-1998. All rights reserved.
370
371 Run one of the following command lines:
372 nmake clean VC (to test using VC dll with VC (no EH) applications)
373 nmake clean VCX (to test using VC dll with VC++ (EH) applications)
374 nmake clean VCE (to test using the VCE dll with VC++ EH applications)
375 nmake clean VSE (to test using VSE dll with VC (SEH) applications)
376 nmake clean VC-bench (to benchtest using VC dll with C bench app)
377 nmake clean VCX-bench (to benchtest using VC dll with C++ bench app)
378 nmake clean VCE-bench (to benchtest using VCE dll with C++ bench app)
379 nmake clean VSE-bench (to benchtest using VSE dll with SEH bench app)
380 nmake clean VC-static (to test using VC static lib with VC (no EH) applications)
381
382
383 Building under Mingw32
384 ----------------------
385
386 The dll can be built easily with recent versions of Mingw32.
387 (The distributed versions are built using Mingw32 and MsysDTK
388 from www.mingw32.org.)
389
390 From the source directory, run make for help information. E.g.:
391
392 $ make
393 Run one of the following command lines:
394 make clean GC (to build the GNU C dll with C cleanup code)
395 make clean GCE (to build the GNU C dll with C++ exception handling)
396 make clean GC-inlined (to build the GNU C inlined dll with C cleanup code)
397 make clean GCE-inlined (to build the GNU C inlined dll with C++ exception handling)
398 make clean GC-static (to build the GNU C inlined static lib with C cleanup code)
399 make clean GC-debug (to build the GNU C debug dll with C cleanup code)
400 make clean GCE-debug (to build the GNU C debug dll with C++ exception handling)
401 make clean GC-inlined-debug (to build the GNU C inlined debug dll with C cleanup code)
402 make clean GCE-inlined-debug (to build the GNU C inlined debug dll with C++ exception handling)
403 make clean GC-static-debug (to build the GNU C inlined static debug lib with C cleanup code)
404
405
406 The pre-built dlls are normally built using the *-inlined targets.
407
408 You can run the testsuite by changing to the "tests" directory and
409 running make for help information. E.g.:
410
411 $ cd tests
412 $ make
413 Run one of the following command lines:
414 make clean GC (to test using GC dll with C (no EH) applications)
415 make clean GCX (to test using GC dll with C++ (EH) applications)
416 make clean GCE (to test using GCE dll with C++ (EH) applications)
417 make clean GC-bench (to benchtest using GNU C dll with C cleanup code)
418 make clean GCE-bench (to benchtest using GNU C dll with C++ exception handling)
419 make clean GC-static (to test using GC static lib with C (no EH) applications)
420
421
422 Building under Linux using the Mingw32 cross development tools
423 --------------------------------------------------------------
424
425 You can build the library without leaving Linux by using the Mingw32 cross
426 development toolchain. See http://www.libsdl.org/extras/win32/cross/ for
427 tools and info. The GNUmakefile contains some support for this, for example:
428
429 make CROSS=i386-mingw32msvc- clean GC-inlined
430
431 will build pthreadGCn.dll and libpthreadGCn.a (n=version#), provided your
432 cross-tools/bin directory is in your PATH (or use the cross-make.sh script
433 at the URL above).
434
435
436 Building the library as a statically linkable library
437 -----------------------------------------------------
438
439 General: PTW32_STATIC_LIB must be defined for both the library build and the
440 application build. The makefiles supplied and used by the following 'make'
441 command lines will define this for you.
442
443 MSVC (creates pthreadVCn.lib as a static link lib):
444
445 nmake clean VC-static
446
447
448 MinGW32 (creates libpthreadGCn.a as a static link lib):
449
450 make clean GC-static
451
452
453 Define PTW32_STATIC_LIB when building your application. Also, your
454 application must call a two non-portable routines to initialise the
455 some state on startup and cleanup before exit. One other routine needs
456 to be called to cleanup after any Win32 threads have called POSIX API
457 routines. See README.NONPORTABLE or the html reference manual pages for
458 details on these routines:
459
460 BOOL pthread_win32_process_attach_np (void);
461 BOOL pthread_win32_process_detach_np (void);
462 BOOL pthread_win32_thread_attach_np (void); // Currently a no-op
463 BOOL pthread_win32_thread_detach_np (void);
464
465
466 The tests makefiles have the same targets but only check that the
467 static library is statically linkable. They don't run the full
468 testsuite. To run the full testsuite, build the dlls and run the
469 dll test targets.
470
471
472 Building the library under Cygwin
473 ---------------------------------
474
475 Cygwin is implementing it's own POSIX threads routines and these
476 will be the ones to use if you develop using Cygwin.
477
478
479 Ready to run binaries
480 ---------------------
481
482 For convenience, the following ready-to-run files can be downloaded
483 from the FTP site (see under "Availability" below):
484
485 pthread.h
486 semaphore.h
487 sched.h
488 pthreadVC.dll - built with MSVC compiler using C setjmp/longjmp
489 pthreadVC.lib
490 pthreadVCE.dll - built with MSVC++ compiler using C++ EH
491 pthreadVCE.lib
492 pthreadVSE.dll - built with MSVC compiler using SEH
493 pthreadVSE.lib
494 pthreadGC.dll - built with Mingw32 GCC
495 libpthreadGC.a - derived from pthreadGC.dll
496 pthreadGCE.dll - built with Mingw32 G++
497 libpthreadGCE.a - derived from pthreadGCE.dll
498
499 As of August 2003 pthreads-win32 pthreadG* versions are built and tested
500 using the MinGW + MsysDTK environment current as of that date or later.
501 The following file MAY be needed for older MinGW environments.
502
503 gcc.dll - needed to build and run applications that use
504 pthreadGCE.dll.
505
506
507 Building applications with GNU compilers
508 ----------------------------------------
509
510 If you're using pthreadGC.dll:
511
512 With the three header files, pthreadGC.dll and libpthreadGC.a in the
513 same directory as your application myapp.c, you could compile, link
514 and run myapp.c under Mingw32 as follows:
515
516 gcc -o myapp.exe myapp.c -I. -L. -lpthreadGC
517 myapp
518
519 Or put pthreadGC.dll in an appropriate directory in your PATH,
520 put libpthreadGC.a in your system lib directory, and
521 put the three header files in your system include directory,
522 then use:
523
524 gcc -o myapp.exe myapp.c -lpthreadGC
525 myapp
526
527
528 If you're using pthreadGCE.dll:
529
530 With the three header files, pthreadGCE.dll, gcc.dll and libpthreadGCE.a
531 in the same directory as your application myapp.c, you could compile,
532 link and run myapp.c under Mingw32 as follows:
533
534 gcc -x c++ -o myapp.exe myapp.c -I. -L. -lpthreadGCE
535 myapp
536
537 Or put pthreadGCE.dll and gcc.dll in an appropriate directory in
538 your PATH, put libpthreadGCE.a in your system lib directory, and
539 put the three header files in your system include directory,
540 then use:
541
542 gcc -x c++ -o myapp.exe myapp.c -lpthreadGCE
543 myapp
544
545
546 Availability
547 ------------
548
549 The complete source code in either unbundled, self-extracting
550 Zip file, or tar/gzipped format can be found at:
551
552 ftp://sources.redhat.com/pub/pthreads-win32
553
554 The pre-built DLL, export libraries and matching pthread.h can
555 be found at:
556
557 ftp://sources.redhat.com/pub/pthreads-win32/dll-latest
558
559 Home page:
560
561 http://sources.redhat.com/pthreads-win32/
562
563
564 Mailing list
565 ------------
566
567 There is a mailing list for discussing pthreads on Win32.
568 To join, send email to:
569
570 pthreads-win32-subscribe (a] sources.redhat.com
571
572 Unsubscribe by sending mail to:
573
574 pthreads-win32-unsubscribe (a] sources.redhat.com
575
576
577 Acknowledgements
578 ----------------
579
580 See the ANNOUNCE file for acknowledgements.
581 See the 'CONTRIBUTORS' file for the list of contributors.
582
583 As much as possible, the ChangeLog file attributes
584 contributions and patches that have been incorporated
585 in the library to the individuals responsible.
586
587 Finally, thanks to all those who work on and contribute to the
588 POSIX and Single Unix Specification standards. The maturity of an
589 industry can be measured by it's open standards.
590
591 ----
592 Ross Johnson
593 <rpj (a] callisto.canberra.edu.au>
594
595
596
597
598
599
600
601
602