1PTHREADS-WIN32 RELEASE 2.9.0 (2012-05-25) 2----------------------------------------- 3Web Site: http://sourceware.org/pthreads-win32/ 4FTP Site: ftp://sourceware.org/pub/pthreads-win32 5Maintainer: Ross Johnson <ross.johnson@loungebythelake.net> 6 7 8We are pleased to announce the availability of a new release of 9Pthreads-win32, an Open Source Software implementation of the 10Threads component of the POSIX 1003.1 2001 Standard for Microsoft's 11Win32 environment. Some functions from other sections of POSIX 121003.1 2001 are also supported including semaphores and scheduling 13functions. 14 15Some common non-portable functions are also implemented for 16additional compatibility, as are a few functions specific 17to pthreads-win32 for easier integration with Win32 applications. 18 19Pthreads-win32 is free software, distributed under the GNU Lesser 20General Public License (LGPL). 21 22 23Acknowledgements 24---------------- 25This library is based originally on a Win32 pthreads 26implementation contributed by John Bossom. 27 28The implementation of Condition Variables uses algorithms developed 29by Alexander Terekhov and Louis Thomas. 30 31The implementation of POSIX mutexes has been improved by Thomas Pfaff 32and later by Alexander Terekhov. 33 34The implementation of Spinlocks and Barriers was contributed 35by Ross Johnson. 36 37The implementation of read/write locks was contributed by 38Aurelio Medina and improved by Alexander Terekhov. 39 40Many others have contributed significant time and effort to solve crutial 41problems in order to make the library workable, robust and reliable. 42 43Thanks to Xavier Leroy for granting permission to use and modify his 44LinuxThreads manual pages. 45 46Thanks to The Open Group for making the Single Unix Specification 47publicly available - many of the manual pages included in the package 48were extracted from it. 49 50There is also a separate CONTRIBUTORS file. This file and others are 51on the web site: 52 53 http://sourceware.org/pthreads-win32 54 55As much as possible, the ChangeLog file acknowledges contributions to the 56code base in more detail. 57 58 59Changes since the last release 60------------------------------ 61These are now documented in the NEWS file. 62See the ChangeLog file also. 63 64 65Known Bugs 66---------- 67These are now documented in the BUGS file. 68 69 70Level of standards conformance 71------------------------------ 72 73The following POSIX 1003.1 2001 options are defined and set to 200112L: 74 75 _POSIX_THREADS 76 _POSIX_THREAD_SAFE_FUNCTIONS 77 _POSIX_THREAD_ATTR_STACKSIZE 78 _POSIX_THREAD_PRIORITY_SCHEDULING 79 _POSIX_SEMAPHORES 80 _POSIX_READER_WRITER_LOCKS 81 _POSIX_SPIN_LOCKS 82 _POSIX_BARRIERS 83 84 85The following POSIX 1003.1 2001 options are defined and set to -1: 86 87 _POSIX_THREAD_ATTR_STACKADDR 88 _POSIX_THREAD_PRIO_INHERIT 89 _POSIX_THREAD_PRIO_PROTECT 90 _POSIX_THREAD_PROCESS_SHARED 91 92 93The following POSIX 1003.1 2001 limits are defined and set: 94 95 _POSIX_THREAD_THREADS_MAX 96 _POSIX_SEM_VALUE_MAX 97 _POSIX_SEM_NSEMS_MAX 98 _POSIX_THREAD_KEYS_MAX 99 _POSIX_THREAD_DESTRUCTOR_ITERATIONS 100 PTHREAD_STACK_MIN 101 PTHREAD_THREADS_MAX 102 SEM_VALUE_MAX 103 SEM_NSEMS_MAX 104 PTHREAD_KEYS_MAX 105 PTHREAD_DESTRUCTOR_ITERATIONS 106 107 108The following functions are implemented: 109 110 --------------------------- 111 PThreads 112 --------------------------- 113 pthread_attr_init 114 pthread_attr_destroy 115 pthread_attr_getdetachstate 116 pthread_attr_getstackaddr 117 pthread_attr_getstacksize 118 pthread_attr_setdetachstate 119 pthread_attr_setstackaddr 120 pthread_attr_setstacksize 121 122 pthread_create 123 pthread_detach 124 pthread_equal 125 pthread_exit 126 pthread_join 127 pthread_once 128 pthread_self 129 130 pthread_cancel 131 pthread_cleanup_pop 132 pthread_cleanup_push 133 pthread_setcancelstate 134 pthread_setcanceltype 135 pthread_testcancel 136 137 --------------------------- 138 Thread Specific Data 139 --------------------------- 140 pthread_key_create 141 pthread_key_delete 142 pthread_setspecific 143 pthread_getspecific 144 145 --------------------------- 146 Mutexes 147 --------------------------- 148 pthread_mutexattr_init 149 pthread_mutexattr_destroy 150 pthread_mutexattr_getpshared 151 pthread_mutexattr_setpshared 152 pthread_mutexattr_gettype 153 pthread_mutexattr_settype (types: PTHREAD_MUTEX_DEFAULT 154 PTHREAD_MUTEX_NORMAL 155 PTHREAD_MUTEX_ERRORCHECK 156 PTHREAD_MUTEX_RECURSIVE ) 157 pthread_mutexattr_getrobust 158 pthread_mutexattr_setrobust (values: PTHREAD_MUTEX_STALLED 159 PTHREAD_MUTEX_ROBUST) 160 pthread_mutex_init 161 pthread_mutex_destroy 162 pthread_mutex_lock 163 pthread_mutex_trylock 164 pthread_mutex_timedlock 165 pthread_mutex_unlock 166 pthread_mutex_consistent 167 168 --------------------------- 169 Condition Variables 170 --------------------------- 171 pthread_condattr_init 172 pthread_condattr_destroy 173 pthread_condattr_getpshared 174 pthread_condattr_setpshared 175 176 pthread_cond_init 177 pthread_cond_destroy 178 pthread_cond_wait 179 pthread_cond_timedwait 180 pthread_cond_signal 181 pthread_cond_broadcast 182 183 --------------------------- 184 Read/Write Locks 185 --------------------------- 186 pthread_rwlock_init 187 pthread_rwlock_destroy 188 pthread_rwlock_tryrdlock 189 pthread_rwlock_trywrlock 190 pthread_rwlock_rdlock 191 pthread_rwlock_timedrdlock 192 pthread_rwlock_rwlock 193 pthread_rwlock_timedwrlock 194 pthread_rwlock_unlock 195 pthread_rwlockattr_init 196 pthread_rwlockattr_destroy 197 pthread_rwlockattr_getpshared 198 pthread_rwlockattr_setpshared 199 200 --------------------------- 201 Spin Locks 202 --------------------------- 203 pthread_spin_init 204 pthread_spin_destroy 205 pthread_spin_lock 206 pthread_spin_unlock 207 pthread_spin_trylock 208 209 --------------------------- 210 Barriers 211 --------------------------- 212 pthread_barrier_init 213 pthread_barrier_destroy 214 pthread_barrier_wait 215 pthread_barrierattr_init 216 pthread_barrierattr_destroy 217 pthread_barrierattr_getpshared 218 pthread_barrierattr_setpshared 219 220 --------------------------- 221 Semaphores 222 --------------------------- 223 sem_init 224 sem_destroy 225 sem_post 226 sem_wait 227 sem_trywait 228 sem_timedwait 229 sem_getvalue (# free if +ve, # of waiters if -ve) 230 sem_open (returns an error ENOSYS) 231 sem_close (returns an error ENOSYS) 232 sem_unlink (returns an error ENOSYS) 233 234 --------------------------- 235 RealTime Scheduling 236 --------------------------- 237 pthread_attr_getschedparam 238 pthread_attr_setschedparam 239 pthread_attr_getinheritsched 240 pthread_attr_setinheritsched 241 pthread_attr_getschedpolicy (only supports SCHED_OTHER) 242 pthread_attr_setschedpolicy (only supports SCHED_OTHER) 243 pthread_getschedparam 244 pthread_setschedparam 245 pthread_getconcurrency 246 pthread_setconcurrency 247 pthread_attr_getscope 248 pthread_attr_setscope (only supports PTHREAD_SCOPE_SYSTEM) 249 sched_get_priority_max 250 sched_get_priority_min 251 sched_rr_get_interval (returns an error ENOTSUP) 252 sched_setscheduler (only supports SCHED_OTHER) 253 sched_getscheduler (only supports SCHED_OTHER) 254 sched_yield 255 256 --------------------------- 257 Signals 258 --------------------------- 259 pthread_sigmask 260 pthread_kill (only supports zero sig value, 261 for thread validity checking) 262 263 --------------------------- 264 Non-portable routines (see the README.NONPORTABLE file for usage) 265 --------------------------- 266 pthread_getw32threadhandle_np 267 pthread_timechange_handler_np 268 pthread_delay_np 269 pthread_getunique_np 270 pthread_mutexattr_getkind_np 271 pthread_mutexattr_setkind_np (types: PTHREAD_MUTEX_FAST_NP, 272 PTHREAD_MUTEX_ERRORCHECK_NP, 273 PTHREAD_MUTEX_RECURSIVE_NP, 274 PTHREAD_MUTEX_ADAPTIVE_NP, 275 PTHREAD_MUTEX_TIMED_NP) 276 pthread_num_processors_np 277 (The following four routines may be required when linking statically. 278 The process_* routines should not be needed for MSVC or GCC.) 279 pthread_win32_process_attach_np 280 pthread_win32_process_detach_np 281 (The following routines should only be needed to manage implicit 282 POSIX handles i.e. when Win native threads call POSIX thread routines 283 (other than pthread_create)) 284 pthread_win32_thread_attach_np 285 pthread_win32_thread_detach_np 286 287 --------------------------- 288 Static Initializers 289 --------------------------- 290 PTHREAD_ONCE_INIT 291 PTHREAD_MUTEX_INITIALIZER 292 PTHREAD_RECURSIVE_MUTEX_INITIALIZER 293 PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP 294 PTHREAD_ERRORCHECK_MUTEX_INITIALIZER 295 PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP 296 PTHREAD_COND_INITIALIZER 297 PTHREAD_RWLOCK_INITIALIZER 298 PTHREAD_SPINLOCK_INITIALIZER 299 300 301The library includes two non-API functions for creating cancellation 302points in applications and libraries: 303 304 pthreadCancelableWait 305 pthreadCancelableTimedWait 306 307 308The following functions are not implemented: 309 310 --------------------------- 311 RealTime Scheduling 312 --------------------------- 313 pthread_mutex_getprioceiling 314 pthread_mutex_setprioceiling 315 pthread_mutex_attr_getprioceiling 316 pthread_mutex_attr_getprotocol 317 pthread_mutex_attr_setprioceiling 318 pthread_mutex_attr_setprotocol 319 320 --------------------------- 321 Fork Handlers 322 --------------------------- 323 pthread_atfork 324 325 --------------------------- 326 Stdio 327 --------------------------- 328 flockfile 329 ftrylockfile 330 funlockfile 331 getc_unlocked 332 getchar_unlocked 333 putc_unlocked 334 putchar_unlocked 335 336 --------------------------- 337 Thread-Safe C Runtime Library 338 --------------------------- 339 readdir_r 340 getgrgid_r 341 getgrnam_r 342 getpwuid_r 343 getpwnam_r 344 345 --------------------------- 346 Signals 347 --------------------------- 348 sigtimedwait 349 sigwait 350 sigwaitinfo 351 352 --------------------------- 353 General 354 --------------------------- 355 sysconf 356 357 --------------------------- 358 Thread-Safe C Runtime Library (macros) 359 --------------------------- 360 strtok_r 361 asctime_r 362 ctime_r 363 gmtime_r 364 localtime_r 365 rand_r 366 367 368Availability 369------------ 370 371The prebuilt DLL, export libs (for both MSVC and Mingw32), and the header 372files (pthread.h, semaphore.h, sched.h) are available along with the 373complete source code. 374 375The source code can be found at: 376 377 ftp://sources.redhat.com/pub/pthreads-win32 378 379and as individual source code files at 380 381 ftp://sources.redhat.com/pub/pthreads-win32/source 382 383The pre-built DLL, export libraries and include files can be found at: 384 385 ftp://sources.redhat.com/pub/pthreads-win32/dll-latest 386 387 388 389Mailing List 390------------ 391 392There is a mailing list for discussing pthreads on Win32. To join, 393send email to: 394 395 pthreads-win32-subscribe@sourceware.cygnus.com 396 397 398Application Development Environments 399------------------------------------ 400 401See the README file for more information. 402 403MSVC: 404MSVC using SEH works. Distribute pthreadVSE.dll with your application. 405MSVC using C++ EH works. Distribute pthreadVCE.dll with your application. 406MSVC using C setjmp/longjmp works. Distribute pthreadVC.dll with your application. 407 408 409Mingw32: 410See the FAQ, Questions 6 and 10. 411 412Mingw using C++ EH works. Distribute pthreadGCE.dll with your application. 413Mingw using C setjmp/longjmp works. Distribute pthreadGC.dll with your application. 414 415 416Cygwin: (http://sourceware.cygnus.com/cygwin/) 417Developers using Cygwin do not need pthreads-win32 since it has POSIX threads 418support. Refer to its documentation for details and extent. 419 420 421UWIN: 422UWIN is a complete Unix-like environment for Windows from AT&T. Pthreads-win32 423doesn't currently support UWIN (and vice versa), but that may change in the 424future. 425 426Generally: 427For convenience, the following pre-built files are available on the FTP site 428(see Availability above): 429 430 pthread.h - for POSIX threads 431 semaphore.h - for POSIX semaphores 432 sched.h - for POSIX scheduling 433 pthreadVCE.dll - built with MSVC++ compiler using C++ EH 434 pthreadVCE.lib 435 pthreadVC.dll - built with MSVC compiler using C setjmp/longjmp 436 pthreadVC.lib 437 pthreadVSE.dll - built with MSVC compiler using SEH 438 pthreadVSE.lib 439 pthreadGCE.dll - built with Mingw32 G++ 2.95.2-1 440 pthreadGC.dll - built with Mingw32 GCC 2.95.2-1 using setjmp/longjmp 441 libpthreadGCE.a - derived from pthreadGCE.dll 442 libpthreadGC.a - derived from pthreadGC.dll 443 gcc.dll - needed if distributing applications that use 444 pthreadGCE.dll (but see the FAQ Q 10 for the latest 445 related information) 446 447These are the only files you need in order to build POSIX threads 448applications for Win32 using either MSVC or Mingw32. 449 450See the FAQ file in the source tree for additional information. 451 452 453Documentation 454------------- 455 456For the authoritative reference, see the online POSIX 457standard reference at: 458 459 http://www.OpenGroup.org 460 461For POSIX Thread API programming, several reference books are 462available: 463 464 Programming with POSIX Threads 465 David R. Butenhof 466 Addison-Wesley (pub) 467 468 Pthreads Programming 469 By Bradford Nichols, Dick Buttlar & Jacqueline Proulx Farrell 470 O'Reilly (pub) 471 472On the web: see the links at the bottom of the pthreads-win32 site: 473 474 http://sources.redhat.com/pthreads-win32/ 475 476 Currently, there is no documentation included in the package apart 477 from the copious comments in the source code. 478 479 480 481Enjoy! 482 483Ross Johnson 484