mingw/pthreads-win32-README

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