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