/[pcsx2_0.9.7]/trunk/3rdparty/w32pthreads/README
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...
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>

  ViewVC Help
Powered by ViewVC 1.1.22