diff options
| author | rpj <rpj> | 2001-06-05 07:48:19 +0000 |
|---|---|---|
| committer | rpj <rpj> | 2001-06-05 07:48:19 +0000 |
| commit | b77a92d5dbb0147c8dd872c0be8f4fe73a750490 (patch) | |
| tree | 69e6c711d510a6c505cb6b26dceab6588f392403 /README | |
| parent | 1451ff5c2051b5cadf84bd8e965dcda757101b13 (diff) | |
* nonportable.c (pthread_mutex_setdefaultkind_np):
Remove - should not have been included in the first place.
(pthread_mutex_getdefaultkind_np): Likewise.
* global.c (ptw32_mutex_default_kind): Likewise.
* mutex.c (pthread_mutex_init): Remove use of
ptw32_mutex_default_kind.
* pthread.h (pthread_mutex_setdefaultkind_np): Likewise.
(pthread_mutex_getdefaultkind_np): Likewise.
* pthread.def (pthread_mutexattr_setkind_np): Added.
(pthread_mutexattr_getkind_np): Likewise.
* README: Many changes that should have gone in before
the last snapshot.
* README.NONPORTABLE: New - referred to by ANNOUNCE
but never created; documents the non-portable routines
included in the library - moved from README with new
routines added.
* ANNOUNCE (pthread_mutexattr_setkind_np): Added to
compliance list.
(pthread_mutexattr_getkind_np): Likewise.
Diffstat (limited to 'README')
| -rw-r--r-- | README | 267 |
1 files changed, 95 insertions, 172 deletions
@@ -9,11 +9,13 @@ and conditions. What is it?
-----------
-Pthreads-win32 is an Open Source Software (OSS) implementation of the
+Pthreads-win32 is an Open Source Software implementation of the
Threads component of the POSIX 1003.1c 1995 Standard for Microsoft's
Win32 environment. Some functions from POSIX 1003.1b are also
supported including semaphores. Other related functions include
-the set of read-write lock functions.
+the set of read-write lock functions. The library also supports
+some of the functionality of the Open Group's Single Unix
+specification, version 2, namely mutex types.
See the file "ANNOUNCE" for more information including standards
conformance details and list of supported routines.
@@ -28,25 +30,28 @@ will not work reliably if these are mixed in an application, each different version of the library has it's own name.
In general:
- pthread[VG][SC]E.dll
- pthread[VG][SC]E.lib
+ pthread[VG]{SE,CE,C}.dll
+ pthread[VG]{SE,CE,C}.lib
where:
[VG] indicates the compiler
- V - MS VC++
- G - GNU G++
+ V - MS VC
+ G - GNU C
- [SC] indicates the exception handling scheme
- S - Structured EH
- C - C++ EH
+ {SE,CE,C} indicates the exception handling scheme
+ SE - Structured EH
+ CE - C++ EH
+ C - no exceptions - uses setjmp/longjmp
For example:
- pthreadVSE.dll (VC++/SEH)
- pthreadGCE.dll (G++/C++ EH)
+ pthreadVSE.dll (MSVC/SEH)
+ pthreadGCE.dll (GNUC/C++ EH)
+ pthreadGC.dll (GNUC/not dependent on exceptions)
-The GNU library archive file name has changed to:
+The GNU library archive file names have changed to:
- libpthreadw32.a (the "32" is now "w32")
+ libpthreadGCE.a
+ libpthreadGC.a
Other name changes
@@ -66,150 +71,8 @@ included a call to _pthread_processInitialize. You will now have to change that to ptw32_processInitialize.
-Known bugs in this snapshot
----------------------------
-
-1. Asynchronous cancelation only works on Intel X86 machines.
-
-
-Caveats
--------
-
-1. Due to what is believed to be C++ compliance error in VC++,
-if your application contains catch(...) blocks in your POSIX threads
-then you will need to replace the "catch(...)" with the macro
-"PtW32Catch", eg.
-
- #ifdef PtW32Catch
- PtW32Catch {
- ...
- }
- #else
- catch(...) {
- ...
- }
- #endif
-
-Otherwise neither pthreads cancelation nor pthread_exit() will work
-reliably.
-
-
-Non-portable functions included in the library
-----------------------------------------------
-
-void
-pthread_mutexattr_setforcecs_np(pthread_mutexattr_t *attr,
- int forcecs);
-
- Allows an application to force the library to use
- critical sections rather than win32 mutexes as
- the basis for any mutex that uses "attr".
- Critical sections are significantly faster than
- mutexes.
-
- Values for "forcecs" are:
- PTHREAD_MUTEX_AUTO_CS_NP
- - allow the library to decide based on
- availability of tryEnterCriticalSection().
- The library determines this at runtime
- and will use critical sections whenever
- tryEnterCriticalSection() is available.
- PTHREAD_MUTEX_FORCE_CS_NP
- - force use of critical sections even if
- tryEnterCriticalSection() isn't provided
- by the system, but you'd better not try
- to use pthread_mutex_trylock() on any
- mutex that uses "attr" if you want your
- application to work on all versions of
- Windows.
-
-HANDLE
-pthread_getw32threadhandle_np(pthread_t thread);
-
- Returns the win32 thread handle that the POSIX
- thread "thread" is running as.
-
- Applications can use the win32 handle to set
- win32 specific attributes of the thread.
-
-int
-pthread_delay_np (const struct timespec *interval);
-
- This routine causes a thread to delay execution for a specific period of time.
- This period ends at the current time plus the specified interval. The routine
- will not return before the end of the period is reached, but may return an
- arbitrary amount of time after the period has gone by. This can be due to
- system load, thread priorities, and system timer granularity.
-
- Specifying an interval of zero (0) seconds and zero (0) nanoseconds is
- allowed and can be used to force the thread to give up the processor or to
- deliver a pending cancelation request.
-
- This routine is a cancelation point.
-
- The timespec structure contains the following two fields:
-
- tv_sec is an integer number of seconds.
- tv_nsec is an integer number of nanoseconds.
-
- Return Values
-
- If an error condition occurs, this routine returns an integer value
- indicating the type of error. Possible return values are as follows:
-
- 0 Successful completion.
- [EINVAL] The value specified by interval is invalid.
-
-
-BOOL
-pthread_win32_process_attach_np (void);
-
-BOOL
-pthread_win32_process_detach_np (void);
-
-BOOL
-pthread_win32_thread_attach_np (void);
-
-BOOL
-pthread_win32_thread_detach_np (void);
-
- These functions contain the code normally run via dllMain
- when the library is used as a dll but which need to be
- called explicitly by an application when the library
- is statically linked.
-
- You will need to call pthread_win32_process_attach_np() before
- you can call any pthread routines when statically linking.
- You should call pthread_win32_process_detach_np() before
- exiting your application to clean up.
-
- pthread_win32_thread_attach_np() is currently a no-op, but
- pthread_win32_thread_detach_np() is needed to clean up
- after Win32 threads that have called pthreads routines
- have exited.
-
- These functions invariably return TRUE except for
- pthread_win32_process_attach_np() which will return FALSE
- if pthreads-win32 initialisation fails.
-
-
-int
-pthreadCancelableWait (HANDLE waitHandle);
-
-int
-pthreadCancelableTimedWait (HANDLE waitHandle, DWORD timeout);
-
- These two functions provide hooks into the pthread_cancel
- mechanism that will allow you to wait on a Windows handle
- and make it a cancellation point. Both functions block
- until either the given w32 handle is signaled, or
- pthread_cancel has been called. It is implemented using
- WaitForMultipleObjects on 'waitHandle' and a manually
- reset w32 event used to implement pthread_cancel.
-
-
-Building under VC++ using either C++ EH or Structured EH
---------------------------------------------------------
+Building under VC++ using C++ EH, Structured EH, or just C
+----------------------------------------------------------
From the source directory run one of the following:
@@ -219,6 +82,10 @@ or: nmake clean VSE (builds the VC++ structured EH version pthreadVSE.dll)
+or:
+
+nmake clean VC (builds the VC setjmp/longjmp version of pthreadVC.dll)
+
You can run the testsuite by changing to the "tests" directory and
running the target corresponding to the DLL version you built:
@@ -228,19 +95,33 @@ or: nmake clean VSE
+or:
+
+nmake clean VC
+
Building under Mingw32
----------------------
The dll can be built with Mingw32 gcc-2.95.2-1 after you've
made the changes to Mingw32 desribed in Question 6 of the FAQ.
-Hopefully versions after gcc-2.95.2-1 won't require the fix.
-Run "make" in the source directory (uses GNUmakefile). This builds
-pthreadGCE.dll and libpthreadw32.a.
+From the source directory, run
+
+make clean GCE
+
+or:
+
+make clean GC
You can run the testsuite by changing to the "tests" directory and
-running "make clean" and then "make".
+running
+
+make clean GCE
+
+or:
+
+make clean GC
Building the library under Cygwin
@@ -265,10 +146,16 @@ from the FTP site (see under "Availability" below): pthread.def
pthreadVCE.dll - built with MSVC++ compiler using C++ EH
pthreadVCE.lib
+ pthreadVC.dll - built with MSVC compiler using C setjmp/longjmp
+ pthreadVC.lib
pthreadVSE.dll - built with MSVC compiler using SEH
pthreadVSE.lib
pthreadGCE.dll - built with Mingw32 G++
- libpthreadw32.a - derived from pthreadGCE.dll
+ pthreadGCE.a - derived from pthreadGCE.dll
+ pthreadGC.dll - built with Mingw32 GCC
+ pthreadGC.a - derived from pthreadGC.dll
+ gcc.dll - needed to build and run applications that use
+ pthreadGCE.dll.
Building applications with the library
@@ -279,24 +166,46 @@ that you use in your application, or specifically, in your POSIX threads. Don't mix them or neither thread cancelation nor
pthread_exit() will work reliably if at all.
+If in doubt use the C (no-exceptions) versions of the library.
+
Building applications with GNU compilers
----------------------------------------
+If you're using pthreadGCE.dll:
+
Use gcc-2.95.2-1 or later modified as per pthreads-win32 FAQ question 6.
-With pthreadGCE.dll and libpthreadw32.a in the same directory as your
-application myapp.c, you could compile, link and run myapp.c under
-Mingw32 as follows:
+With the three header files, pthreadGCE.dll, gcc.dll and libpthreadGCE.a
+in the same directory as your application myapp.c, you could compile,
+link and run myapp.c under Mingw32 as follows:
+
+ gcc -x c++ -o myapp.exe myapp.c -I. -L. -lpthreadGCE
+ myapp
+
+Or put pthreadGCE.dll and gcc.dll in an appropriate directory in
+your PATH, put libpthreadGCE.a in MINGW_ROOT\i386-mingw32\lib, and
+put the three header files in MINGW_ROOT\i386-mingw32\include,
+then use:
+
+ gcc -x c++ -o myapp.exe myapp.c -lpthreadGCE
+ myapp
+
+If you're using pthreadGC.dll:
+
+With the three header files, pthreadGC.dll and libpthreadGC.a in the
+same directory as your application myapp.c, you could compile, link
+and run myapp.c under Mingw32 as follows:
- gcc -x c++ -o myapp.exe myapp.c -I. -L. -lpthreadw32
+ gcc -o myapp.exe myapp.c -I. -L. -lpthreadGC
myapp
-Or put pthreadGCE.dll in an appropriate directory in your PATH,
-put libpthread32.a in MINGW_ROOT\i386-mingw32\lib, and
-put pthread.h in MINGW_ROOT\i386-mingw32\include, then use:
+Or put pthreadGC.dll in an appropriate directory in your PATH,
+put libpthreadGC.a in MINGW_ROOT\i386-mingw32\lib, and
+put the three header files in MINGW_ROOT\i386-mingw32\include,
+then use:
- gcc -x c++ -o myapp.exe myapp.c -lpthreadw32
+ gcc -o myapp.exe myapp.c -lpthreadGC
myapp
@@ -335,12 +244,26 @@ Acknowledgements ----------------
Pthreads-win32 is based substantially on a Win32 Pthreads
-implementation contributed by John E. Bossom <jebossom@cognos.com>.
-Many others have contributed important new code and bug fixes.
+implementation contributed by John E. Bossom.
+Many others have contributed important new code,
+improvements and bug fixes. Thanks go to Alexander Terekhov
+and Louis Thomas for their improvements to the implementation
+of condition variables.
See the 'CONTRIBUTORS' file for the list of contributors.
+As much as possible, the ChangeLog file also attributes
+contributions and patches that have been incorporated
+in the library.
+
----
Ross Johnson
<rpj@ise.canberra.edu.au>
+
+
+
+
+
+
+
|