ViewVC logotype

Contents of /trunk/3rdparty/w32pthreads/README

Parent Directory Parent Directory | Revision Log Revision Log

Revision 31 - (show annotations) (download)
Tue Sep 7 03:24:11 2010 UTC (9 years, 11 months ago) by william
File size: 22520 byte(s)
committing r3113 initial commit again...
2 ==============
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.
10 What is it?
11 -----------
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).
23 See the file "ANNOUNCE" for more information including standards
24 conformance details and the list of supported and unsupported
25 routines.
28 Prerequisites
29 -------------
30 MSVC or GNU C (MinGW32 MSys development kit)
31 To build from source.
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.
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.
51 Library naming
52 --------------
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.
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.
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.
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.
77 Note 4: the compatibility number was added so that applications
78 can differentiate between binary incompatible versions of the
79 libs and dlls.
81 In general:
82 pthread[VG]{SE,CE,C}c.dll
83 pthread[VG]{SE,CE,C}c.lib
85 where:
86 [VG] indicates the compiler
87 V - MS VC, or
88 G - GNU C
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
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.
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).
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)
114 The GNU library archive file names have correspondingly changed to:
116 libpthreadGCEc.a
117 libpthreadGCc.a
120 Versioning numbering
121 --------------------
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.
129 See the resource file 'version.rc'.
131 Microsoft version numbers use 4 integers:
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.
139 current.revision.age.0
141 The numbers are changed as follows:
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.
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.
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'.
165 (See http://home.att.net/~perlspinr/libversioning.html for a nicely
166 detailed explanation.)
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.
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 -------------------------------------------------------
181 Simple, use either pthreadGCv.* if you use GCC, or pthreadVCv.* if you
182 use MSVC - where 'v' is the DLL versioning (compatibility) number.
184 Otherwise, you need to choose carefully and know WHY.
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.
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).
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?
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.
210 Now you may be asking: then why have you kept the EH versions of
211 the library?
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.
223 Notes:
225 [If you use either pthreadVCE or pthreadGCE]
227 1. [See also the discussion in the FAQ file - Q2, Q4, and Q5]
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.
233 #ifdef PtW32Catch
234 PtW32Catch {
235 ...
236 }
237 #else
238 catch(...) {
239 ...
240 }
241 #endif
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.
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.
252 Other name changes
253 ------------------
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.
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.
269 Cleanup code default style
270 --------------------------
272 Previously, if not defined, the cleanup style was determined automatically
273 from the compiler used, and one of the following was defined accordingly:
276 __CLEANUP_CXX C++, including MSVC++, GNU G++
277 __CLEANUP_C C, including GNU GCC, not MSVC
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()).
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().
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.
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:
303 __CLEANUP_SEH pthreadVSE.dll
304 __CLEANUP_CXX pthreadVCE.dll or pthreadGCE.dll
305 __CLEANUP_C pthreadVC.dll or pthreadGC.dll
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.
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.
324 Building under VC++ using C++ EH, Structured EH, or just C
325 ----------------------------------------------------------
327 From the source directory run nmake without any arguments to list
328 help information. E.g.
330 $ nmake
332 Microsoft (R) Program Maintenance Utility Version 6.00.8168.0
333 Copyright (C) Microsoft Corp 1988-1998. All rights reserved.
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)
352 The pre-built dlls are normally built using the *-inlined targets.
354 You can run the testsuite by changing to the "tests" directory and
355 running nmake. E.g.:
357 $ cd tests
358 $ nmake
360 Microsoft (R) Program Maintenance Utility Version 6.00.8168.0
361 Copyright (C) Microsoft Corp 1988-1998. All rights reserved.
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)
375 Building under Mingw32
376 ----------------------
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.)
382 From the source directory, run make for help information. E.g.:
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)
398 The pre-built dlls are normally built using the *-inlined targets.
400 You can run the testsuite by changing to the "tests" directory and
401 running make for help information. E.g.:
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)
414 Building under Linux using the Mingw32 cross development tools
415 --------------------------------------------------------------
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:
421 make CROSS=i386-mingw32msvc- clean GC-inlined
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).
428 Building the library as a statically linkable library
429 -----------------------------------------------------
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.
435 MSVC (creates pthreadVCn.lib as a static link lib):
437 nmake clean VC-static
440 MinGW32 (creates libpthreadGCn.a as a static link lib):
442 make clean GC-static
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:
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);
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.
464 Building the library under Cygwin
465 ---------------------------------
467 Cygwin is implementing it's own POSIX threads routines and these
468 will be the ones to use if you develop using Cygwin.
471 Ready to run binaries
472 ---------------------
474 For convenience, the following ready-to-run files can be downloaded
475 from the FTP site (see under "Availability" below):
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
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.
495 gcc.dll - needed to build and run applications that use
496 pthreadGCE.dll.
499 Building applications with GNU compilers
500 ----------------------------------------
502 If you're using pthreadGC.dll:
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:
508 gcc -o myapp.exe myapp.c -I. -L. -lpthreadGC
509 myapp
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:
516 gcc -o myapp.exe myapp.c -lpthreadGC
517 myapp
520 If you're using pthreadGCE.dll:
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:
526 gcc -x c++ -o myapp.exe myapp.c -I. -L. -lpthreadGCE
527 myapp
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:
534 gcc -x c++ -o myapp.exe myapp.c -lpthreadGCE
535 myapp
538 Availability
539 ------------
541 The complete source code in either unbundled, self-extracting
542 Zip file, or tar/gzipped format can be found at:
544 ftp://sources.redhat.com/pub/pthreads-win32
546 The pre-built DLL, export libraries and matching pthread.h can
547 be found at:
549 ftp://sources.redhat.com/pub/pthreads-win32/dll-latest
551 Home page:
553 http://sources.redhat.com/pthreads-win32/
556 Mailing list
557 ------------
559 There is a mailing list for discussing pthreads on Win32.
560 To join, send email to:
562 pthreads-win32-subscribe@sources.redhat.com
564 Unsubscribe by sending mail to:
566 pthreads-win32-unsubscribe@sources.redhat.com
569 Acknowledgements
570 ----------------
572 See the ANNOUNCE file for acknowledgements.
573 See the 'CONTRIBUTORS' file for the list of contributors.
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.
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.
583 ----
584 Ross Johnson
585 <rpj@callisto.canberra.edu.au>

  ViewVC Help
Powered by ViewVC 1.1.22