From 3562e78743202e43aec8727005182a2558117eca Mon Sep 17 00:00:00 2001 From: marha Date: Sun, 28 Jun 2009 22:07:26 +0000 Subject: Checked in the following released items: xkeyboard-config-1.4.tar.gz ttf-bitstream-vera-1.10.tar.gz font-alias-1.0.1.tar.gz font-sun-misc-1.0.0.tar.gz font-sun-misc-1.0.0.tar.gz font-sony-misc-1.0.0.tar.gz font-schumacher-misc-1.0.0.tar.gz font-mutt-misc-1.0.0.tar.gz font-misc-misc-1.0.0.tar.gz font-misc-meltho-1.0.0.tar.gz font-micro-misc-1.0.0.tar.gz font-jis-misc-1.0.0.tar.gz font-isas-misc-1.0.0.tar.gz font-dec-misc-1.0.0.tar.gz font-daewoo-misc-1.0.0.tar.gz font-cursor-misc-1.0.0.tar.gz font-arabic-misc-1.0.0.tar.gz font-winitzki-cyrillic-1.0.0.tar.gz font-misc-cyrillic-1.0.0.tar.gz font-cronyx-cyrillic-1.0.0.tar.gz font-screen-cyrillic-1.0.1.tar.gz font-xfree86-type1-1.0.1.tar.gz font-adobe-utopia-type1-1.0.1.tar.gz font-ibm-type1-1.0.0.tar.gz font-bitstream-type1-1.0.0.tar.gz font-bitstream-speedo-1.0.0.tar.gz font-bh-ttf-1.0.0.tar.gz font-bh-type1-1.0.0.tar.gz font-bitstream-100dpi-1.0.0.tar.gz font-bh-lucidatypewriter-100dpi-1.0.0.tar.gz font-bh-100dpi-1.0.0.tar.gz font-adobe-utopia-100dpi-1.0.1.tar.gz font-adobe-100dpi-1.0.0.tar.gz font-util-1.0.1.tar.gz font-bitstream-75dpi-1.0.0.tar.gz font-bh-lucidatypewriter-75dpi-1.0.0.tar.gz font-adobe-utopia-75dpi-1.0.1.tar.gz font-bh-75dpi-1.0.0.tar.gz bdftopcf-1.0.1.tar.gz font-adobe-75dpi-1.0.0.tar.gz mkfontscale-1.0.6.tar.gz openssl-0.9.8k.tar.gz bigreqsproto-1.0.2.tar.gz xtrans-1.2.2.tar.gz resourceproto-1.0.2.tar.gz inputproto-1.4.4.tar.gz compositeproto-0.4.tar.gz damageproto-1.1.0.tar.gz zlib-1.2.3.tar.gz xkbcomp-1.0.5.tar.gz freetype-2.3.9.tar.gz pthreads-w32-2-8-0-release.tar.gz pixman-0.12.0.tar.gz kbproto-1.0.3.tar.gz evieext-1.0.2.tar.gz fixesproto-4.0.tar.gz recordproto-1.13.2.tar.gz randrproto-1.2.2.tar.gz scrnsaverproto-1.1.0.tar.gz renderproto-0.9.3.tar.gz xcmiscproto-1.1.2.tar.gz fontsproto-2.0.2.tar.gz xextproto-7.0.3.tar.gz xproto-7.0.14.tar.gz libXdmcp-1.0.2.tar.gz libxkbfile-1.0.5.tar.gz libfontenc-1.0.4.tar.gz libXfont-1.3.4.tar.gz libX11-1.1.5.tar.gz libXau-1.0.4.tar.gz libxcb-1.1.tar.gz xorg-server-1.5.3.tar.gz --- pthreads/manual/ChangeLog | 62 ++ pthreads/manual/PortabilityIssues.html | 718 +++++++++++++++++++++ pthreads/manual/index.html | 146 +++++ pthreads/manual/pthreadCancelableWait.html | 86 +++ pthreads/manual/pthread_attr_init.html | 280 ++++++++ pthreads/manual/pthread_attr_setstackaddr.html | 158 +++++ pthreads/manual/pthread_attr_setstacksize.html | 127 ++++ pthreads/manual/pthread_barrier_init.html | 200 ++++++ pthreads/manual/pthread_barrier_wait.html | 167 +++++ pthreads/manual/pthread_barrierattr_init.html | 142 ++++ .../manual/pthread_barrierattr_setpshared.html | 159 +++++ pthreads/manual/pthread_cancel.html | 205 ++++++ pthreads/manual/pthread_cleanup_push.html | 140 ++++ pthreads/manual/pthread_cond_init.html | 313 +++++++++ pthreads/manual/pthread_condattr_init.html | 98 +++ pthreads/manual/pthread_condattr_setpshared.html | 153 +++++ pthreads/manual/pthread_create.html | 94 +++ pthreads/manual/pthread_delay_np.html | 71 ++ pthreads/manual/pthread_detach.html | 90 +++ pthreads/manual/pthread_equal.html | 48 ++ pthreads/manual/pthread_exit.html | 59 ++ pthreads/manual/pthread_getw32threadhandle_np.html | 57 ++ pthreads/manual/pthread_join.html | 118 ++++ pthreads/manual/pthread_key_create.html | 211 ++++++ pthreads/manual/pthread_kill.html | 152 +++++ pthreads/manual/pthread_mutex_init.html | 277 ++++++++ pthreads/manual/pthread_mutexattr_init.html | 157 +++++ pthreads/manual/pthread_mutexattr_setpshared.html | 151 +++++ pthreads/manual/pthread_num_processors_np.html | 57 ++ pthreads/manual/pthread_once.html | 83 +++ pthreads/manual/pthread_rwlock_init.html | 193 ++++++ pthreads/manual/pthread_rwlock_rdlock.html | 168 +++++ pthreads/manual/pthread_rwlock_timedrdlock.html | 156 +++++ pthreads/manual/pthread_rwlock_timedwrlock.html | 150 +++++ pthreads/manual/pthread_rwlock_unlock.html | 141 ++++ pthreads/manual/pthread_rwlock_wrlock.html | 153 +++++ pthreads/manual/pthread_rwlockattr_init.html | 141 ++++ pthreads/manual/pthread_rwlockattr_setpshared.html | 160 +++++ pthreads/manual/pthread_self.html | 70 ++ pthreads/manual/pthread_setcancelstate.html | 207 ++++++ pthreads/manual/pthread_setcanceltype.html | 207 ++++++ pthreads/manual/pthread_setconcurrency.html | 155 +++++ pthreads/manual/pthread_setschedparam.html | 113 ++++ pthreads/manual/pthread_spin_init.html | 176 +++++ pthreads/manual/pthread_spin_lock.html | 141 ++++ pthreads/manual/pthread_spin_unlock.html | 124 ++++ pthreads/manual/pthread_timechange_handler_np.html | 76 +++ .../manual/pthread_win32_attach_detach_np.html | 74 +++ .../manual/pthread_win32_test_features_np.html | 68 ++ pthreads/manual/sched_get_priority_max.html | 115 ++++ pthreads/manual/sched_getscheduler.html | 127 ++++ pthreads/manual/sched_setscheduler.html | 181 ++++++ pthreads/manual/sched_yield.html | 98 +++ pthreads/manual/sem_init.html | 200 ++++++ 54 files changed, 8173 insertions(+) create mode 100644 pthreads/manual/ChangeLog create mode 100644 pthreads/manual/PortabilityIssues.html create mode 100644 pthreads/manual/index.html create mode 100644 pthreads/manual/pthreadCancelableWait.html create mode 100644 pthreads/manual/pthread_attr_init.html create mode 100644 pthreads/manual/pthread_attr_setstackaddr.html create mode 100644 pthreads/manual/pthread_attr_setstacksize.html create mode 100644 pthreads/manual/pthread_barrier_init.html create mode 100644 pthreads/manual/pthread_barrier_wait.html create mode 100644 pthreads/manual/pthread_barrierattr_init.html create mode 100644 pthreads/manual/pthread_barrierattr_setpshared.html create mode 100644 pthreads/manual/pthread_cancel.html create mode 100644 pthreads/manual/pthread_cleanup_push.html create mode 100644 pthreads/manual/pthread_cond_init.html create mode 100644 pthreads/manual/pthread_condattr_init.html create mode 100644 pthreads/manual/pthread_condattr_setpshared.html create mode 100644 pthreads/manual/pthread_create.html create mode 100644 pthreads/manual/pthread_delay_np.html create mode 100644 pthreads/manual/pthread_detach.html create mode 100644 pthreads/manual/pthread_equal.html create mode 100644 pthreads/manual/pthread_exit.html create mode 100644 pthreads/manual/pthread_getw32threadhandle_np.html create mode 100644 pthreads/manual/pthread_join.html create mode 100644 pthreads/manual/pthread_key_create.html create mode 100644 pthreads/manual/pthread_kill.html create mode 100644 pthreads/manual/pthread_mutex_init.html create mode 100644 pthreads/manual/pthread_mutexattr_init.html create mode 100644 pthreads/manual/pthread_mutexattr_setpshared.html create mode 100644 pthreads/manual/pthread_num_processors_np.html create mode 100644 pthreads/manual/pthread_once.html create mode 100644 pthreads/manual/pthread_rwlock_init.html create mode 100644 pthreads/manual/pthread_rwlock_rdlock.html create mode 100644 pthreads/manual/pthread_rwlock_timedrdlock.html create mode 100644 pthreads/manual/pthread_rwlock_timedwrlock.html create mode 100644 pthreads/manual/pthread_rwlock_unlock.html create mode 100644 pthreads/manual/pthread_rwlock_wrlock.html create mode 100644 pthreads/manual/pthread_rwlockattr_init.html create mode 100644 pthreads/manual/pthread_rwlockattr_setpshared.html create mode 100644 pthreads/manual/pthread_self.html create mode 100644 pthreads/manual/pthread_setcancelstate.html create mode 100644 pthreads/manual/pthread_setcanceltype.html create mode 100644 pthreads/manual/pthread_setconcurrency.html create mode 100644 pthreads/manual/pthread_setschedparam.html create mode 100644 pthreads/manual/pthread_spin_init.html create mode 100644 pthreads/manual/pthread_spin_lock.html create mode 100644 pthreads/manual/pthread_spin_unlock.html create mode 100644 pthreads/manual/pthread_timechange_handler_np.html create mode 100644 pthreads/manual/pthread_win32_attach_detach_np.html create mode 100644 pthreads/manual/pthread_win32_test_features_np.html create mode 100644 pthreads/manual/sched_get_priority_max.html create mode 100644 pthreads/manual/sched_getscheduler.html create mode 100644 pthreads/manual/sched_setscheduler.html create mode 100644 pthreads/manual/sched_yield.html create mode 100644 pthreads/manual/sem_init.html (limited to 'pthreads/manual') diff --git a/pthreads/manual/ChangeLog b/pthreads/manual/ChangeLog new file mode 100644 index 000000000..c07cdd702 --- /dev/null +++ b/pthreads/manual/ChangeLog @@ -0,0 +1,62 @@ +2005-05-06 Ross Johnson + + * PortabilityIssues.html: Was nonPortableIssues.html. + * index.html: Updated; add table of contents at top. + * *.html: Add Pthreads-win32 header info; add link back to the + index page 'index.html'. + +2005-05-06 Ross Johnson + + * index.html: New. + * nonPortableIssues.html: New. + * pthread_attr_init.html: New. + * pthread_attr_setstackaddr.html: New. + * pthread_attr_setstacksize.html: New. + * pthread_barrierattr_init.html: New. + * pthread_barrierattr_setpshared.html: New. + * pthread_barrier_init.html: New. + * pthread_barrier_wait.html: New. + * pthreadCancelableWait.html: New. + * pthread_cancel.html: New. + * pthread_cleanup_push.html: New. + * pthread_condattr_init.html: New. + * pthread_condattr_setpshared.html: New. + * pthread_cond_init.html: New. + * pthread_create.html: New. + * pthread_delay_np.html: New. + * pthread_detach.html: New. + * pthread_equal.html: New. + * pthread_exit.html: New. + * pthread_getw32threadhandle_np.html: New. + * pthread_join.html: New. + * pthread_key_create.html: New. + * pthread_kill.html: New. + * pthread_mutexattr_init.html: New. + * pthread_mutexattr_setpshared.html: New. + * pthread_mutex_init.html: New. + * pthread_num_processors_np.html: New. + * pthread_once.html: New. + * pthread_rwlockattr_init.html: New. + * pthread_rwlockattr_setpshared.html: New. + * pthread_rwlock_init.html: New. + * pthread_rwlock_rdlock.html: New. + * pthread_rwlock_timedrdlock.html: New. + * pthread_rwlock_timedwrlock.html: New. + * pthread_rwlock_unlock.html: New. + * pthread_rwlock_wrlock.html: New. + * pthread_self.html: New. + * pthread_setcancelstate.html: New. + * pthread_setcanceltype.html: New. + * pthread_setconcurrency.html: New. + * pthread_setschedparam.html: New. + * pthread_spin_init.html: New. + * pthread_spin_lock.html: New. + * pthread_spin_unlock.html: New. + * pthread_timechange_handler_np.html: New. + * pthread_win32_attach_detach_np.html: New. + * pthread_win32_test_features_np.html: New. + * sched_get_priority_max.html: New. + * sched_getscheduler.html: New. + * sched_setscheduler.html: New. + * sched_yield.html: New. + * sem_init.html: New. diff --git a/pthreads/manual/PortabilityIssues.html b/pthreads/manual/PortabilityIssues.html new file mode 100644 index 000000000..376a5f00e --- /dev/null +++ b/pthreads/manual/PortabilityIssues.html @@ -0,0 +1,718 @@ + + + + + PORTABILITYISSUES manual page + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

Portability issues

+

Synopsis

+

Thread priority

+

Description

+

Thread priority

+

POSIX defines a single contiguous range +of numbers that determine a thread's priority. Win32 defines priority +classes - and priority levels relative to these classes. Classes are +simply priority base levels that the defined priority levels are +relative to such that, changing a process's priority class will +change the priority of all of it's threads, while the threads retain +the same relativity to each other.

+

A Win32 system defines a single +contiguous monotonic range of values that define system priority +levels, just like POSIX. However, Win32 restricts individual threads +to a subset of this range on a per-process basis.

+

The following table shows the base +priority levels for combinations of priority class and priority value +in Win32.

+
+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+


+

+ 		+

Process Priority Class

+ 		+

Thread Priority Level

+
+

1

+ 		+

IDLE_PRIORITY_CLASS

+ 		+

THREAD_PRIORITY_IDLE

+
+

1

+ 		+

BELOW_NORMAL_PRIORITY_CLASS

+ 		+

THREAD_PRIORITY_IDLE

+
+

1

+ 		+

NORMAL_PRIORITY_CLASS

+ 		+

THREAD_PRIORITY_IDLE

+
+

1

+ 		+

ABOVE_NORMAL_PRIORITY_CLASS

+ 		+

THREAD_PRIORITY_IDLE

+
+

1

+ 		+

HIGH_PRIORITY_CLASS

+ 		+

THREAD_PRIORITY_IDLE

+
+

2

+ 		+

IDLE_PRIORITY_CLASS

+ 		+

THREAD_PRIORITY_LOWEST

+
+

3

+ 		+

IDLE_PRIORITY_CLASS

+ 		+

THREAD_PRIORITY_BELOW_NORMAL

+
+

4

+ 		+

IDLE_PRIORITY_CLASS

+ 		+

THREAD_PRIORITY_NORMAL

+
+

4

+ 		+

BELOW_NORMAL_PRIORITY_CLASS

+ 		+

THREAD_PRIORITY_LOWEST

+
+

5

+ 		+

IDLE_PRIORITY_CLASS

+ 		+

THREAD_PRIORITY_ABOVE_NORMAL

+
+

5

+ 		+

BELOW_NORMAL_PRIORITY_CLASS

+ 		+

THREAD_PRIORITY_BELOW_NORMAL

+
+

5

+ 		+

Background NORMAL_PRIORITY_CLASS

+ 		+

THREAD_PRIORITY_LOWEST

+
+

6

+ 		+

IDLE_PRIORITY_CLASS

+ 		+

THREAD_PRIORITY_HIGHEST

+
+

6

+ 		+

BELOW_NORMAL_PRIORITY_CLASS

+ 		+

THREAD_PRIORITY_NORMAL

+
+

6

+ 		+

Background NORMAL_PRIORITY_CLASS

+ 		+

THREAD_PRIORITY_BELOW_NORMAL

+
+

7

+ 		+

BELOW_NORMAL_PRIORITY_CLASS

+ 		+

THREAD_PRIORITY_ABOVE_NORMAL

+
+

7

+ 		+

Background NORMAL_PRIORITY_CLASS

+ 		+

THREAD_PRIORITY_NORMAL

+
+

7

+ 		+

Foreground NORMAL_PRIORITY_CLASS

+ 		+

THREAD_PRIORITY_LOWEST

+
+

8

+ 		+

BELOW_NORMAL_PRIORITY_CLASS

+ 		+

THREAD_PRIORITY_HIGHEST

+
+

8

+ 		+

NORMAL_PRIORITY_CLASS

+ 		+

THREAD_PRIORITY_ABOVE_NORMAL

+
+

8

+ 		+

Foreground NORMAL_PRIORITY_CLASS

+ 		+

THREAD_PRIORITY_BELOW_NORMAL

+
+

8

+ 		+

ABOVE_NORMAL_PRIORITY_CLASS

+ 		+

THREAD_PRIORITY_LOWEST

+
+

9

+ 		+

NORMAL_PRIORITY_CLASS

+ 		+

THREAD_PRIORITY_HIGHEST

+
+

9

+ 		+

Foreground NORMAL_PRIORITY_CLASS

+ 		+

THREAD_PRIORITY_NORMAL

+
+

9

+ 		+

ABOVE_NORMAL_PRIORITY_CLASS

+ 		+

THREAD_PRIORITY_BELOW_NORMAL

+
+

10

+ 		+

Foreground NORMAL_PRIORITY_CLASS

+ 		+

THREAD_PRIORITY_ABOVE_NORMAL

+
+

10

+ 		+

ABOVE_NORMAL_PRIORITY_CLASS

+ 		+

THREAD_PRIORITY_NORMAL

+
+

11

+ 		+

Foreground NORMAL_PRIORITY_CLASS

+ 		+

THREAD_PRIORITY_HIGHEST

+
+

11

+ 		+

ABOVE_NORMAL_PRIORITY_CLASS

+ 		+

THREAD_PRIORITY_ABOVE_NORMAL

+
+

11

+ 		+

HIGH_PRIORITY_CLASS

+ 		+

THREAD_PRIORITY_LOWEST

+
+

12

+ 		+

ABOVE_NORMAL_PRIORITY_CLASS

+ 		+

THREAD_PRIORITY_HIGHEST

+
+

12

+ 		+

HIGH_PRIORITY_CLASS

+ 		+

THREAD_PRIORITY_BELOW_NORMAL

+
+

13

+ 		+

HIGH_PRIORITY_CLASS

+ 		+

THREAD_PRIORITY_NORMAL

+
+

14

+ 		+

HIGH_PRIORITY_CLASS

+ 		+

THREAD_PRIORITY_ABOVE_NORMAL

+
+

15

+ 		+

HIGH_PRIORITY_CLASS

+ 		+

THREAD_PRIORITY_HIGHEST

+
+

15

+ 		+

HIGH_PRIORITY_CLASS

+ 		+

THREAD_PRIORITY_TIME_CRITICAL

+
+

15

+ 		+

IDLE_PRIORITY_CLASS

+ 		+

THREAD_PRIORITY_TIME_CRITICAL

+
+

15

+ 		+

BELOW_NORMAL_PRIORITY_CLASS

+ 		+

THREAD_PRIORITY_TIME_CRITICAL

+
+

15

+ 		+

NORMAL_PRIORITY_CLASS

+ 		+

THREAD_PRIORITY_TIME_CRITICAL

+
+

15

+ 		+

ABOVE_NORMAL_PRIORITY_CLASS

+ 		+

THREAD_PRIORITY_TIME_CRITICAL

+
+

16

+ 		+

REALTIME_PRIORITY_CLASS

+ 		+

THREAD_PRIORITY_IDLE

+
+

17

+ 		+

REALTIME_PRIORITY_CLASS

+ 		+

-7

+
+

18

+ 		+

REALTIME_PRIORITY_CLASS

+ 		+

-6

+
+

19

+ 		+

REALTIME_PRIORITY_CLASS

+ 		+

-5

+
+

20

+ 		+

REALTIME_PRIORITY_CLASS

+ 		+

-4

+
+

21

+ 		+

REALTIME_PRIORITY_CLASS

+ 		+

-3

+
+

22

+ 		+

REALTIME_PRIORITY_CLASS

+ 		+

THREAD_PRIORITY_LOWEST

+
+

23

+ 		+

REALTIME_PRIORITY_CLASS

+ 		+

THREAD_PRIORITY_BELOW_NORMAL

+
+

24

+ 		+

REALTIME_PRIORITY_CLASS

+ 		+

THREAD_PRIORITY_NORMAL

+
+

25

+ 		+

REALTIME_PRIORITY_CLASS

+ 		+

THREAD_PRIORITY_ABOVE_NORMAL

+
+

26

+ 		+

REALTIME_PRIORITY_CLASS

+ 		+

THREAD_PRIORITY_HIGHEST

+
+

27

+ 		+

REALTIME_PRIORITY_CLASS

+ 		+

3

+
+

28

+ 		+

REALTIME_PRIORITY_CLASS

+ 		+

4

+
+

29

+ 		+

REALTIME_PRIORITY_CLASS

+ 		+

5

+
+

30

+ 		+

REALTIME_PRIORITY_CLASS

+ 		+

6

+
+

31

+ 		+

REALTIME_PRIORITY_CLASS

+ 		+

THREAD_PRIORITY_TIME_CRITICAL

+
+
+
+

Windows NT: Values -7, -6, -5, -4, -3, 3, +4, 5, and 6 are not supported.

+

As you can see, the real priority levels +available to any individual Win32 thread are non-contiguous.

+

An application using Pthreads-w32 should +not make assumptions about the numbers used to represent thread +priority levels, except that they are monotonic between the values +returned by sched_get_priority_min() and sched_get_priority_max(). +E.g. Windows 95, 98, NT, 2000, XP make available a non-contiguous +range of numbers between -15 and 15, while at least one version of +WinCE (3.0) defines the minimum priority (THREAD_PRIORITY_LOWEST) as +5, and the maximum priority (THREAD_PRIORITY_HIGHEST) as 1.

+

Internally, pthreads-win32 maps any +priority levels between THREAD_PRIORITY_IDLE and +THREAD_PRIORITY_LOWEST to THREAD_PRIORITY_LOWEST, or between +THREAD_PRIORITY_TIME_CRITICAL and THREAD_PRIORITY_HIGHEST to +THREAD_PRIORITY_HIGHEST. Currently, this also applies to +REALTIME_PRIORITY_CLASS even if levels -7, -6, -5, -4, -3, 3, 4, 5, +and 6 are supported.

+

If it wishes, a Win32 application using +pthreads-w32 can use the Win32 defined priority macros +THREAD_PRIORITY_IDLE through THREAD_PRIORITY_TIME_CRITICAL.

+

Author

+

Ross Johnson for use with Pthreads-w32.

+

See also

+



+

+
+

Table of Contents

+ + + diff --git a/pthreads/manual/index.html b/pthreads/manual/index.html new file mode 100644 index 000000000..a209dc01a --- /dev/null +++ b/pthreads/manual/index.html @@ -0,0 +1,146 @@ + + + + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Table of Contents

+

POSIX +threads API reference
Miscellaneous +POSIX thread safe routines provided by Pthreads-w32
Non-portable +Pthreads-w32 routines
Other

+

POSIX threads API reference

+

pthread_attr_destroy

+

pthread_attr_getdetachstate

+

pthread_attr_getinheritsched

+

pthread_attr_getschedparam

+

pthread_attr_getschedpolicy

+

pthread_attr_getscope

+

pthread_attr_getstackaddr

+

pthread_attr_getstacksize

+

pthread_attr_init

+

pthread_attr_setdetachstate

+

pthread_attr_setinheritsched

+

pthread_attr_setschedparam

+

pthread_attr_setschedpolicy

+

pthread_attr_setscope

+

pthread_attr_setstackaddr

+

pthread_attr_setstacksize

+

pthread_barrierattr_destroy

+

pthread_barrierattr_getpshared

+

pthread_barrierattr_init

+

pthread_barrierattr_setpshared

+

pthread_barrier_destroy

+

pthread_barrier_init

+

pthread_barrier_wait

+

pthread_cancel

+

pthread_cleanup_pop

+

pthread_cleanup_push

+

pthread_condattr_destroy

+

pthread_condattr_getpshared

+

pthread_condattr_init

+

pthread_condattr_setpshared

+

pthread_cond_broadcast

+

pthread_cond_destroy

+

pthread_cond_init

+

pthread_cond_signal

+

pthread_cond_timedwait

+

pthread_cond_wait

+

pthread_create

+

pthread_detach

+

pthread_equal

+

pthread_exit

+

pthread_getconcurrency

+

pthread_getschedparam

+

pthread_getspecific

+

pthread_join

+

pthread_key_create

+

pthread_key_delete

+

pthread_kill

+

pthread_mutexattr_destroy

+

pthread_mutexattr_getkind_np

+

pthread_mutexattr_getpshared

+

pthread_mutexattr_gettype

+

pthread_mutexattr_init

+

pthread_mutexattr_setkind_np

+

pthread_mutexattr_setpshared

+

pthread_mutexattr_settype

+

pthread_mutex_destroy

+

pthread_mutex_init

+

pthread_mutex_lock

+

pthread_mutex_timedlock

+

pthread_mutex_trylock

+

pthread_mutex_unlock

+

pthread_once

+

pthread_rwlockattr_destroy

+

pthread_rwlockattr_getpshared

+

pthread_rwlockattr_init

+

pthread_rwlockattr_setpshared

+

pthread_rwlock_destroy

+

pthread_rwlock_init

+

pthread_rwlock_rdlock

+

pthread_rwlock_timedrdlock

+

pthread_rwlock_timedwrlock

+

pthread_rwlock_tryrdlock

+

pthread_rwlock_trywrlock

+

pthread_rwlock_unlock

+

pthread_rwlock_wrlock

+

pthread_self

+

pthread_setcancelstate

+

pthread_setcanceltype

+

pthread_setconcurrency

+

pthread_setschedparam

+

pthread_setspecific

+

pthread_sigmask

+

pthread_spin_destroy

+

pthread_spin_init

+

pthread_spin_lock

+

pthread_spin_trylock

+

pthread_spin_unlock

+

pthread_testcancel

+

sched_get_priority_max

+

sched_get_priority_min

+

sched_getscheduler

+

sched_setscheduler

+

sched_yield

+

sem_close

+

sem_destroy

+

sem_getvalue

+

sem_init

+

sem_open

+

sem_post

+

sem_post_multiple

+

sem_timedwait

+

sem_trywait

+

sem_unlink

+

sem_wait

+

sigwait

+

Miscellaneous POSIX thread safe +routines provided by Pthreads-w32

+

asctime_r

+

ctime_r

+

gmtime_r

+

localtime_r

+

rand_r

+

Non-portable Pthreads-w32 routines

+

pthreadCancelableTimedWait

+

pthreadCancelableWait

+

pthread_delay_np

+

pthread_getw32threadhandle_np

+

pthread_num_processors_np

+

pthread_win32_test_features_np

+

pthread_timechange_handler_np

+

pthread_win32_process_attach_np

+

pthread_win32_process_detach_np

+

pthread_win32_thread_attach_np

+

pthread_win32_thread_detach_np

+

Other

+

Portability +issues

+ + diff --git a/pthreads/manual/pthreadCancelableWait.html b/pthreads/manual/pthreadCancelableWait.html new file mode 100644 index 000000000..9d7c1a458 --- /dev/null +++ b/pthreads/manual/pthreadCancelableWait.html @@ -0,0 +1,86 @@ + + + + + PTHREADCANCELLABLEWAIT manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

pthreadCancelableTimedWait, +pthreadCancelableWait – provide cancellation hooks for user Win32 +routines

+

Synopsis

+

#include <pthread.h> +

+

int pthreadCancelableTimedWait (HANDLE waitHandle, +DWORD timeout);

+

int pthreadCancelableWait (HANDLE waitHandle);

+

Description

+

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 +Win32 HANDLE is signalled, or pthread_cancel() +has been called. They are implemented using WaitForMultipleObjects +on waitHandle and the manually reset Win32 event handle that +is the target of pthread_cancel(). +These routines may be called from Win32 native threads but +pthread_cancel() will +require that thread's POSIX thread ID that the thread must retrieve +using pthread_self().

+

pthreadCancelableTimedWait is the timed version that will +return with the code ETIMEDOUT if the interval timeout +milliseconds elapses before waitHandle is signalled.

+

Cancellation

+

These routines allow routines that block on Win32 HANDLEs to be +cancellable via pthread_cancel().

+

Return Value

+



+

+

Errors

+

The pthreadCancelableTimedWait function returns the +following error code on error: +

+
+
+
ETIMEDOUT +
+
+

+The interval timeout milliseconds elapsed before waitHandle +was signalled.

+

Author

+

Ross Johnson for use with Pthreads-w32.

+

See also

+

pthread_cancel(), +pthread_self()

+
+

Table of Contents

+ + + diff --git a/pthreads/manual/pthread_attr_init.html b/pthreads/manual/pthread_attr_init.html new file mode 100644 index 000000000..fa5ab5811 --- /dev/null +++ b/pthreads/manual/pthread_attr_init.html @@ -0,0 +1,280 @@ + + + + + PTHREAD_ATTR_INIT(3) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

pthread_attr_init, pthread_attr_destroy, +pthread_attr_setdetachstate, pthread_attr_getdetachstate, +pthread_attr_setschedparam, pthread_attr_getschedparam, +pthread_attr_setschedpolicy, pthread_attr_getschedpolicy, +pthread_attr_setinheritsched, pthread_attr_getinheritsched, +pthread_attr_setscope, pthread_attr_getscope - thread creation +attributes +

+

Synopsis

+

#include <pthread.h> +

+

int pthread_attr_init(pthread_attr_t *attr); +

+

int pthread_attr_destroy(pthread_attr_t *attr); +

+

int pthread_attr_setdetachstate(pthread_attr_t *attr, +int detachstate); +

+

int pthread_attr_getdetachstate(const pthread_attr_t *attr, +int *detachstate); +

+

int pthread_attr_setschedpolicy(pthread_attr_t *attr, +int policy); +

+

int pthread_attr_getschedpolicy(const pthread_attr_t *attr, +int *policy); +

+

int pthread_attr_setschedparam(pthread_attr_t *attr, +const struct sched_param *param); +

+

int pthread_attr_getschedparam(const pthread_attr_t *attr, +struct sched_param *param); +

+

int pthread_attr_setinheritsched(pthread_attr_t *attr, +int inherit); +

+

int pthread_attr_getinheritsched(const pthread_attr_t *attr, +int *inherit); +

+

int pthread_attr_setscope(pthread_attr_t *attr, +int scope); +

+

int pthread_attr_getscope(const pthread_attr_t *attr, +int *scope); +

+

Description

+

Setting attributes for threads is achieved by filling a thread +attribute object attr of type pthread_attr_t, then +passing it as second argument to pthread_create(3) +. Passing NULL is equivalent to passing a thread attribute +object with all attributes set to their default values. +

+

pthread_attr_init initializes the thread attribute object +attr and fills it with default values for the attributes. (The +default values are listed below for each attribute.) +

+

Each attribute attrname (see below for a list of all +attributes) can be individually set using the function +pthread_attr_setattrname and retrieved using the +function pthread_attr_getattrname. +

+

pthread_attr_destroy destroys a thread attribute object, +which must not then be reused until it is reinitialized. +

+

Attribute objects are consulted only when creating a new thread. +The same attribute object can be used for creating several threads. +Modifying an attribute object after a call to pthread_create +does not change the attributes of the thread previously created. +

+

The following thread attributes are supported: +

+

detachstate

+

Control whether the thread is created in the joinable state (value +PTHREAD_CREATE_JOINABLE) or in the detached state ( +PTHREAD_CREATE_DETACHED). +

+

Default value: PTHREAD_CREATE_JOINABLE. +

+

In the joinable state, another thread can synchronize on the +thread termination and recover its termination code using +pthread_join(3) . When a +joinable thread terminates, some of the thread resources are kept +allocated, and released only when another thread performs +pthread_join(3) on that +thread. +

+

In the detached state, the thread's resources are released +immediately when it terminates. pthread_join(3) +cannot be used to synchronize on the thread termination. +

+

A thread created in the joinable state can later be put in the +detached thread using pthread_detach(3) +. +

+

schedpolicy

+

Select the scheduling policy for the thread: one of SCHED_OTHER +(regular, non-real-time scheduling), SCHED_RR (real-time, +round-robin) or SCHED_FIFO (real-time, first-in first-out). +

+

Pthreads-w32 only supports SCHED_OTHER - attempting +to set one of the other policies will return an error ENOTSUP.

+

Default value: SCHED_OTHER. +

+

Pthreads-w32 only supports SCHED_OTHER - attempting +to set one of the other policies will return an error ENOTSUP.

+

The scheduling policy of a thread can be changed after creation +with pthread_setschedparam(3) +. +

+

schedparam

+

Contain the scheduling parameters (essentially, the scheduling +priority) for the thread.

+

Pthreads-w32 supports the priority levels defined by the +Windows system it is running on. Under Windows, thread priorities are +relative to the process priority class, which must be set via the +Windows W32 API.

+

Default value: priority is 0 (Win32 level THREAD_PRIORITY_NORMAL). +

+

The scheduling priority of a thread can be changed after creation +with pthread_setschedparam(3) +. +

+

inheritsched

+

Indicate whether the scheduling policy and scheduling parameters +for the newly created thread are determined by the values of the +schedpolicy and schedparam attributes (value +PTHREAD_EXPLICIT_SCHED) or are inherited from the parent +thread (value PTHREAD_INHERIT_SCHED). +

+

Default value: PTHREAD_EXPLICIT_SCHED. +

+

scope

+

Define the scheduling contention scope for the created thread. The +only value supported in the Pthreads-w32 implementation is +PTHREAD_SCOPE_SYSTEM, meaning that the threads contend for CPU +time with all processes running on the machine. The other value +specified by the standard, PTHREAD_SCOPE_PROCESS, means that +scheduling contention occurs only between the threads of the running +process.

+

Pthreads-w32 only supports PTHREAD_SCOPE_SYSTEM.

+

Default value: PTHREAD_SCOPE_SYSTEM. +

+

Return Value

+

All functions return 0 on success and a non-zero error code on +error. On success, the pthread_attr_getattrname +functions also store the current value of the attribute attrname +in the location pointed to by their second argument. +

+

Errors

+

The pthread_attr_setdetachstate function returns the +following error codes on error: +

+
+
+
EINVAL +
+ the specified detachstate is not one of + PTHREAD_CREATE_JOINABLE or PTHREAD_CREATE_DETACHED. +
+
+

+The pthread_attr_setschedparam function returns the following +error codes on error: +

+
+
+
EINVAL +
+ the priority specified in param is outside the range of + allowed priorities for the scheduling policy currently in attr + (1 to 99 for SCHED_FIFO and SCHED_RR; 0 for + SCHED_OTHER). +
+
+

+The pthread_attr_setschedpolicy function returns the following +error codes on error: +

+
+
+
EINVAL +
+ the specified policy is not one of SCHED_OTHER, + SCHED_FIFO, or SCHED_RR. +
+ ENOTSUP +
+ policy is not SCHED_OTHER, the only value supported + by Pthreads-w32.
+
+

+The pthread_attr_setinheritsched function returns the +following error codes on error: +

+
+
+
EINVAL +
+ the specified inherit is not one of PTHREAD_INHERIT_SCHED + or PTHREAD_EXPLICIT_SCHED. +
+
+

+The pthread_attr_setscope function returns the following error +codes on error: +

+
+
+
EINVAL +
+ the specified scope is not one of PTHREAD_SCOPE_SYSTEM + or PTHREAD_SCOPE_PROCESS. +
+ ENOTSUP +
+ the specified scope is PTHREAD_SCOPE_PROCESS (not + supported by Pthreads-w32). +
+
+

+Author

+

Xavier Leroy <Xavier.Leroy@inria.fr> +

+

Modified by Ross Johnson for use with Pthreads-w32.

+

See Also

+

pthread_create(3) , +pthread_join(3) , +pthread_detach(3) , +pthread_setschedparam(3) +. +

+
+

Table of Contents

+ + + diff --git a/pthreads/manual/pthread_attr_setstackaddr.html b/pthreads/manual/pthread_attr_setstackaddr.html new file mode 100644 index 000000000..868832c0a --- /dev/null +++ b/pthreads/manual/pthread_attr_setstackaddr.html @@ -0,0 +1,158 @@ + + + + + "PTHREAD_ATTR_GETSTACKADDR"(P) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

pthread_attr_getstackaddr, pthread_attr_setstackaddr - get and set +the stackaddr attribute +

+

Synopsis

+

#include <pthread.h> +

+

int pthread_attr_getstackaddr(const pthread_attr_t *restrict +attr, void **restrict stackaddr);
int +pthread_attr_setstackaddr(pthread_attr_t *attr, void +*stackaddr); +

+

Description

+

The pthread_attr_getstackaddr and pthread_attr_setstackaddr +functions, respectively, shall get and set the thread creation +stackaddr attribute in the attr object. +

+

The stackaddr attribute specifies the location of storage +to be used for the created thread’s stack. The size of the storage +shall be at least {PTHREAD_STACK_MIN}. +

+

Pthreads-w32 defines _POSIX_THREAD_ATTR_STACKADDR in +pthread.h as -1 to indicate that these routines are implemented but +cannot used to set or get the stack address. These routines always +return the error ENOSYS when called.

+

Return Value

+

Upon successful completion, pthread_attr_getstackaddr and +pthread_attr_setstackaddr shall return a value of 0; +otherwise, an error number shall be returned to indicate the error. +

+

The pthread_attr_getstackaddr function stores the stackaddr +attribute value in stackaddr if successful. +

+

Errors

+

The pthread_attr_setstackaddr function always returns the +following error code: +

+
+
+
ENOSYS
+ The function is not supported. +
+
+

+The pthread_attr_getstackaddr function always returns the +following error code: +

+
+
+
ENOSYS
+ The function is not supported. +
+
+

+These functions shall not return an error code of [EINTR]. +

+

The following sections are informative. +

+

Examples

+

None. +

+

Application Usage

+

The specification of the stackaddr attribute presents +several ambiguities that make portable use of these interfaces +impossible. The description of the single address parameter as a +"stack" does not specify a particular relationship between +the address and the "stack" implied by that address. For +example, the address may be taken as the low memory address of a +buffer intended for use as a stack, or it may be taken as the address +to be used as the initial stack pointer register value for the new +thread. These two are not the same except for a machine on which the +stack grows "up" from low memory to high, and on which a +"push" operation first stores the value in memory and then +increments the stack pointer register. Further, on a machine where +the stack grows "down" from high memory to low, +interpretation of the address as the "low memory" address +requires a determination of the intended size of the stack. +IEEE Std 1003.1-2001 has introduced the new interfaces +pthread_attr_setstack(3) +and pthread_attr_getstack(3) +to resolve these ambiguities. +

+

Rationale

+

None. +

+

Future Directions

+

None. +

+

See Also

+

pthread_attr_destroy(3) +, pthread_attr_getdetachstate(3) +, pthread_attr_getstack(3) +, pthread_attr_getstacksize(3) +, pthread_attr_setstack(3) +, pthread_create(3) , the +Base Definitions volume of IEEE Std 1003.1-2001, +<limits.h>, <pthread.h> +

+

Copyright

+

Portions of this text are reprinted and reproduced in electronic +form from IEEE Std 1003.1, 2003 Edition, Standard for Information +Technology -- Portable Operating System Interface (POSIX), The Open +Group Base Specifications Issue 6, Copyright (C) 2001-2003 by the +Institute of Electrical and Electronics Engineers, Inc and The Open +Group. In the event of any discrepancy between this version and the +original IEEE and The Open Group Standard, the original IEEE and The +Open Group Standard is the referee document. The original Standard +can be obtained online at http://www.opengroup.org/unix/online.html +. +

+

Modified by Ross Johnson for use with Pthreads-w32.

+
+

Table of Contents

+ + + diff --git a/pthreads/manual/pthread_attr_setstacksize.html b/pthreads/manual/pthread_attr_setstacksize.html new file mode 100644 index 000000000..ae9d031f4 --- /dev/null +++ b/pthreads/manual/pthread_attr_setstacksize.html @@ -0,0 +1,127 @@ + + + + + "PTHREAD_ATTR_GETSTACKSIZE"(P) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

pthread_attr_getstacksize, pthread_attr_setstacksize - get and set +the stacksize attribute +

+

Synopsis

+

#include <pthread.h> +

+

int pthread_attr_getstacksize(const pthread_attr_t *restrict +attr, size_t *restrict stacksize);
int +pthread_attr_setstacksize(pthread_attr_t *attr, size_t +stacksize); +

+

Description

+

The pthread_attr_getstacksize and pthread_attr_setstacksize +functions, respectively, shall get and set the thread creation +stacksize attribute in the attr object. +

+

The stacksize attribute shall define the minimum stack size +(in bytes) allocated for the created threads stack. +

+

Pthreads-w32 defines _POSIX_THREAD_ATTR_STACKSIZE in +pthread.h to indicate that these routines are implemented and may be +used to set or get the stack size.

+

Default value: 0 (in Pthreads-w32 a value of 0 means the stack +will grow as required)

+

Return Value

+

Upon successful completion, pthread_attr_getstacksize and +pthread_attr_setstacksize shall return a value of 0; +otherwise, an error number shall be returned to indicate the error. +

+

The pthread_attr_getstacksize function stores the stacksize +attribute value in stacksize if successful. +

+

Errors

+

The pthread_attr_setstacksize function shall fail if: +

+
+
EINVAL +
+ The value of stacksize is less than {PTHREAD_STACK_MIN} or + exceeds a system-imposed limit. +
+

+These functions shall not return an error code of [EINTR]. +

+

The following sections are informative. +

+

Examples

+

None. +

+

Application Usage

+

None. +

+

Rationale

+

None. +

+

Future Directions

+

None. +

+

See Also

+

pthread_attr_destroy(3) +, pthread_attr_getstackaddr(3) +, pthread_attr_getdetachstate(3) +, pthread_create(3) , +the Base Definitions volume of IEEE Std 1003.1-2001, +<limits.h>, <pthread.h> +

+

Copyright

+

Portions of this text are reprinted and reproduced in electronic +form from IEEE Std 1003.1, 2003 Edition, Standard for Information +Technology -- Portable Operating System Interface (POSIX), The Open +Group Base Specifications Issue 6, Copyright (C) 2001-2003 by the +Institute of Electrical and Electronics Engineers, Inc and The Open +Group. In the event of any discrepancy between this version and the +original IEEE and The Open Group Standard, the original IEEE and The +Open Group Standard is the referee document. The original Standard +can be obtained online at http://www.opengroup.org/unix/online.html +. +

+

Modified by Ross Johnson for use with Pthreads-w32.

+
+

Table of Contents

+ + + diff --git a/pthreads/manual/pthread_barrier_init.html b/pthreads/manual/pthread_barrier_init.html new file mode 100644 index 000000000..065c1296f --- /dev/null +++ b/pthreads/manual/pthread_barrier_init.html @@ -0,0 +1,200 @@ + + + + + "PTHREAD_BARRIER_DESTROY"(P) manual page + + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

pthread_barrier_destroy, pthread_barrier_init - destroy and +initialize a barrier object (ADVANCED REALTIME THREADS) +

+

Synopsis

+

#include <pthread.h> +

+

int pthread_barrier_destroy(pthread_barrier_t *barrier); +
int pthread_barrier_init(pthread_barrier_t *restrict barrier, +const pthread_barrierattr_t *restrict attr, unsigned +count); +

+

Description

+

The pthread_barrier_destroy function shall destroy the +barrier referenced by barrier and release any resources used +by the barrier. The effect of subsequent use of the barrier is +undefined until the barrier is reinitialized by another call to +pthread_barrier_init . An implementation may use this function +to set barrier to an invalid value. The results are undefined +if pthread_barrier_destroy is called when any thread is +blocked on the barrier, or if this function is called with an +uninitialized barrier. +

+

The pthread_barrier_init function shall allocate any +resources required to use the barrier referenced by barrier +and shall initialize the barrier with attributes referenced by attr. +If attr is NULL, the default barrier attributes shall be used; +the effect is the same as passing the address of a default barrier +attributes object. The results are undefined if pthread_barrier_init +is called when any thread is blocked on the barrier (that is, has not +returned from the pthread_barrier_wait(3) +call). The results are undefined if a barrier is used without first +being initialized. The results are undefined if pthread_barrier_init +is called specifying an already initialized barrier. +

+

The count argument specifies the number of threads that +must call pthread_barrier_wait(3) +before any of them successfully return from the call. The value +specified by count must be greater than zero. +

+

If the pthread_barrier_init function fails, the barrier +shall not be initialized and the contents of barrier are +undefined. +

+

Only the object referenced by barrier may be used for +performing synchronization. The result of referring to copies of that +object in calls to pthread_barrier_destroy or +pthread_barrier_wait(3) +is undefined.

+

Return Value

+

Upon successful completion, these functions shall return zero; +otherwise, an error number shall be returned to indicate the error. +

+

Errors

+

The pthread_barrier_destroy function may fail if: +

+
+
EBUSY +
+ The implementation has detected an attempt to destroy a barrier + while it is in use (for example, while being used in a + pthread_barrier_wait(3) + call) by another thread. +
+ EINVAL +
+ The value specified by barrier is invalid. +
+

+The pthread_barrier_init function shall fail if: +

+
+
EAGAIN +
+ The system lacks the necessary resources to initialize another + barrier. +
+ EINVAL +
+ The value specified by count is equal to zero. +
+ ENOMEM +
+ Insufficient memory exists to initialize the barrier. +
+

+The pthread_barrier_init function may fail if: +

+
+
EBUSY +
+ The implementation has detected an attempt to reinitialize a barrier + while it is in use (for example, while being used in a + pthread_barrier_wait(3) + call) by another thread. +
+ EINVAL +
+ The value specified by attr is invalid. +
+

+These functions shall not return an error code of [EINTR]. +

+

The following sections are informative. +

+

Examples

+

None. +

+

Application Usage

+

The pthread_barrier_destroy and pthread_barrier_init +functions are part of the Barriers option and need not be provided on +all implementations. +

+

Pthreads-w32 defines _POSIX_BARRIERS to indicate +that these routines are implemented and may be used.

+

Rationale

+

None. +

+

Future Directions

+

None. +

+

Known Bugs

+
+
In + pthreads-win32, + pthread_barrier_wait(3) + may deadlock if the number of running threads able to wait on the + barrier object exceeds the value given as the count + parameter in pthread_barrier_init. +
+

+See Also

+

pthread_barrier_wait(3) +, the Base Definitions volume of IEEE Std 1003.1-2001, +<pthread.h> +

+

Copyright

+

Portions of this text are reprinted and reproduced in electronic +form from IEEE Std 1003.1, 2003 Edition, Standard for Information +Technology -- Portable Operating System Interface (POSIX), The Open +Group Base Specifications Issue 6, Copyright (C) 2001-2003 by the +Institute of Electrical and Electronics Engineers, Inc and The Open +Group. In the event of any discrepancy between this version and the +original IEEE and The Open Group Standard, the original IEEE and The +Open Group Standard is the referee document. The original Standard +can be obtained online at http://www.opengroup.org/unix/online.html +. +

+

Modified by Ross Johnson for use with Pthreads-w32.

+
+

Table of Contents

+ + + \ No newline at end of file diff --git a/pthreads/manual/pthread_barrier_wait.html b/pthreads/manual/pthread_barrier_wait.html new file mode 100644 index 000000000..693d8bd15 --- /dev/null +++ b/pthreads/manual/pthread_barrier_wait.html @@ -0,0 +1,167 @@ + + + + + "PTHREAD_BARRIER_WAIT"(P) manual page + + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

pthread_barrier_wait - synchronize at a barrier (ADVANCED +REALTIME THREADS) +

+

Synopsis

+

#include <pthread.h> +

+

int pthread_barrier_wait(pthread_barrier_t *barrier); + +

+

Description

+

The pthread_barrier_wait function shall synchronize +participating threads at the barrier referenced by barrier. +The calling thread shall block until the required number of threads +have called pthread_barrier_wait specifying the barrier. +

+

When the required number of threads have called +pthread_barrier_wait specifying the barrier, the constant +PTHREAD_BARRIER_SERIAL_THREAD shall be returned to one +unspecified thread and zero shall be returned to each of the +remaining threads. At this point, the barrier shall be reset to the +state it had as a result of the most recent pthread_barrier_init(3) +function that referenced it. +

+

The constant PTHREAD_BARRIER_SERIAL_THREAD is defined in +<pthread.h> and its value shall be distinct from any +other value returned by pthread_barrier_wait . +

+

The results are undefined if this function is called with an +uninitialized barrier. +

+

If a signal is delivered to a thread blocked on a barrier, upon +return from the signal handler the thread shall resume waiting at the +barrier if the barrier wait has not completed (that is, if the +required number of threads have not arrived at the barrier during the +execution of the signal handler); otherwise, the thread shall +continue as normal from the completed barrier wait. Until the thread +in the signal handler returns from it, it is unspecified whether +other threads may proceed past the barrier once they have all reached +it. +

+

A thread that has blocked on a barrier shall not prevent any +unblocked thread that is eligible to use the same processing +resources from eventually making forward progress in its execution. +Eligibility for processing resources shall be determined by the +scheduling policy. +

+

Return Value

+

Upon successful completion, the pthread_barrier_wait +function shall return PTHREAD_BARRIER_SERIAL_THREAD for a +single (arbitrary) thread synchronized at the barrier and zero for +each of the other threads. Otherwise, an error number shall be +returned to indicate the error. +

+

Errors

+

The pthread_barrier_wait function may fail if: +

+
+
EINVAL +
+ The value specified by barrier does not refer to an + initialized barrier object. +
+

+This function shall not return an error code of [EINTR]. +

+

The following sections are informative. +

+

Examples

+

None. +

+

Application Usage

+

Applications using this function may be subject to priority +inversion, as discussed in the Base Definitions volume of +IEEE Std 1003.1-2001, Section 3.285, Priority Inversion. +

+

The pthread_barrier_wait function is part of the Barriers +option and need not be provided on all implementations. +

+

Pthreads-w32 defines _POSIX_BARRIERS to indicate +that this routine is implemented and may be used.

+

Rationale

+

None. +

+

Future Directions

+

None. +

+

Known Bugs

+
+
In + pthreads-win32, + pthread_barrier_wait may deadlock if the number of running + threads able to wait on the barrier object exceeds the value given + as the count parameter in + pthread_barrier_init(3). +
+

+See Also

+

pthread_barrier_destroy(3), +pthread_barrier_init(3), +the Base Definitions volume of IEEE Std 1003.1-2001, +<pthread.h> +

+

Copyright

+

Portions of this text are reprinted and reproduced in electronic +form from IEEE Std 1003.1, 2003 Edition, Standard for Information +Technology -- Portable Operating System Interface (POSIX), The Open +Group Base Specifications Issue 6, Copyright (C) 2001-2003 by the +Institute of Electrical and Electronics Engineers, Inc and The Open +Group. In the event of any discrepancy between this version and the +original IEEE and The Open Group Standard, the original IEEE and The +Open Group Standard is the referee document. The original Standard +can be obtained online at http://www.opengroup.org/unix/online.html +. +

+

Modified by Ross Johnson for use with Pthreads-w32.

+
+

Table of Contents

+ + + \ No newline at end of file diff --git a/pthreads/manual/pthread_barrierattr_init.html b/pthreads/manual/pthread_barrierattr_init.html new file mode 100644 index 000000000..a7c802735 --- /dev/null +++ b/pthreads/manual/pthread_barrierattr_init.html @@ -0,0 +1,142 @@ + + + + + "PTHREAD_BARRIERATTR_DESTROY"(P) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

pthread_barrierattr_destroy, pthread_barrierattr_init - destroy +and initialize the barrier attributes object (ADVANCED REALTIME +THREADS) +

+

Synopsis

+

#include <pthread.h> +

+

int pthread_barrierattr_destroy(pthread_barrierattr_t *attr); +
int pthread_barrierattr_init(pthread_barrierattr_t *attr); + +

+

Description

+

The pthread_barrierattr_destroy function shall destroy a +barrier attributes object. A destroyed attr attributes object +can be reinitialized using pthread_barrierattr_init ; the +results of otherwise referencing the object after it has been +destroyed are undefined. An implementation may cause +pthread_barrierattr_destroy to set the object referenced by +attr to an invalid value. +

+

The pthread_barrierattr_init function shall initialize a +barrier attributes object attr with the default value for all +of the attributes defined by the implementation. +

+

Results are undefined if pthread_barrierattr_init is called +specifying an already initialized attr attributes object. +

+

After a barrier attributes object has been used to initialize one +or more barriers, any function affecting the attributes object +(including destruction) shall not affect any previously initialized +barrier. +

+

Return Value

+

If successful, the pthread_barrierattr_destroy and +pthread_barrierattr_init functions shall return zero; +otherwise, an error number shall be returned to indicate the error. +

+

Errors

+

The pthread_barrierattr_destroy function may fail if: +

+
+
EINVAL +
+ The value specified by attr is invalid. +
+

+The pthread_barrierattr_init function shall fail if: +

+
+
ENOMEM +
+ Insufficient memory exists to initialize the barrier attributes + object. +
+

+These functions shall not return an error code of [EINTR]. +

+

The following sections are informative. +

+

Examples

+

None. +

+

Application Usage

+

The pthread_barrierattr_destroy and +pthread_barrierattr_init functions are part of the Barriers +option and need not be provided on all implementations. +

+

Pthreads-w32 defines _POSIX_BARRIERS to indicate +that these routines are implemented and may be used.

+

Rationale

+

None. +

+

Future Directions

+

None. +

+

See Also

+

pthread_barrierattr_getpshared(3) +, pthread_barrierattr_setpshared(3) +, the Base Definitions volume of IEEE Std 1003.1-2001, +<pthread.h>. +

+

Copyright

+

Portions of this text are reprinted and reproduced in electronic +form from IEEE Std 1003.1, 2003 Edition, Standard for Information +Technology -- Portable Operating System Interface (POSIX), The Open +Group Base Specifications Issue 6, Copyright (C) 2001-2003 by the +Institute of Electrical and Electronics Engineers, Inc and The Open +Group. In the event of any discrepancy between this version and the +original IEEE and The Open Group Standard, the original IEEE and The +Open Group Standard is the referee document. The original Standard +can be obtained online at http://www.opengroup.org/unix/online.html +. +

+

Modified by Ross Johnson for use with Pthreads-w32.

+
+

Table of Contents

+ + + diff --git a/pthreads/manual/pthread_barrierattr_setpshared.html b/pthreads/manual/pthread_barrierattr_setpshared.html new file mode 100644 index 000000000..2c62d3dce --- /dev/null +++ b/pthreads/manual/pthread_barrierattr_setpshared.html @@ -0,0 +1,159 @@ + + + + + "PTHREAD_BARRIERATTR_GETPSHARED"(P) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

pthread_barrierattr_getpshared, pthread_barrierattr_setpshared - +get and set the process-shared attribute of the barrier attributes +object (ADVANCED REALTIME THREADS) +

+

Synopsis

+

#include <pthread.h> +

+

int pthread_barrierattr_getpshared(const pthread_barrierattr_t +* restrict attr, int *restrict pshared); +
int pthread_barrierattr_setpshared(pthread_barrierattr_t *attr, +int pshared); +

+

Description

+

The pthread_barrierattr_getpshared function shall obtain +the value of the process-shared attribute from the attributes +object referenced by attr. The pthread_barrierattr_setpshared +function shall set the process-shared attribute in an +initialized attributes object referenced by attr. +

+

The process-shared attribute is set to +PTHREAD_PROCESS_SHARED to permit a barrier to be operated upon by any +thread that has access to the memory where the barrier is allocated. +If the process-shared attribute is PTHREAD_PROCESS_PRIVATE, +the barrier shall only be operated upon by threads created within the +same process as the thread that initialized the barrier; if threads +of different processes attempt to operate on such a barrier, the +behavior is undefined. The default value of the attribute shall be +PTHREAD_PROCESS_PRIVATE. Both constants PTHREAD_PROCESS_SHARED and +PTHREAD_PROCESS_PRIVATE are defined in <pthread.h>. +

+

Pthreads-w32 defines _POSIX_THREAD_PROCESS_SHARED in +pthread.h as -1 to indicate that these routines are implemented but +that the process shared attribute is not supported.

+

Additional attributes, their default values, and the names of the +associated functions to get and set those attribute values are +implementation-defined. +

+

Return Value

+

If successful, the pthread_barrierattr_getpshared function +shall return zero and store the value of the process-shared +attribute of attr into the object referenced by the pshared +parameter. Otherwise, an error number shall be returned to indicate +the error. +

+

If successful, the pthread_barrierattr_setpshared function +shall return zero; otherwise, an error number shall be returned to +indicate the error. +

+

Errors

+

These functions may fail if: +

+
+
EINVAL +
+ The value specified by attr is invalid. +
+ The pthread_barrierattr_setpshared function may fail if: +
+ EINVAL +
+ The new value specified for the process-shared attribute is + not one of the legal values PTHREAD_PROCESS_SHARED or + PTHREAD_PROCESS_PRIVATE. +
+ ENOSYS +
+ The value specified by attr was PTHREAD_PROCESS_SHARED + (Pthreads-w32).
+

+These functions shall not return an error code of [EINTR]. +

+

The following sections are informative. +

+

Examples

+

None. +

+

Application Usage

+

The pthread_barrierattr_getpshared and +pthread_barrierattr_setpshared functions are part of the +Barriers option and need not be provided on all implementations. +

+

Pthreads-w32 defines _POSIX_BARRIERS and +_POSIX_THREAD_PROCESS_SHARED in pthread.h as -1 to indicate +that these routines are implemented and may be used, but do not +support the process shared option.

+

Rationale

+

None. +

+

Future Directions

+

None. +

+

See Also

+

pthread_barrier_destroy(3) +, pthread_barrierattr_destroy(3) +, pthread_barrierattr_init(3) +, the Base Definitions volume of IEEE Std 1003.1-2001, +<pthread.h> +

+

Copyright

+

Portions of this text are reprinted and reproduced in electronic +form from IEEE Std 1003.1, 2003 Edition, Standard for Information +Technology -- Portable Operating System Interface (POSIX), The Open +Group Base Specifications Issue 6, Copyright (C) 2001-2003 by the +Institute of Electrical and Electronics Engineers, Inc and The Open +Group. In the event of any discrepancy between this version and the +original IEEE and The Open Group Standard, the original IEEE and The +Open Group Standard is the referee document. The original Standard +can be obtained online at http://www.opengroup.org/unix/online.html +. +

+

Modified by Ross Johnson for use with Pthreads-w32.

+
+

Table of Contents

+ + + diff --git a/pthreads/manual/pthread_cancel.html b/pthreads/manual/pthread_cancel.html new file mode 100644 index 000000000..d9acd7727 --- /dev/null +++ b/pthreads/manual/pthread_cancel.html @@ -0,0 +1,205 @@ + + + + + PTHREAD_CANCEL(3) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

pthread_cancel, pthread_setcancelstate, pthread_setcanceltype, +pthread_testcancel - thread cancellation +

+

Synopsis

+

#include <pthread.h> +

+

int pthread_cancel(pthread_t thread); +

+

int pthread_setcancelstate(int state, int +*oldstate); +

+

int pthread_setcanceltype(int type, int +*oldtype); +

+

void pthread_testcancel(void); +

+

Description

+

Cancellation is the mechanism by which a thread can terminate the +execution of another thread. More precisely, a thread can send a +cancellation request to another thread. Depending on its settings, +the target thread can then either ignore the request, honor it +immediately, or defer it until it reaches a cancellation point. +

+

When a thread eventually honors a cancellation request, it +performs as if pthread_exit(PTHREAD_CANCELED) has been called +at that point: all cleanup handlers are executed in reverse order, +destructor functions for thread-specific data are called, and finally +the thread stops executing with the return value PTHREAD_CANCELED. +See pthread_exit(3) for more +information. +

+

pthread_cancel sends a cancellation request to the thread +denoted by the thread argument. +

+

pthread_setcancelstate changes the cancellation state for +the calling thread -- that is, whether cancellation requests are +ignored or not. The state argument is the new cancellation +state: either PTHREAD_CANCEL_ENABLE to enable cancellation, or +PTHREAD_CANCEL_DISABLE to disable cancellation (cancellation +requests are ignored). If oldstate is not NULL, the +previous cancellation state is stored in the location pointed to by +oldstate, and can thus be restored later by another call to +pthread_setcancelstate. +

+

pthread_setcanceltype changes the type of responses to +cancellation requests for the calling thread: asynchronous +(immediate) or deferred. The type argument is the new +cancellation type: either PTHREAD_CANCEL_ASYNCHRONOUS to +cancel the calling thread as soon as the cancellation request is +received, or PTHREAD_CANCEL_DEFERRED to keep the cancellation +request pending until the next cancellation point. If oldtype +is not NULL, the previous cancellation state is stored in the +location pointed to by oldtype, and can thus be restored later +by another call to pthread_setcanceltype. +

+

Pthreads-w32 provides two levels of support for +PTHREAD_CANCEL_ASYNCHRONOUS: full and partial. Full support +requires an additional DLL and driver be installed on the Windows +system (see the See Also section below) that allows blocked threads +to be cancelled immediately. Partial support means that the target +thread will not cancel until it resumes execution naturally. Partial +support is provided if either the DLL or the driver are not +automatically detected by the pthreads-w32 library at run-time.

+

Threads are always created by pthread_create(3) +with cancellation enabled and deferred. That is, the initial +cancellation state is PTHREAD_CANCEL_ENABLE and the initial +type is PTHREAD_CANCEL_DEFERRED. +

+

Cancellation points are those points in the program execution +where a test for pending cancellation requests is performed and +cancellation is executed if positive. The following POSIX threads +functions are cancellation points: +

+

pthread_join(3) +
pthread_cond_wait(3) +
pthread_cond_timedwait(3) +
pthread_testcancel(3)
sem_wait(3) +
sem_timedwait(3)
sigwait(3)

+

Pthreads-w32 provides two functions to enable additional +cancellation points to be created in user functions that block on +Win32 HANDLEs:

+

pthreadCancelableWait() +
pthreadCancelableTimedWait()

+

All other POSIX threads functions are guaranteed not to be +cancellation points. That is, they never perform cancellation in +deferred cancellation mode. +

+

pthread_testcancel does nothing except testing for pending +cancellation and executing it. Its purpose is to introduce explicit +checks for cancellation in long sequences of code that do not call +cancellation point functions otherwise. +

+

Return Value

+

pthread_cancel, pthread_setcancelstate and +pthread_setcanceltype return 0 on success and a non-zero error +code on error. +

+

Errors

+

pthread_cancel returns the following error code on error: +

+
+
+
ESRCH +
+ no thread could be found corresponding to that specified by the + thread ID. +
+
+

+pthread_setcancelstate returns the following error code on +error: +

+
+
+
EINVAL +
+ the state argument is not +
+
+
+PTHREAD_CANCEL_ENABLE nor PTHREAD_CANCEL_DISABLE +
+

pthread_setcanceltype returns the following error code on +error: +

+
+
+
EINVAL +
+ the type argument is not +
+
+
+PTHREAD_CANCEL_DEFERRED nor PTHREAD_CANCEL_ASYNCHRONOUS +
+

Author

+

Xavier Leroy <Xavier.Leroy@inria.fr> +

+

Modified by Ross Johnson for use with Pthreads-w32.

+

See Also

+

pthread_exit(3) , +pthread_cleanup_push(3) +, pthread_cleanup_pop(3) +, Pthreads-w32 package README file 'Prerequisites' section. +

+

Bugs

+

POSIX specifies that a number of system calls (basically, all +system calls that may block, such as read(2) +, write(2) , wait(2) +, etc.) and library functions that may call these system calls (e.g. +fprintf(3) ) are cancellation +points. Pthreads-win32 is not integrated enough with the C +library to implement this, and thus none of the C library functions +is a cancellation point. +

+

A workaround for these calls is to temporarily switch to +asynchronous cancellation (assuming full asynchronous cancellation +support is installed). So, checking for cancellation during a read +system call, for instance, can be achieved as follows: +

+


+
+
pthread_setcanceltype(PTHREAD_CANCEL_ASYNCHRONOUS, &oldCancelType);
+read(fd, buffer, length);
+pthread_setcanceltype(oldCancelType, NULL);
+
+
Table of Contents
+ + + diff --git a/pthreads/manual/pthread_cleanup_push.html b/pthreads/manual/pthread_cleanup_push.html new file mode 100644 index 000000000..0fc071e19 --- /dev/null +++ b/pthreads/manual/pthread_cleanup_push.html @@ -0,0 +1,140 @@ + + + + + PTHREAD_CLEANUP(3) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

pthread_cleanup_push, pthread_cleanup_pop - install and remove +cleanup handlers +

+

Synopsis

+

#include <pthread.h> +

+

void pthread_cleanup_push(void (*routine) (void +*), void *arg); +

+

void pthread_cleanup_pop(int execute); +

+

Description

+

Cleanup handlers are functions that get called when a thread +terminates, either by calling pthread_exit(3) +or because of cancellation. Cleanup handlers are installed and +removed following a stack-like discipline. +

+

The purpose of cleanup handlers is to free the resources that a +thread may hold at the time it terminates. In particular, if a thread +exits or is cancelled while it owns a locked mutex, the mutex will +remain locked forever and prevent other threads from executing +normally. The best way to avoid this is, just before locking the +mutex, to install a cleanup handler whose effect is to unlock the +mutex. Cleanup handlers can be used similarly to free blocks +allocated with malloc(3) or close +file descriptors on thread termination. +

+

pthread_cleanup_push installs the routine function +with argument arg as a cleanup handler. From this point on to +the matching pthread_cleanup_pop, the function routine +will be called with arguments arg when the thread terminates, +either through pthread_exit(3) +or by cancellation. If several cleanup handlers are active at that +point, they are called in LIFO order: the most recently installed +handler is called first. +

+

pthread_cleanup_pop removes the most recently installed +cleanup handler. If the execute argument is not 0, it also +executes the handler, by calling the routine function with +arguments arg. If the execute argument is 0, the +handler is only removed but not executed. +

+

Matching pairs of pthread_cleanup_push and +pthread_cleanup_pop must occur in the same function, at the +same level of block nesting. Actually, pthread_cleanup_push +and pthread_cleanup_pop are macros, and the expansion of +pthread_cleanup_push introduces an open brace { with +the matching closing brace } being introduced by the expansion +of the matching pthread_cleanup_pop. +

+

Return Value

+
None. +
+

Errors

+
None. +
+

Author

+
Xavier Leroy +<Xavier.Leroy@inria.fr> +
+
Modified by +Ross Johnson for use with Pthreads-w32.
+

See Also

+
pthread_exit(3) +, pthread_cancel(3) , +pthread_setcanceltype(3) . +
+

Example

+
Here is how +to lock a mutex mut in such a way that it will be unlocked if +the thread is canceled while mut is locked: +
+
pthread_cleanup_push(pthread_mutex_unlock, (void *) &mut);
+pthread_mutex_lock(&mut);
+/* do some work */
+pthread_mutex_unlock(&mut);
+pthread_cleanup_pop(0);
+Equivalently, the last two lines can be replaced by +
+
pthread_cleanup_pop(1);
+Notice that the code above is safe only in deferred cancellation mode +(see pthread_setcanceltype(3) +). In asynchronous cancellation mode, a cancellation can occur +between pthread_cleanup_push and pthread_mutex_lock, or +between pthread_mutex_unlock and pthread_cleanup_pop, +resulting in both cases in the thread trying to unlock a mutex not +locked by the current thread. This is the main reason why +asynchronous cancellation is difficult to use. +
+
If the code +above must also work in asynchronous cancellation mode, then it must +switch to deferred mode for locking and unlocking the mutex: +
+
pthread_setcanceltype(PTHREAD_CANCEL_DEFERRED, &oldtype);
+pthread_cleanup_push(pthread_mutex_unlock, (void *) &mut);
+pthread_mutex_lock(&mut);
+/* do some work */
+pthread_cleanup_pop(1);
+pthread_setcanceltype(oldtype, NULL);
+
+
+Table of Contents
+ + + diff --git a/pthreads/manual/pthread_cond_init.html b/pthreads/manual/pthread_cond_init.html new file mode 100644 index 000000000..937e490a0 --- /dev/null +++ b/pthreads/manual/pthread_cond_init.html @@ -0,0 +1,313 @@ + + + + + PTHREAD_COND(3) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

pthread_cond_init, pthread_cond_destroy, pthread_cond_signal, +pthread_cond_broadcast, pthread_cond_wait, pthread_cond_timedwait - +operations on conditions +

+

Synopsis

+

#include <pthread.h> +

+

pthread_cond_t cond = PTHREAD_COND_INITIALIZER; +

+

int pthread_cond_init(pthread_cond_t *cond, +pthread_condattr_t *cond_attr); +

+

int pthread_cond_signal(pthread_cond_t *cond); +

+

int pthread_cond_broadcast(pthread_cond_t *cond); +

+

int pthread_cond_wait(pthread_cond_t *cond, +pthread_mutex_t *mutex); +

+

int pthread_cond_timedwait(pthread_cond_t *cond, +pthread_mutex_t *mutex, const struct timespec +*abstime); +

+

int pthread_cond_destroy(pthread_cond_t *cond); +

+

Description

+

A condition (short for ‘‘condition variable’’) is a +synchronization device that allows threads to suspend execution and +relinquish the processors until some predicate on shared data is +satisfied. The basic operations on conditions are: signal the +condition (when the predicate becomes true), and wait for the +condition, suspending the thread execution until another thread +signals the condition. +

+

A condition variable must always be associated with a mutex, to +avoid the race condition where a thread prepares to wait on a +condition variable and another thread signals the condition just +before the first thread actually waits on it. +

+

pthread_cond_init initializes the condition variable cond, +using the condition attributes specified in cond_attr, or +default attributes if cond_attr is NULL. +

+

Variables of type pthread_cond_t can also be initialized +statically, using the constant PTHREAD_COND_INITIALIZER. In +the Pthreads-w32 implementation, an application should still +call pthread_cond_destroy at some point to ensure that any +resources consumed by the condition variable are released.

+

pthread_cond_signal restarts one of the threads that are +waiting on the condition variable cond. If no threads are +waiting on cond, nothing happens. If several threads are +waiting on cond, exactly one is restarted, but it is not +specified which. +

+

pthread_cond_broadcast restarts all the threads that are +waiting on the condition variable cond. Nothing happens if no +threads are waiting on cond. +

+

pthread_cond_wait atomically unlocks the mutex (as +per pthread_unlock_mutex) and waits for the condition variable +cond to be signalled. The thread execution is suspended and +does not consume any CPU time until the condition variable is +signalled. The mutex must be locked by the calling thread on +entrance to pthread_cond_wait. Before returning to the calling +thread, pthread_cond_wait re-acquires mutex (as per +pthread_lock_mutex). +

+

Unlocking the mutex and suspending on the condition variable is +done atomically. Thus, if all threads always acquire the mutex before +signalling the condition, this guarantees that the condition cannot +be signalled (and thus ignored) between the time a thread locks the +mutex and the time it waits on the condition variable. +

+

pthread_cond_timedwait atomically unlocks mutex and +waits on cond, as pthread_cond_wait does, but it also +bounds the duration of the wait. If cond has not been +signalled within the amount of time specified by abstime, the +mutex mutex is re-acquired and pthread_cond_timedwait +returns the error ETIMEDOUT. The abstime parameter +specifies an absolute time, with the same origin as time(2) +and gettimeofday(2). +

+

pthread_cond_destroy destroys a condition variable, freeing +the resources it might hold. No threads must be waiting on the +condition variable on entrance to pthread_cond_destroy.

+

Cancellation

+

pthread_cond_wait and pthread_cond_timedwait are +cancellation points. If a thread is cancelled while suspended in one +of these functions, the thread immediately resumes execution, then +locks again the mutex argument to pthread_cond_wait and +pthread_cond_timedwait, and finally executes the cancellation. +Consequently, cleanup handlers are assured that mutex is +locked when they are called. +

+

Async-signal Safety

+

The condition functions are not async-signal safe, and should not +be called from a signal handler. In particular, calling +pthread_cond_signal or pthread_cond_broadcast from a +signal handler may deadlock the calling thread. +

+

Return Value

+

All condition variable functions return 0 on success and a +non-zero error code on error. +

+

Errors

+

pthread_cond_init, pthread_cond_signal, +pthread_cond_broadcast, and pthread_cond_wait never +return an error code. +

+

The pthread_cond_init function returns the following error +codes on error: +

+
+
+
EINVAL +
+ The cond argument is invalid. +
+ ENOMEM +
+
+
+There was not enough memory to allocate the condition variable. +
+

The pthread_cond_signal function returns the following +error codes on error: +

+
+
+
EINVAL +
+ The cond argument is invalid. +
+
+

+The pthread_cond_broadcast function returns the following +error codes on error: +

+
+
+
EINVAL +
+ The cond argument is invalid. +
+
+

+The pthread_cond_wait function returns the following error +codes on error: +

+
+
+
EINVAL +
+ The cond argument is invalid. +
+ ENOMEM +
+
+
+There was not enough memory to allocate the statically initialised +condition variable. Statically initialised condition variables are +dynamically allocated by the first thread to wait on them.
+

The pthread_cond_timedwait function returns the following +error codes on error: +

+
+
+
EINVAL +
+
+

+The cond argument is invalid. +

+
+
+
ETIMEDOUT +
+ The condition variable was not signalled before the timeout + specified by abstime +
+ ENOMEM +
+
+
+There was not enough memory to allocate the statically initialised +condition variable. Statically initialised condition variables are +dynamically allocated by the first thread to wait on them. +
+

The pthread_cond_destroy function returns the following +error code on error: +

+
+
+
EINVAL +
+
+

+The cond argument is invalid. +

+
+
+
EBUSY +
+ Some threads are currently waiting on cond. +
+
+

+Author

+

Xavier Leroy <Xavier.Leroy@inria.fr> +

+

Modified by Ross Johnson for use with Pthreads-w32.

+

See Also

+

pthread_condattr_init(3) +, pthread_mutex_lock(3) +, pthread_mutex_unlock(3) +, pthread_cancel(3). +

+

Example

+

Consider two shared variables x and y, protected by +the mutex mut, and a condition variable cond that is to +be signaled whenever x becomes greater than y. +

+
int x,y;
+pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER;
+pthread_cond_t cond = PTHREAD_COND_INITIALIZER;
+Waiting until x is greater than y is performed as +follows: +
+
pthread_mutex_lock(&mut);
+while (x <= y) {
+        pthread_cond_wait(&cond, &mut);
+}
+/* operate on x and y */
+pthread_mutex_unlock(&mut);
+Modifications on x and y that may cause x to +become greater than y should signal the condition if needed: +
+
pthread_mutex_lock(&mut);
+/* modify x and y */
+if (x > y) pthread_cond_broadcast(&cond);
+pthread_mutex_unlock(&mut);
+If it can be proved that at most one waiting thread needs to be waken +up (for instance, if there are only two threads communicating through +x and y), pthread_cond_signal can be used as a +slightly more efficient alternative to pthread_cond_broadcast. +If in doubt, use pthread_cond_broadcast. +
+
To wait for x to +become greater than y with a timeout of 5 seconds, do: +
+
struct timeval now;
+struct timespec timeout;
+int retcode;
+pthread_mutex_lock(&mut);
+gettimeofday(&now);
+timeout.tv_sec = now.tv_sec + 5;
+timeout.tv_nsec = now.tv_usec * 1000;
+retcode = 0;
+while (x <= y && retcode != ETIMEDOUT) {
+        retcode = pthread_cond_timedwait(&cond, &mut, &timeout);
+}
+if (retcode == ETIMEDOUT) {
+        /* timeout occurred */
+} else {
+        /* operate on x and y */
+}
+pthread_mutex_unlock(&mut);
+
+
+Table of Contents
+ + + diff --git a/pthreads/manual/pthread_condattr_init.html b/pthreads/manual/pthread_condattr_init.html new file mode 100644 index 000000000..8b8b2f2aa --- /dev/null +++ b/pthreads/manual/pthread_condattr_init.html @@ -0,0 +1,98 @@ + + + + + PTHREAD_CONDATTR(3) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

pthread_condattr_init, pthread_condattr_destroy - condition +creation +

+

attributes +

+

Synopsis

+

#include <pthread.h> +

+

int pthread_condattr_init(pthread_condattr_t *attr); +

+

int pthread_condattr_destroy(pthread_condattr_t *attr); +

+

Description

+

Condition attributes can be specified at condition creation time, +by passing a condition attribute object as second argument to +pthread_cond_init(3) . +Passing NULL is equivalent to passing a condition attribute +object with all attributes set to their default values. +

+

pthread_condattr_init initializes the condition attribute +object attr and fills it with default values for the +attributes. pthread_condattr_destroy destroys a condition +attribute object, which must not be reused until it is reinitialized.

+

Pthreads-w32 defines _POSIX_THREAD_PROCESS_SHARED in +pthread.h as -1 to indicate that the attribute routines are +implemented but that the process shared attribute is not supported.

+

Return Value

+

All condition variable functions return 0 on success and a +non-zero error code on error.

+

Errors

+

The pthread_condattr_init function returns the following +error code on error: +

+
+
+
ENOMEM +
+ The was insufficient memory to create the attribute. + +
+
+

+The pthread_condattr_destroy function returns the following +error code on error: +

+
+
+
EINVAL +
+ The attr argument is not valid. + +
+
+

+Author

+

Xavier Leroy <Xavier.Leroy@inria.fr> +

+

Modified by Ross Johnson for use with Pthreads-w32.

+

See Also

+

pthread_cond_init(3) . +

+
+

Table of Contents

+ + + diff --git a/pthreads/manual/pthread_condattr_setpshared.html b/pthreads/manual/pthread_condattr_setpshared.html new file mode 100644 index 000000000..eda357e07 --- /dev/null +++ b/pthreads/manual/pthread_condattr_setpshared.html @@ -0,0 +1,153 @@ + + + + + "PTHREAD_CONDATTR_GETPSHARED"(P) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

pthread_condattr_getpshared, pthread_condattr_setpshared - get and +set the process-shared condition variable attributes +

+

Synopsis

+

#include <pthread.h> +

+

int pthread_condattr_getpshared(const pthread_condattr_t +*restrict attr, int *restrict pshared); +
int pthread_condattr_setpshared(pthread_condattr_t *attr, +int pshared); +

+

Description

+

The pthread_condattr_getpshared function shall obtain the +value of the process-shared attribute from the attributes +object referenced by attr. The pthread_condattr_setpshared +function shall set the process-shared attribute in an +initialized attributes object referenced by attr. +

+

The process-shared attribute is set to +PTHREAD_PROCESS_SHARED to permit a condition variable to be +operated upon by any thread that has access to the memory where the +condition variable is allocated, even if the condition variable is +allocated in memory that is shared by multiple processes. If the +process-shared attribute is PTHREAD_PROCESS_PRIVATE, +the condition variable shall only be operated upon by threads created +within the same process as the thread that initialized the condition +variable; if threads of differing processes attempt to operate on +such a condition variable, the behavior is undefined. The default +value of the attribute is PTHREAD_PROCESS_PRIVATE. +

+

Pthreads-w32 defines _POSIX_THREAD_PROCESS_SHARED in +pthread.h as -1 to indicate that these routines are implemented but +that the process shared attribute is not supported.

+

Return Value

+

If successful, the pthread_condattr_setpshared function +shall return zero; otherwise, an error number shall be returned to +indicate the error. +

+

If successful, the pthread_condattr_getpshared function +shall return zero and store the value of the process-shared +attribute of attr into the object referenced by the pshared +parameter. Otherwise, an error number shall be returned to indicate +the error. +

+

Errors

+

The pthread_condattr_getpshared and +pthread_condattr_setpshared functions may fail if: +

+
+
EINVAL +
+ The value specified by attr is invalid. +
+

+The pthread_condattr_setpshared function may fail if: +

+
+
EINVAL +
+ The new value specified for the attribute is outside the range of + legal values for that attribute. +
+ ENOSYS +
+ The value specified by attr was PTHREAD_PROCESS_SHARED + (Pthreads-w32).
+

+These functions shall not return an error code of [EINTR]. +

+

The following sections are informative. +

+

Examples

+

None. +

+

Application Usage

+

Pthreads-w32 defines _POSIX_THREAD_PROCESS_SHARED in +pthread.h as -1 to indicate that these routines are implemented and +may be used, but do not support the process shared option.

+

Rationale

+

None. +

+

Future Directions

+

None. +

+

See Also

+

pthread_create(3) , +pthread_cond_destroy(3) , +pthread_condattr_destroy(3) +, pthread_mutex_destroy(3) +, the Base Definitions volume of IEEE Std 1003.1-2001, +<pthread.h> +

+

Copyright

+

Portions of this text are reprinted and reproduced in electronic +form from IEEE Std 1003.1, 2003 Edition, Standard for Information +Technology -- Portable Operating System Interface (POSIX), The Open +Group Base Specifications Issue 6, Copyright (C) 2001-2003 by the +Institute of Electrical and Electronics Engineers, Inc and The Open +Group. In the event of any discrepancy between this version and the +original IEEE and The Open Group Standard, the original IEEE and The +Open Group Standard is the referee document. The original Standard +can be obtained online at http://www.opengroup.org/unix/online.html +. +

+

Modified by Ross Johnson for use with Pthreads-w32.

+
+

Table of Contents

+ + + diff --git a/pthreads/manual/pthread_create.html b/pthreads/manual/pthread_create.html new file mode 100644 index 000000000..d1ebbc3e1 --- /dev/null +++ b/pthreads/manual/pthread_create.html @@ -0,0 +1,94 @@ + + + + + PTHREAD_CREATE(3) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

pthread_create - create a new thread +

+

Synopsis

+

#include <pthread.h> +

+

int pthread_create(pthread_t * thread, +pthread_attr_t * attr, void * (*start_routine)(void +*), void * arg); +

+

Description

+

pthread_create creates a new thread of control that +executes concurrently with the calling thread. The new thread applies +the function start_routine passing it arg as first +argument. The new thread terminates either explicitly, by calling +pthread_exit(3) , or +implicitly, by returning from the start_routine function. The +latter case is equivalent to calling pthread_exit(3) +with the result returned by start_routine as exit code. +

+

The initial signal state of the new thread is inherited from it's +creating thread and there are no pending signals. Pthreads-w32 +does not yet implement signals.

+

The attr argument specifies thread attributes to be applied +to the new thread. See pthread_attr_init(3) +for a complete list of thread attributes. The attr argument +can also be NULL, in which case default attributes are used: +the created thread is joinable (not detached) and has default (non +real-time) scheduling policy. +

+

Return Value

+

On success, the identifier of the newly created thread is stored +in the location pointed by the thread argument, and a 0 is +returned. On error, a non-zero error code is returned. +

+

Errors

+
+
EAGAIN +
+
+
+ Not enough system resources to create a process for the new + thread, or
more than PTHREAD_THREADS_MAX threads are + already active. +
+
+
+

+Author

+

Xavier Leroy <Xavier.Leroy@inria.fr> +

+

Modified by Ross Johnson for use with Pthreads-w32.

+

See Also

+

pthread_exit(3) , +pthread_join(3) , +pthread_detach(3) , +pthread_attr_init(3) . +

+
+

Table of Contents

+ + + diff --git a/pthreads/manual/pthread_delay_np.html b/pthreads/manual/pthread_delay_np.html new file mode 100644 index 000000000..ce533e24e --- /dev/null +++ b/pthreads/manual/pthread_delay_np.html @@ -0,0 +1,71 @@ + + + + + PTHREAD_DELAY_NP manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

pthread_delay_np – suspend the +thread for a specified period

+

Synopsis

+

#include <pthread.h> +

+

int pthread_delay_np (const struct timespec *interval);

+

Description

+

pthread_delay_np 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 cancellation request.

+

Cancellation

+

pthread_delay_np is a cancellation point.

+

Return Value

+

If an error condition occurs, pthread_delay_np returns an +integer value indicating the type of error.

+

Errors

+

The pthread_delay_np function returns the following error +code on error: +

+
+
+
EINVAL +
+
+

+The value specified by interval is invalid.

+

Author

+

Ross Johnson for use with Pthreads-w32.

+
+

Table of Contents

+ + + diff --git a/pthreads/manual/pthread_detach.html b/pthreads/manual/pthread_detach.html new file mode 100644 index 000000000..252adb813 --- /dev/null +++ b/pthreads/manual/pthread_detach.html @@ -0,0 +1,90 @@ + + + + + PTHREAD_DETACH(3) manual page + + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

pthread_detach - put a running thread in the detached state +

+

Synopsis

+

#include <pthread.h> +

+

int pthread_detach(pthread_t th); +

+

Description

+

pthread_detach puts the thread th in the detached +state. This guarantees that the resources consumed by th will +be freed immediately when th terminates. However, this +prevents other threads from synchronizing on the termination of th +using pthread_join. If, when pthread_detach is called, +th has already terminated, all of th's remaining +resources will be freed.

+

A thread can be created initially in the detached state, using the +detachstate attribute to pthread_create(3) +. In contrast, pthread_detach applies to threads created in +the joinable state, and which need to be put in the detached state +later. +

+

After pthread_detach completes, subsequent attempts to +perform pthread_join on th will fail. If another thread +is already joining the thread th at the time pthread_detach +is called, th will be detached and pthread_join will +eventually return when th terminates but may not return with +th's correct return code. +

+

Return Value

+

On success, 0 is returned. On error, a non-zero error code is +returned. +

+

Errors

+
+
ESRCH +
+ No thread could be found corresponding to that specified by th +
+ EINVAL +
+ the thread th is already in the detached state +
+

+Author

+

Xavier Leroy <Xavier.Leroy@inria.fr> +

+

Modified by Ross Johnson for use with Pthreads-w32.

+

See Also

+

pthread_create(3) , +pthread_join(3) , +pthread_attr_setdetachstate(3) +

+
+

Table of Contents

+ + + \ No newline at end of file diff --git a/pthreads/manual/pthread_equal.html b/pthreads/manual/pthread_equal.html new file mode 100644 index 000000000..6f610634e --- /dev/null +++ b/pthreads/manual/pthread_equal.html @@ -0,0 +1,48 @@ + + + + + +PTHREAD_EQUAL(3) manual page + + +Table of Contents

+ +

+

Name

+pthread_equal - compare two thread identifiers +

+

Synopsis

+#include <pthread.h> + +

int pthread_equal(pthread_t thread1, pthread_t thread2); +

+

Description

+pthread_equal +determines if two thread identifiers refer to the same thread. +

+

Return Value

+A +non-zero value is returned if thread1 and thread2 refer to the same thread. +Otherwise, 0 is returned. +

+

Author

+Xavier Leroy <Xavier.Leroy@inria.fr> +

+

See Also

+pthread_self(3) +. +

+ +

+Table of Contents

+

+ + diff --git a/pthreads/manual/pthread_exit.html b/pthreads/manual/pthread_exit.html new file mode 100644 index 000000000..e97318f54 --- /dev/null +++ b/pthreads/manual/pthread_exit.html @@ -0,0 +1,59 @@ + + + + + +PTHREAD_EXIT(3) manual page + + +Table of Contents

+ +

+

Name

+pthread_exit - terminate the calling thread +

+

Synopsis

+#include <pthread.h> + +

void pthread_exit(void *retval); +

+

Description

+pthread_exit terminates the +execution of the calling thread. All cleanup handlers that have been set +for the calling thread with pthread_cleanup_push(3) + are executed in reverse +order (the most recently pushed handler is executed first). Finalization +functions for thread-specific data are then called for all keys that have +non- NULL values associated with them in the calling thread (see pthread_key_create(3) +). +Finally, execution of the calling thread is stopped. +

The retval argument +is the return value of the thread. It can be consulted from another thread +using pthread_join(3) +. +

+

Return Value

+The pthread_exit function never returns. + +

+

Author

+Xavier Leroy <Xavier.Leroy@inria.fr> +

+

See Also

+pthread_create(3) +, pthread_join(3) +. +

+ +

+Table of Contents

+

+ + diff --git a/pthreads/manual/pthread_getw32threadhandle_np.html b/pthreads/manual/pthread_getw32threadhandle_np.html new file mode 100644 index 000000000..7e8de6438 --- /dev/null +++ b/pthreads/manual/pthread_getw32threadhandle_np.html @@ -0,0 +1,57 @@ + + + + + PTHREAD_GETW32THREADHANDLE_NP manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

pthread_getw32threadhandle_np – get +the Win32 thread handle associated with a thread

+

Synopsis

+

#include <pthread.h> +

+

HANDLE pthread_getw32threadhandle_np(pthread_t thread);

+

Description

+

Returns the Win32 native thread HANDLE that the POSIX +thread thread is running as.

+

Applications can use the Win32 handle to set Win32 specific +attributes of the thread.

+

Cancellation

+

None.

+

Return Value

+

pthread_getw32threadhandle_np returns the Win32 native +thread HANDLE for the specified POSIX thread thread.

+

Errors

+

None.

+

Author

+

Ross Johnson for use with Pthreads-w32.

+
+

Table of Contents

+ + + diff --git a/pthreads/manual/pthread_join.html b/pthreads/manual/pthread_join.html new file mode 100644 index 000000000..3e3f3b902 --- /dev/null +++ b/pthreads/manual/pthread_join.html @@ -0,0 +1,118 @@ + + + + + PTHREAD_JOIN(3) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

pthread_join - wait for termination of another thread +

+

Synopsis

+

#include <pthread.h> +

+

int pthread_join(pthread_t th, void +**thread_return); +

+

Description

+

pthread_join suspends the execution of the calling thread +until the thread identified by th terminates, either by +calling pthread_exit(3) or by +being cancelled. +

+

If thread_return is not NULL, the return value of th +is stored in the location pointed to by thread_return. The +return value of th is either the argument it gave to +pthread_exit(3) , or +PTHREAD_CANCELED if th was cancelled. +

+

The joined thread th must be in the joinable state: it must +not have been detached using pthread_detach(3) +or the PTHREAD_CREATE_DETACHED attribute to pthread_create(3) +. +

+

When a joinable thread terminates, its memory resources (thread +descriptor and stack) are not deallocated until another thread +performs pthread_join on it. Therefore, pthread_join +must be called once for each joinable thread created to avoid memory +leaks. +

+

At most one thread can wait for the termination of a given thread. +Calling pthread_join on a thread th on which another +thread is already waiting for termination returns an error. +

+

Cancellation

+

pthread_join is a cancellation point. If a thread is +cancelled while suspended in pthread_join, the thread +execution resumes immediately and the cancellation is executed +without waiting for the th thread to terminate. If +cancellation occurs during pthread_join, the th thread +remains not joined. +

+

Return Value

+

On success, the return value of th is stored in the +location pointed to by thread_return, and 0 is returned. On +error, a non-zero error code is returned. +

+

Errors

+
+
ESRCH +
+ No thread could be found corresponding to that specified by th. +
+ EINVAL +
+ The th thread has been detached. +
+ EINVAL +
+ Another thread is already waiting on termination of th. +
+ EDEADLK +
+ The th argument refers to the calling thread. +
+

+Author

+

Xavier Leroy <Xavier.Leroy@inria.fr> +

+

See Also

+

pthread_exit(3) , +pthread_detach(3) , +pthread_create(3) , +pthread_attr_setdetachstate(3) +, pthread_cleanup_push(3) +, pthread_key_create(3) +. +

+
+

Table of Contents

+ + + diff --git a/pthreads/manual/pthread_key_create.html b/pthreads/manual/pthread_key_create.html new file mode 100644 index 000000000..5ecca6995 --- /dev/null +++ b/pthreads/manual/pthread_key_create.html @@ -0,0 +1,211 @@ + + + + + PTHREAD_SPECIFIC(3) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

pthread_key_create, pthread_key_delete, pthread_setspecific, +pthread_getspecific - management of thread-specific data +

+

Synopsis

+

#include <pthread.h> +

+

int pthread_key_create(pthread_key_t *key, void +(*destr_function) (void *)); +

+

int pthread_key_delete(pthread_key_t key); +

+

int pthread_setspecific(pthread_key_t key, const +void *pointer); +

+

void * pthread_getspecific(pthread_key_t key); +

+

Description

+

Programs often need global or static variables that have different +values in different threads. Since threads share one memory space, +this cannot be achieved with regular variables. Thread-specific data +is the POSIX threads answer to this need. +

+

Each thread possesses a private memory block, the thread-specific +data area, or TSD area for short. This area is indexed by TSD keys. +The TSD area associates values of type void * to TSD keys. TSD +keys are common to all threads, but the value associated with a given +TSD key can be different in each thread. +

+

For concreteness, the TSD areas can be viewed as arrays of void +* pointers, TSD keys as integer indices into these arrays, and +the value of a TSD key as the value of the corresponding array +element in the calling thread. +

+

When a thread is created, its TSD area initially associates NULL +with all keys. +

+

pthread_key_create allocates a new TSD key. The key is +stored in the location pointed to by key. There is a limit of +PTHREAD_KEYS_MAX on the number of keys allocated at a given +time. The value initially associated with the returned key is NULL +in all currently executing threads. +

+

The destr_function argument, if not NULL, specifies +a destructor function associated with the key. When a thread +terminates via pthread_exit or by cancellation, destr_function +is called with arguments the value associated with the key in that +thread. The destr_function is not called if that value is NULL +or the key has been deleted. The order in which destructor +functions are called at thread termination time is unspecified. +

+

Before the destructor function is called, the NULL value is +associated with the key in the current thread. A destructor function +might, however, re-associate non- NULL values to that key or +some other key. To deal with this, if after all the destructors have +been called for all non- NULL values, there are still some +non- NULL values with associated destructors, then the process +is repeated.

+

pthread_key_delete deallocates a TSD key. It does not check +whether non- NULL values are associated with that key in the +currently executing threads, nor call the destructor function +associated with the key. +

+

pthread_setspecific changes the value associated with key +in the calling thread, storing the given pointer instead. +

+

pthread_getspecific returns the value currently associated +with key in the calling thread. +

+

The routines pthread_setspecific, pthread_getspecific, +and pthread_key_delete can be called from destr_function +targeting any valid key including the key on which destr_function +is currently operating. If pthread_getspecific is called on +the key whose thread specific data is being destroyed, the value NULL +is returned, unless pthread_setspecific was called previously +on that key from within destr_function to set the value to +non-NULL. For some implementations the effect of calling +pthread_setspecific from within destr_function can be +either memory leakage or infinite loops if destr_function has +already been called at least PTHREAD_DESTRUCTOR_ITERATIONS +times.

+

Pthreads-w32 stops running key +destr_function routines after PTHREAD_DESTRUCTOR_ITERATIONS +iterations, even if some non- NULL values with associated +descriptors remain. If memory is allocated and associated with a key +from within destr_function, that memory may not be reclaimed +because that key's destr_function, may not run again.

+

Return Value

+

pthread_key_create, pthread_key_delete, and +pthread_setspecific return 0 on success and a non-zero error +code on failure. If successful, pthread_key_create stores the +newly allocated key in the location pointed to by its key +argument. +

+

pthread_getspecific returns the value associated with key +on success, and NULL on error. +

+

Errors

+

pthread_key_create returns the following error code on +error: +

+
+
+
EAGAIN +
+
+
+PTHREAD_KEYS_MAX keys are already allocated +
+
+
+
ENOMEM +
+
+
+Insufficient memory to allocate the key. +
+

pthread_key_delete and pthread_setspecific return +the following error code on error: +

+
+
+
EINVAL +
+ key is not a valid, allocated TSD key +
+
+

+pthread_getspecific returns NULL if key is not a +valid, allocated TSD key. +

+

Author

+

Xavier Leroy <Xavier.Leroy@inria.fr> +

+

Modified by Ross Johnson for use with Pthreads-w32.

+

See Also

+

pthread_create(3) , +pthread_exit(3) , +pthread_testcancel(3) . +

+

Example

+

The following code fragment allocates a thread-specific array of +100 characters, with automatic reclamation at thread exit: +

+


+
+
/* Key for the thread-specific buffer */
+static pthread_key_t buffer_key;
+/* Once-only initialisation of the key */
+static pthread_once_t buffer_key_once = PTHREAD_ONCE_INIT;
+/* Allocate the thread-specific buffer */
+void buffer_alloc(void)
+{
+  pthread_once(&buffer_key_once, buffer_key_alloc);
+  pthread_setspecific(buffer_key, malloc(100));
+}
+/* Return the thread-specific buffer */
+char * get_buffer(void)
+{
+  return (char *) pthread_getspecific(buffer_key);
+}
+/* Allocate the key */
+static void buffer_key_alloc()
+{
+  pthread_key_create(&buffer_key, buffer_destroy);
+}
+/* Free the thread-specific buffer */
+static void buffer_destroy(void * buf)
+{
+  free(buf);
+}
+
+
+Table of Contents
+ + + \ No newline at end of file diff --git a/pthreads/manual/pthread_kill.html b/pthreads/manual/pthread_kill.html new file mode 100644 index 000000000..33d61b21c --- /dev/null +++ b/pthreads/manual/pthread_kill.html @@ -0,0 +1,152 @@ + + + + + PTHREAD_SIGNAL(3) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

pthread_sigmask, pthread_kill, sigwait - handling of signals in +threads +

+

Synopsis

+

#include <pthread.h>
#include <signal.h> +

+

int pthread_sigmask(int how, const sigset_t +*newmask, sigset_t *oldmask); +

+

int pthread_kill(pthread_t thread, int signo); +

+

int sigwait(const sigset_t *set, int *sig);

+

Description

+

pthread_sigmask changes the signal mask for the calling +thread as described by the how and newmask arguments. +If oldmask is not NULL, the previous signal mask is +stored in the location pointed to by oldmask. Pthreads-w32 +implements this function but no other function uses the signal mask +yet.

+

The meaning of the how and newmask arguments is the +same as for sigprocmask(2). +If how is SIG_SETMASK, the signal mask is set to +newmask. If how is SIG_BLOCK, the signals +specified to newmask are added to the current signal mask. If +how is SIG_UNBLOCK, the signals specified to newmask +are removed from the current signal mask. +

+

Recall that signal masks are set on a per-thread basis, but signal +actions and signal handlers, as set with sigaction(2), are +shared between all threads. +

+

pthread_kill send signal number signo to the thread +thread. Pthreads-w32 only supports signal number 0, +which does not send any signal but causes pthread_kill to +return an error if thread is not valid.

+

sigwait suspends the calling thread until one of the +signals in set is delivered to the calling thread. It then +stores the number of the signal received in the location pointed to +by sig and returns. The signals in set must be blocked +and not ignored on entrance to sigwait. If the delivered +signal has a signal handler function attached, that function is not +called. Pthreads-w32 implements this function as a +cancellation point only - it does not wait for any signals and does +not change the location pointed to by sig.

+

Cancellation

+

sigwait is a cancellation point. +

+

Return Value

+

On success, 0 is returned. On failure, a non-zero error code is +returned. +

+

Errors

+

The pthread_sigmask function returns the following error +codes on error: +

+
+
+
EINVAL +
+ how is not one of SIG_SETMASK, SIG_BLOCK, or + SIG_UNBLOCK +
+
+

+The pthread_kill function returns the following error codes on +error: +

+
+
+
EINVAL +
+ signo is not a valid signal number or is unsupported.
+ ESRCH +
+ the thread thread does not exist (e.g. it has already + terminated) +
+
+

+The sigwait function never returns an error. +

+

Author

+

Xavier Leroy <Xavier.Leroy@inria.fr> +

+

Modified by Ross Johnson for use with Pthreads-w32.

+

See Also

+

+

+

Notes

+

In any implementation, for sigwait to work reliably, the +signals being waited for must be blocked in all threads, not only in +the calling thread, since otherwise the POSIX semantics for signal +delivery do not guarantee that it’s the thread doing the sigwait +that will receive the signal. The best way to achieve this is to +block those signals before any threads are created, and never unblock +them in the program other than by calling sigwait. This works +because all threads inherit their initial sigmask from their creating +thread.

+

Bugs

+

Pthreads-w32 does not implement signals yet and so these +routines have almost no use except to prevent the compiler or linker +from complaining. pthread_kill is useful in determining if the +thread is a valid thread, but since many threads implementations +reuse thread IDs, the valid thread may no longer be the thread you +think it is, and so this method of determining thread validity is not +portable, and very risky. Pthreads-w32 from version 1.0.0 +onwards implements pseudo-unique thread IDs, so applications that use +this technique (but really shouldn't) have some protection.

+
+

Table of Contents

+ + + diff --git a/pthreads/manual/pthread_mutex_init.html b/pthreads/manual/pthread_mutex_init.html new file mode 100644 index 000000000..f9982cf61 --- /dev/null +++ b/pthreads/manual/pthread_mutex_init.html @@ -0,0 +1,277 @@ + + + + + PTHREAD_MUTEX(3) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

pthread_mutex_init, pthread_mutex_lock, pthread_mutex_trylock, +pthread_mutex_timedlock, pthread_mutex_unlock, pthread_mutex_destroy +- operations on mutexes +

+

Synopsis

+

#include <pthread.h> +

+

#include <time.h>

+

pthread_mutex_t fastmutex = +PTHREAD_MUTEX_INITIALIZER; +

+

pthread_mutex_t recmutex = +PTHREAD_RECURSIVE_MUTEX_INITIALIZER; +

+

pthread_mutex_t errchkmutex = +PTHREAD_ERRORCHECK_MUTEX_INITIALIZER; +

+

pthread_mutex_t recmutex = +PTHREAD_RECURSIVE_MUTEX_INITIALIZER_NP; +

+

pthread_mutex_t errchkmutex = +PTHREAD_ERRORCHECK_MUTEX_INITIALIZER_NP; +

+

int pthread_mutex_init(pthread_mutex_t *mutex, +const pthread_mutexattr_t *mutexattr); +

+

int pthread_mutex_lock(pthread_mutex_t *mutex); +

+

int pthread_mutex_trylock(pthread_mutex_t *mutex); +

+

int pthread_mutex_timedlock(pthread_mutex_t *mutex, +const struct timespec *abs_timeout); +

+

int pthread_mutex_unlock(pthread_mutex_t *mutex); +

+

int pthread_mutex_destroy(pthread_mutex_t *mutex); +

+

Description

+

A mutex is a MUTual EXclusion device, and is useful for protecting +shared data structures from concurrent modifications, and +implementing critical sections and monitors. +

+

A mutex has two possible states: unlocked (not owned by any +thread), and locked (owned by one thread). A mutex can never be owned +by two different threads simultaneously. A thread attempting to lock +a mutex that is already locked by another thread is suspended until +the owning thread unlocks the mutex first. +

+

pthread_mutex_init initializes the mutex object pointed to +by mutex according to the mutex attributes specified in +mutexattr. If mutexattr is NULL, default +attributes are used instead. +

+

The type of a mutex determines whether it can be locked again by a +thread that already owns it. The default type is “normal”. See +pthread_mutexattr_init(3) +for more information on mutex attributes. +

+

Variables of type pthread_mutex_t can also be initialized +statically, using the constants PTHREAD_MUTEX_INITIALIZER (for +normal “fast” mutexes), PTHREAD_RECURSIVE_MUTEX_INITIALIZER +(for recursive mutexes), and PTHREAD_ERRORCHECK_MUTEX_INITIALIZER +(for error checking mutexes). In +the Pthreads-w32 implementation, an application should still +call pthread_mutex_destroy at some point to ensure that any +resources consumed by the mutex are released.

+

pthread_mutex_lock locks the given mutex. If the mutex is +currently unlocked, it becomes locked and owned by the calling +thread, and pthread_mutex_lock returns immediately. If the +mutex is already locked by another thread, pthread_mutex_lock +suspends the calling thread until the mutex is unlocked. +

+

If the mutex is already locked by the calling thread, the behavior +of pthread_mutex_lock depends on the type of the mutex. If the +mutex is of the “normal” type, the calling thread is suspended +until the mutex is unlocked, thus effectively causing the calling +thread to deadlock. If the mutex is of the ‘‘error checking’’ +type, pthread_mutex_lock returns immediately with the error +code EDEADLK. If the mutex is of the ‘‘recursive’’ +type, pthread_mutex_lock succeeds and returns immediately, +recording the number of times the calling thread has locked the +mutex. An equal number of pthread_mutex_unlock operations must +be performed before the mutex returns to the unlocked state. +

+

pthread_mutex_trylock behaves identically to +pthread_mutex_lock, except that it does not block the calling +thread if the mutex is already locked by another thread (or by the +calling thread in the case of a “normal” mutex). Instead, +pthread_mutex_trylock returns immediately with the error code +EBUSY. +

+

pthread_mutex_timedlock behaves identically to +pthread_mutex_lock, except that if it cannot acquire the lock +before the abs_timeout time, the call returns with the error +code ETIMEDOUT. If the mutex can be locked immediately it is, +and the abs_timeout parameter is ignored.

+

pthread_mutex_unlock unlocks the given mutex. The mutex is +assumed to be locked and owned by the calling thread on entrance to +pthread_mutex_unlock. If the mutex is of the “normal” +type, pthread_mutex_unlock always returns it to the unlocked +state. If it is of the ‘‘recursive’’ type, it decrements the +locking count of the mutex (number of pthread_mutex_lock +operations performed on it by the calling thread), and only when this +count reaches zero is the mutex actually unlocked. +

+

On ‘‘error checking’’ mutexes, pthread_mutex_unlock +actually checks at run-time that the mutex is locked on entrance, and +that it was locked by the same thread that is now calling +pthread_mutex_unlock. If these conditions are not met, an +error code is returned and the mutex remains unchanged. ‘‘Normal’’ +mutexes perform no such checks, thus allowing a locked mutex to be +unlocked by a thread other than its owner. This is non-portable +behavior and is not meant to be used as a feature.

+

pthread_mutex_destroy destroys a mutex object, freeing the +resources it might hold. The mutex must be unlocked on entrance.

+

Cancellation

+

None of the mutex functions is a cancellation point, not even +pthread_mutex_lock, in spite of the fact that it can suspend a +thread for arbitrary durations. This way, the status of mutexes at +cancellation points is predictable, allowing cancellation handlers to +unlock precisely those mutexes that need to be unlocked before the +thread stops executing. Consequently, threads using deferred +cancellation should never hold a mutex for extended periods of time. +

+

Async-signal Safety

+

The mutex functions are not async-signal safe. What this means is +that they should not be called from a signal handler. In particular, +calling pthread_mutex_lock or pthread_mutex_unlock from +a signal handler may deadlock the calling thread. +

+

Return Value

+

pthread_mutex_init always returns 0. The other mutex +functions return 0 on success and a non-zero error code on error. +

+

Errors

+

The pthread_mutex_lock function returns the following error +code on error: +

+
+
+
EINVAL +
+ the mutex has not been properly initialized. +
+ EDEADLK +
+ the mutex is already locked by the calling thread (‘‘error + checking’’ mutexes only). +
+
+

+The pthread_mutex_trylock function returns the following error +codes on error: +

+
+
+
EBUSY +
+ the mutex could not be acquired because it was currently locked. +
+ EINVAL +
+ the mutex has not been properly initialized. +
+
+

+The pthread_mutex_timedlock function returns the following +error codes on error: +

+
+
+
ETIMEDOUT +
+ the mutex could not be acquired before the abs_timeout time + arrived. +
+ EINVAL +
+ the mutex has not been properly initialized. +
+
+

+The pthread_mutex_unlock function returns the following error +code on error: +

+
+
+
EINVAL +
+ the mutex has not been properly initialized. +
+ EPERM +
+ the calling thread does not own the mutex (‘‘error checking’’ + mutexes only). +
+
+

+The pthread_mutex_destroy function returns the following error +code on error: +

+
+
+
EBUSY +
+ the mutex is currently locked. +
+
+

+Author

+

Xavier Leroy <Xavier.Leroy@inria.fr> +

+

Modified by Ross Johnson for use with Pthreads-w32.

+

See Also

+

pthread_mutexattr_init(3) +, pthread_mutexattr_settype(3) +, pthread_cancel(3) . +

+

Example

+

A shared global variable x can be protected by a mutex as +follows: +

+
int x;
+pthread_mutex_t mut = PTHREAD_MUTEX_INITIALIZER;
+All accesses and modifications to x should be bracketed by +calls to pthread_mutex_lock and pthread_mutex_unlock as +follows: +
+
pthread_mutex_lock(&mut);
+/* operate on x */
+pthread_mutex_unlock(&mut);
+
+
Table of +Contents
+ + + diff --git a/pthreads/manual/pthread_mutexattr_init.html b/pthreads/manual/pthread_mutexattr_init.html new file mode 100644 index 000000000..f3df9936d --- /dev/null +++ b/pthreads/manual/pthread_mutexattr_init.html @@ -0,0 +1,157 @@ + + + + + PTHREAD_MUTEXATTR(3) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

pthread_mutexattr_init, pthread_mutexattr_destroy, +pthread_mutexattr_settype, pthread_mutexattr_gettype - mutex creation +attributes +

+

Synopsis

+

#include <pthread.h> +

+

int pthread_mutexattr_init(pthread_mutexattr_t *attr); +

+

int pthread_mutexattr_destroy(pthread_mutexattr_t *attr); +

+

int pthread_mutexattr_settype(pthread_mutexattr_t *attr, +int type); +

+

int pthread_mutexattr_gettype(const pthread_mutexattr_t *attr, +int *type); +

+

int pthread_mutexattr_setkind_np(pthread_mutexattr_t *attr, +int type); +

+

int pthread_mutexattr_getkind_np(const pthread_mutexattr_t +*attr, int *type); +

+

Description

+

Mutex attributes can be specified at mutex creation time, by +passing a mutex attribute object as second argument to +pthread_mutex_init(3) . +Passing NULL is equivalent to passing a mutex attribute object +with all attributes set to their default values. +

+

pthread_mutexattr_init initializes the mutex attribute +object attr and fills it with default values for the +attributes. +

+

pthread_mutexattr_destroy destroys a mutex attribute +object, which must not be reused until it is reinitialized.

+

The following mutex types are supported:

+

PTHREAD_MUTEX_NORMAL - for +‘‘fast’’ mutexes.

+

PTHREAD_MUTEX_RECURSIVE - for +‘‘recursive’’ mutexes.

+

PTHREAD_MUTEX_ERRORCHECK - for +‘‘error checking’’ mutexes.

+

The mutex type determines what happens if a thread attempts to +lock a mutex it already owns with pthread_mutex_lock(3) +. If the mutex is of the “normal” or “fast” type, +pthread_mutex_lock(3) +simply suspends the calling thread forever. If the mutex is of the +‘‘error checking’’ type, pthread_mutex_lock(3) +returns immediately with the error code EDEADLK. If the mutex +is of the ‘‘recursive’’ type, the call to +pthread_mutex_lock(3) +returns immediately with a success return code. The number of times +the thread owning the mutex has locked it is recorded in the mutex. +The owning thread must call pthread_mutex_unlock(3) +the same number of times before the mutex returns to the unlocked +state. +

+

The default mutex type is PTHREAD_MUTEX_NORMAL

+

Pthreads-w32 also recognises the following equivalent types +that are used by Linux:

+

PTHREAD_MUTEX_FAST_NP +– equivalent to PTHREAD_MUTEX_NORMAL

+

PTHREAD_MUTEX_RECURSIVE_NP

+

PTHREAD_MUTEX_ERRORCHECK_NP

+

pthread_mutexattr_settype sets the mutex type attribute in +attr to the value specified by type. +

+

pthread_mutexattr_gettype retrieves the current value of +the mutex kind attribute in attr and stores it in the location +pointed to by type. +

+

Pthreads-w32 also recognises the following equivalent +functions that are used in Linux:

+

pthread_mutexattr_setkind_np is an alias for +pthread_mutexattr_settype. +

+

pthread_mutexattr_getkind_np is +an alias for pthread_mutexattr_gettype. +

+

Return Value

+

pthread_mutexattr_init, pthread_mutexattr_destroy +and pthread_mutexattr_gettype always return 0. +

+

pthread_mutexattr_settype returns 0 on success and a +non-zero error code on error. +

+

Errors

+

On error, pthread_mutexattr_settype returns the following +error code: +

+
+
EINVAL +
+ type is none of:
PTHREAD_MUTEX_NORMAL, + PTHREAD_MUTEX_FAST_NP,
PTHREAD_MUTEX_RECURSIVE, + PTHREAD_MUTEX_RECURSIVE_NP,
PTHREAD_MUTEX_ERRORCHECK, + PTHREAD_MUTEX_ERRORCHECK_NP +
+

+Author

+

Xavier Leroy <Xavier.Leroy@inria.fr> +

+

Modified by Ross Johnson for use with Pthreads-w32.

+

See Also

+

pthread_mutex_init(3) +, pthread_mutex_lock(3) +, pthread_mutex_unlock(3) +. +

+

Notes

+

For speed, Pthreads-w32 never checks the thread ownership +of mutexes of type PTHREAD_MUTEX_NORMAL (or +PTHREAD_MUTEX_FAST_NP) when performing operations on the +mutex. It is therefore possible for one thread to lock such a mutex +and another to unlock it.

+

When developing code, it is a +common precaution to substitute the error checking type, and drop in +the normal type for release if the extra performance is required.

+
+

Table of Contents

+ + + diff --git a/pthreads/manual/pthread_mutexattr_setpshared.html b/pthreads/manual/pthread_mutexattr_setpshared.html new file mode 100644 index 000000000..25bf9f60b --- /dev/null +++ b/pthreads/manual/pthread_mutexattr_setpshared.html @@ -0,0 +1,151 @@ + + + + + "PTHREAD_MUTEXATTR_GETPSHARED"(P) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

pthread_mutexattr_getpshared, pthread_mutexattr_setpshared - get +and set the process-shared attribute +

+

Synopsis

+

#include <pthread.h> +

+

int pthread_mutexattr_getpshared(const pthread_mutexattr_t * +restrict attr, int *restrict pshared); +
int pthread_mutexattr_setpshared(pthread_mutexattr_t *attr, +int pshared); +

+

Description

+

The pthread_mutexattr_getpshared function shall obtain the +value of the process-shared attribute from the attributes +object referenced by attr. The pthread_mutexattr_setpshared +function shall set the process-shared attribute in an +initialized attributes object referenced by attr. +

+

The process-shared attribute is set to +PTHREAD_PROCESS_SHARED to permit a mutex to be operated upon +by any thread that has access to the memory where the mutex is +allocated, even if the mutex is allocated in memory that is shared by +multiple processes. If the process-shared attribute is +PTHREAD_PROCESS_PRIVATE, the mutex shall only be operated upon +by threads created within the same process as the thread that +initialized the mutex; if threads of differing processes attempt to +operate on such a mutex, the behavior is undefined. The default value +of the attribute shall be PTHREAD_PROCESS_PRIVATE. +

+

Pthreads-w32 defines _POSIX_THREAD_PROCESS_SHARED in +pthread.h as -1 to indicate that these routines are implemented but +the process shared option is not supported.

+

Return Value

+

Upon successful completion, pthread_mutexattr_setpshared +shall return zero; otherwise, an error number shall be returned to +indicate the error. +

+

Upon successful completion, pthread_mutexattr_getpshared +shall return zero and store the value of the process-shared +attribute of attr into the object referenced by the pshared +parameter. Otherwise, an error number shall be returned to indicate +the error. +

+

Errors

+

The pthread_mutexattr_getpshared and +pthread_mutexattr_setpshared functions may fail if: +

+
+
EINVAL +
+ The value specified by attr is invalid. +
+

+The pthread_mutexattr_setpshared function may fail if: +

+
+
EINVAL +
+ The new value specified for the attribute is outside the range of + legal values for that attribute. +
+ ENOTSUP +
+ The new value specified for the attribute is PTHREAD_PROCESS_SHARED. +
+

+These functions shall not return an error code of [EINTR]. +

+

The following sections are informative. +

+

Examples

+

None. +

+

Application Usage

+

None. +

+

Rationale

+

None. +

+

Future Directions

+

None. +

+

See Also

+

pthread_cond_destroy(3) +, pthread_create(3) , +pthread_mutex_destroy(3) +, pthread_mutexattr_destroy(3) +, the Base Definitions volume of IEEE Std 1003.1-2001, +<pthread.h> +

+

Copyright

+

Portions of this text are reprinted and reproduced in electronic +form from IEEE Std 1003.1, 2003 Edition, Standard for Information +Technology -- Portable Operating System Interface (POSIX), The Open +Group Base Specifications Issue 6, Copyright (C) 2001-2003 by the +Institute of Electrical and Electronics Engineers, Inc and The Open +Group. In the event of any discrepancy between this version and the +original IEEE and The Open Group Standard, the original IEEE and The +Open Group Standard is the referee document. The original Standard +can be obtained online at http://www.opengroup.org/unix/online.html +. +

+

Modified by Ross Johnson for use with Pthreads-w32.

+
+

Table of Contents

+ + + diff --git a/pthreads/manual/pthread_num_processors_np.html b/pthreads/manual/pthread_num_processors_np.html new file mode 100644 index 000000000..050941065 --- /dev/null +++ b/pthreads/manual/pthread_num_processors_np.html @@ -0,0 +1,57 @@ + + + + + PTHREAD_NUM_PROCESSORS_NP manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

pthread_num_processors_np – get the +number of processors (CPUs) in use by the process

+

Synopsis

+

#include <pthread.h> +

+

int pthread_num_processors_np(void);

+

Description

+

pthread_num_processors_np returns the number of processors +in the system. This implementation actually returns the number of +processors available to the process, which can be a lower number than +the system's number, depending on the process's affinity mask.

+

Cancellation

+

None.

+

Return Value

+

pthread_num_processors_np returns the number of processors +currently available to the process.

+

Errors

+

None.

+

Author

+

Ross Johnson for use with Pthreads-w32.

+
+

Table of Contents

+ + + diff --git a/pthreads/manual/pthread_once.html b/pthreads/manual/pthread_once.html new file mode 100644 index 000000000..856fb8653 --- /dev/null +++ b/pthreads/manual/pthread_once.html @@ -0,0 +1,83 @@ + + + + + PTHREAD_ONCE(3) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

pthread_once - once-only initialization +

+

Synopsis

+

#include <pthread.h> +

+

pthread_once_t once_control = PTHREAD_ONCE_INIT; +

+

int pthread_once(pthread_once_t *once_control, +void (*init_routine) (void)); +

+

Description

+

The purpose of pthread_once is to ensure that a piece of +initialization code is executed at most once. The once_control +argument points to a static or extern variable statically initialized +to PTHREAD_ONCE_INIT. +

+

The first time pthread_once is called with a given +once_control argument, it calls init_routine with no +argument and changes the value of the once_control variable to +record that initialization has been performed. Subsequent calls to +pthread_once with the same once_control argument do +nothing. +

+

Cancellation

+

While pthread_once is not a cancellation point, +init_routine can be. The effect on once_control of a +cancellation inside the init_routine is to leave it as if +pthread_once had not been called by the cancelled thread.

+

Return Value

+

pthread_once +returns 0 on success, or an error code on failure.

+

Errors

+

The pthread_once function returns the following error code +on error: +

+
+
+
EINVAL +
+
+

+The once_control or init_routine parameter is NULL.

+

Author

+

Xavier Leroy <Xavier.Leroy@inria.fr> +

+

Modified by Ross Johnson for use with Pthreads-w32.

+
+

Table of Contents

+ + + \ No newline at end of file diff --git a/pthreads/manual/pthread_rwlock_init.html b/pthreads/manual/pthread_rwlock_init.html new file mode 100644 index 000000000..530df93d4 --- /dev/null +++ b/pthreads/manual/pthread_rwlock_init.html @@ -0,0 +1,193 @@ + + + + + "PTHREAD_RWLOCK_DESTROY"(P) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

pthread_rwlock_destroy, pthread_rwlock_init - destroy and +initialize a read-write lock object +

+

Synopsis

+

#include <pthread.h> +

+

pthread_wrlock_t rwlock = +PTHREAD_RWLOCK_INITIALIZER;

+

int pthread_rwlock_destroy(pthread_rwlock_t *rwlock); +
int pthread_rwlock_init(pthread_rwlock_t *restrict rwlock, +const pthread_rwlockattr_t *restrict attr); +

+

Description

+

The pthread_rwlock_destroy function shall destroy the +read-write lock object referenced by rwlock and release any +resources used by the lock. The effect of subsequent use of the lock +is undefined until the lock is reinitialized by another call to +pthread_rwlock_init. An implementation may cause +pthread_rwlock_destroy to set the object referenced by rwlock +to an invalid value. Results are undefined if pthread_rwlock_destroy +is called when any thread holds rwlock. Attempting to destroy +an uninitialized read-write lock results in undefined behavior. +

+

The pthread_rwlock_init function shall allocate any +resources required to use the read-write lock referenced by rwlock +and initializes the lock to an unlocked state with attributes +referenced by attr. If attr is NULL, the default +read-write lock attributes shall be used; the effect is the same as +passing the address of a default read-write lock attributes object. +Once initialized, the lock can be used any number of times without +being reinitialized. Results are undefined if pthread_rwlock_init +is called specifying an already initialized read-write lock. Results +are undefined if a read-write lock is used without first being +initialized. +

+

If the pthread_rwlock_init function fails, rwlock +shall not be initialized and the contents of rwlock are +undefined. +

+

Pthreads-w32 supports statically initialized rwlock +objects using PTHREAD_RWLOCK_INITIALIZER. +An application should still call pthread_rwlock_destroy at +some point to ensure that any resources consumed by the read/write +lock are released.

+

Only the object referenced by rwlock may be used for +performing synchronization. The result of referring to copies of that +object in calls to pthread_rwlock_destroy , +pthread_rwlock_rdlock , pthread_rwlock_timedrdlock , +pthread_rwlock_timedwrlock , pthread_rwlock_tryrdlock , +pthread_rwlock_trywrlock , pthread_rwlock_unlock , or +pthread_rwlock_wrlock is undefined. +

+

Pthreads-w32 defines _POSIX_READER_WRITER_LOCKS in +pthread.h as 200112L to indicate that the reader/writer routines are +implemented and may be used.

+

Return Value

+

If successful, the pthread_rwlock_destroy and +pthread_rwlock_init functions shall return zero; otherwise, an +error number shall be returned to indicate the error. +

+

The [EBUSY] and [EINVAL] error checks, if implemented, act as if +they were performed immediately at the beginning of processing for +the function and caused an error return prior to modifying the state +of the read-write lock specified by rwlock. +

+

Errors

+

The pthread_rwlock_destroy function may fail if: +

+
+
EBUSY +
+ The implementation has detected an attempt to destroy the object + referenced by rwlock while it is locked. +
+ EINVAL +
+ The value specified by rwlock is invalid. +
+

+The pthread_rwlock_init function shall fail if: +

+
+
EAGAIN +
+ The system lacked the necessary resources (other than memory) to + initialize another read-write lock. +
+ ENOMEM +
+ Insufficient memory exists to initialize the read-write lock. +
+

+
+

+The pthread_rwlock_init function may fail if: +

+
+
EINVAL +
+ The value specified by attr is invalid. +
+

+These functions shall not return an error code of [EINTR]. +

+

The following sections are informative. +

+

Examples

+

None. +

+

Application Usage

+

Applications using these and related read-write lock functions may +be subject to priority inversion, as discussed in the Base +Definitions volume of IEEE Std 1003.1-2001, Section 3.285, +Priority Inversion. +

+

Rationale

+

None. +

+

Future Directions

+

None. +

+

See Also

+

pthread_rwlock_rdlock(3) +, pthread_rwlock_timedrdlock(3) +, pthread_rwlock_timedwrlock(3) +, pthread_rwlock_tryrdlock(3) +, pthread_rwlock_trywrlock(3) +, pthread_rwlock_unlock(3) +, pthread_rwlock_wrlock(3) +, the Base Definitions volume of IEEE Std 1003.1-2001, +<pthread.h> +

+

Copyright

+

Portions of this text are reprinted and reproduced in electronic +form from IEEE Std 1003.1, 2003 Edition, Standard for Information +Technology -- Portable Operating System Interface (POSIX), The Open +Group Base Specifications Issue 6, Copyright (C) 2001-2003 by the +Institute of Electrical and Electronics Engineers, Inc and The Open +Group. In the event of any discrepancy between this version and the +original IEEE and The Open Group Standard, the original IEEE and The +Open Group Standard is the referee document. The original Standard +can be obtained online at http://www.opengroup.org/unix/online.html +. +

+

Modified by Ross Johnson for use with Pthreads-w32.

+
+

Table of Contents

+ + + diff --git a/pthreads/manual/pthread_rwlock_rdlock.html b/pthreads/manual/pthread_rwlock_rdlock.html new file mode 100644 index 000000000..3b63f255c --- /dev/null +++ b/pthreads/manual/pthread_rwlock_rdlock.html @@ -0,0 +1,168 @@ + + + + + "PTHREAD_RWLOCK_RDLOCK"(P) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

pthread_rwlock_rdlock, pthread_rwlock_tryrdlock - lock a +read-write lock object for reading +

+

Synopsis

+

#include <pthread.h> +

+

int pthread_rwlock_rdlock(pthread_rwlock_t *rwlock); +
int pthread_rwlock_tryrdlock(pthread_rwlock_t *rwlock); + +

+

Description

+

The pthread_rwlock_rdlock function shall apply a read lock +to the read-write lock referenced by rwlock. The calling +thread acquires the read lock if a writer does not hold the lock and +there are no writers blocked on the lock. +

+

Pthreads-win32 does not prefer either writers or readers in +acquiring the lock – all threads enter a single prioritised FIFO +queue. While this may not be optimally efficient for some +applications, it does ensure that one type does not starve the other.

+

A thread may hold multiple concurrent read locks on rwlock +(that is, successfully call the pthread_rwlock_rdlock function +n times). If so, the application shall ensure that the thread +performs matching unlocks (that is, it calls the +pthread_rwlock_unlock(3) +function n times). +

+

The pthread_rwlock_tryrdlock function shall apply a read +lock as in the pthread_rwlock_rdlock function, with the +exception that the function shall fail if the equivalent +pthread_rwlock_rdlock call would have blocked the calling +thread. In no case shall the pthread_rwlock_tryrdlock function +ever block; it always either acquires the lock or fails and returns +immediately. +

+

Results are undefined if any of these functions are called with an +uninitialized read-write lock. +

+

Pthreads-w32 does not detect deadlock if the thread already +owns the lock for writing.

+

Pthreads-w32 defines _POSIX_READER_WRITER_LOCKS in +pthread.h as 200112L to indicate that the reader/writer routines are +implemented and may be used.

+

Return Value

+

If successful, the pthread_rwlock_rdlock function shall +return zero; otherwise, an error number shall be returned to indicate +the error. +

+

The pthread_rwlock_tryrdlock function shall return zero if +the lock for reading on the read-write lock object referenced by +rwlock is acquired. Otherwise, an error number shall be +returned to indicate the error. +

+

Errors

+

The pthread_rwlock_tryrdlock function shall fail if: +

+
+
EBUSY +
+ The read-write lock could not be acquired for reading because a + writer holds the lock or a writer with the appropriate priority was + blocked on it. +
+

+The pthread_rwlock_rdlock and pthread_rwlock_tryrdlock +functions may fail if: +

+
+
EINVAL +
+ The value specified by rwlock does not refer to an + initialized read-write lock object. +
+ EAGAIN +
+ The read lock could not be acquired because the maximum number of + read locks for rwlock has been exceeded. +
+

+These functions shall not return an error code of [EINTR]. +

+

The following sections are informative. +

+

Examples

+

None. +

+

Application Usage

+

Applications using these functions may be subject to priority +inversion, as discussed in the Base Definitions volume of +IEEE Std 1003.1-2001, Section 3.285, Priority Inversion. +

+

Rationale

+

None. +

+

Future Directions

+

None. +

+

See Also

+

pthread_rwlock_destroy(3) +, pthread_rwlock_timedrdlock(3) +, pthread_rwlock_timedwrlock(3) +, pthread_rwlock_trywrlock(3) +, pthread_rwlock_unlock(3) +, pthread_rwlock_wrlock(3) +, the Base Definitions volume of IEEE Std 1003.1-2001, +<pthread.h> +

+

Copyright

+

Portions of this text are reprinted and reproduced in electronic +form from IEEE Std 1003.1, 2003 Edition, Standard for Information +Technology -- Portable Operating System Interface (POSIX), The Open +Group Base Specifications Issue 6, Copyright (C) 2001-2003 by the +Institute of Electrical and Electronics Engineers, Inc and The Open +Group. In the event of any discrepancy between this version and the +original IEEE and The Open Group Standard, the original IEEE and The +Open Group Standard is the referee document. The original Standard +can be obtained online at http://www.opengroup.org/unix/online.html +. +

+

Modified by Ross Johnson for use with Pthreads-w32.

+
+

Table of Contents

+ + + diff --git a/pthreads/manual/pthread_rwlock_timedrdlock.html b/pthreads/manual/pthread_rwlock_timedrdlock.html new file mode 100644 index 000000000..1b9ca630f --- /dev/null +++ b/pthreads/manual/pthread_rwlock_timedrdlock.html @@ -0,0 +1,156 @@ + + + + + "PTHREAD_RWLOCK_TIMEDRDLOCK"(P) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

pthread_rwlock_timedrdlock - lock a read-write lock for reading +

+

Synopsis

+

#include <pthread.h>
#include <time.h> +

+

int pthread_rwlock_timedrdlock(pthread_rwlock_t *restrict +rwlock, const struct timespec *restrict abs_timeout); + +

+

Description

+

The pthread_rwlock_timedrdlock function shall apply a read +lock to the read-write lock referenced by rwlock as in the +pthread_rwlock_rdlock(3) +function. However, if the lock cannot be acquired without waiting for +other threads to unlock the lock, this wait shall be terminated when +the specified timeout expires. The timeout shall expire when the +absolute time specified by abs_timeout passes, as measured by +the clock on which timeouts are based (that is, when the value of +that clock equals or exceeds abs_timeout), or if the absolute +time specified by abs_timeout has already been passed at the +time of the call. +

+

The timespec data type is defined in the <time.h> +header. Under no circumstances shall the function fail with a timeout +if the lock can be acquired immediately. The validity of the +abs_timeout parameter need not be checked if the lock can be +immediately acquired. +

+

The calling thread may deadlock if at the time the call is made it +holds a write lock on rwlock. The results are undefined if +this function is called with an uninitialized read-write lock. +

+

Pthreads-w32 defines _POSIX_READER_WRITER_LOCKS in +pthread.h as 200112L to indicate that the reader/writer routines are +implemented and may be used.

+

Return Value

+

The pthread_rwlock_timedrdlock function shall return zero +if the lock for reading on the read-write lock object referenced by +rwlock is acquired. Otherwise, an error number shall be +returned to indicate the error. +

+

Errors

+

The pthread_rwlock_timedrdlock function shall fail if: +

+
+
ETIMEDOUT +
+ The lock could not be acquired before the specified timeout expired. +
+

+The pthread_rwlock_timedrdlock function may fail if: +

+
+
EAGAIN +
+ The read lock could not be acquired because the maximum number of + read locks for lock would be exceeded. +
+ EINVAL +
+ The value specified by rwlock does not refer to an + initialized read-write lock object, or the abs_timeout + nanosecond value is less than zero or greater than or equal to 1000 + million. +
+

+This function shall not return an error code of [EINTR]. +

+

The following sections are informative. +

+

Examples

+

None. +

+

Application Usage

+

Applications using this function may be subject to priority +inversion, as discussed in the Base Definitions volume of +IEEE Std 1003.1-2001, Section 3.285, Priority Inversion. +

+

Rationale

+

None. +

+

Future Directions

+

None. +

+

See Also

+

pthread_rwlock_destroy(3) +, pthread_rwlock_rdlock(3) +, pthread_rwlock_timedwrlock(3) +, pthread_rwlock_tryrdlock(3) +, pthread_rwlock_trywrlock(3) +, pthread_rwlock_unlock(3) +, pthread_rwlock_wrlock(3) +, the Base Definitions volume of IEEE Std 1003.1-2001, +<pthread.h>, <time.h> +

+

Copyright

+

Portions of this text are reprinted and reproduced in electronic +form from IEEE Std 1003.1, 2003 Edition, Standard for Information +Technology -- Portable Operating System Interface (POSIX), The Open +Group Base Specifications Issue 6, Copyright (C) 2001-2003 by the +Institute of Electrical and Electronics Engineers, Inc and The Open +Group. In the event of any discrepancy between this version and the +original IEEE and The Open Group Standard, the original IEEE and The +Open Group Standard is the referee document. The original Standard +can be obtained online at http://www.opengroup.org/unix/online.html +. +

+

Modified by Ross Johnson for use with Pthreads-w32.

+
+

Table of Contents

+ + + diff --git a/pthreads/manual/pthread_rwlock_timedwrlock.html b/pthreads/manual/pthread_rwlock_timedwrlock.html new file mode 100644 index 000000000..0213bab40 --- /dev/null +++ b/pthreads/manual/pthread_rwlock_timedwrlock.html @@ -0,0 +1,150 @@ + + + + + "PTHREAD_RWLOCK_TIMEDWRLOCK"(P) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

pthread_rwlock_timedwrlock - lock a read-write lock for writing +

+

Synopsis

+

#include <pthread.h>
#include <time.h> +

+

int pthread_rwlock_timedwrlock(pthread_rwlock_t *restrict +rwlock, const struct timespec *restrict abs_timeout); + +

+

Description

+

The pthread_rwlock_timedwrlock function shall apply a write +lock to the read-write lock referenced by rwlock as in the +pthread_rwlock_wrlock(3) +function. However, if the lock cannot be acquired without waiting for +other threads to unlock the lock, this wait shall be terminated when +the specified timeout expires. The timeout shall expire when the +absolute time specified by abs_timeout passes, as measured by +the clock on which timeouts are based (that is, when the value of +that clock equals or exceeds abs_timeout), or if the absolute +time specified by abs_timeout has already been passed at the +time of the call. +

+

The timespec data type is defined in the <time.h> +header. Under no circumstances shall the function fail with a timeout +if the lock can be acquired immediately. The validity of the +abs_timeout parameter need not be checked if the lock can be +immediately acquired. +

+

The calling thread may deadlock if at the time the call is made it +holds the read-write lock. The results are undefined if this function +is called with an uninitialized read-write lock. +

+

Pthreads-w32 defines _POSIX_READER_WRITER_LOCKS in +pthread.h as 200112L to indicate that the reader/writer routines are +implemented and may be used.

+

Return Value

+

The pthread_rwlock_timedwrlock function shall return zero +if the lock for writing on the read-write lock object referenced by +rwlock is acquired. Otherwise, an error number shall be +returned to indicate the error. +

+

Errors

+

The pthread_rwlock_timedwrlock function shall fail if: +

+
+
ETIMEDOUT +
+ The lock could not be acquired before the specified timeout expired. +
+

+The pthread_rwlock_timedwrlock function may fail if: +

+
+
EINVAL +
+ The value specified by rwlock does not refer to an initialized + read-write lock object, or the abs_timeout nanosecond value + is less than zero or greater than or equal to 1000 million. +
+

+This function shall not return an error code of [EINTR]. +

+

The following sections are informative. +

+

Examples

+

None. +

+

Application Usage

+

Applications using this function may be subject to priority +inversion, as discussed in the Base Definitions volume of +IEEE Std 1003.1-2001, Section 3.285, Priority Inversion. +

+

Rationale

+

None. +

+

Future Directions

+

None. +

+

See Also

+

pthread_rwlock_destroy(3) +, pthread_rwlock_rdlock(3) +, pthread_rwlock_timedrdlock(3) +, pthread_rwlock_tryrdlock(3) +, pthread_rwlock_trywrlock(3) +, pthread_rwlock_unlock(3) +, pthread_rwlock_wrlock(3) +, the Base Definitions volume of IEEE Std 1003.1-2001, +<pthread.h>, <time.h> +

+

Copyright

+

Portions of this text are reprinted and reproduced in electronic +form from IEEE Std 1003.1, 2003 Edition, Standard for Information +Technology -- Portable Operating System Interface (POSIX), The Open +Group Base Specifications Issue 6, Copyright (C) 2001-2003 by the +Institute of Electrical and Electronics Engineers, Inc and The Open +Group. In the event of any discrepancy between this version and the +original IEEE and The Open Group Standard, the original IEEE and The +Open Group Standard is the referee document. The original Standard +can be obtained online at http://www.opengroup.org/unix/online.html +. +

+

Modified by Ross Johnson for use with Pthreads-w32.

+
+

Table of Contents

+ + + diff --git a/pthreads/manual/pthread_rwlock_unlock.html b/pthreads/manual/pthread_rwlock_unlock.html new file mode 100644 index 000000000..09725cc3e --- /dev/null +++ b/pthreads/manual/pthread_rwlock_unlock.html @@ -0,0 +1,141 @@ + + + + + "PTHREAD_RWLOCK_UNLOCK"(P) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

pthread_rwlock_unlock - unlock a read-write lock object +

+

Synopsis

+

#include <pthread.h> +

+

int pthread_rwlock_unlock(pthread_rwlock_t *rwlock); + +

+

Description

+

The pthread_rwlock_unlock function shall release a lock +held on the read-write lock object referenced by rwlock. +Results are undefined if the read-write lock rwlock is not +held by the calling thread. +

+

If this function is called to release a read lock from the +read-write lock object and there are other read locks currently held +on this read-write lock object, the read-write lock object remains in +the read locked state. If this function releases the last read lock +for this read-write lock object, the read-write lock object shall be +put in the unlocked state with no owners. +

+

If this function is called to release a write lock for this +read-write lock object, the read-write lock object shall be put in +the unlocked state. +

+

Pthreads-win32 does not prefer either writers or readers in +acquiring the lock – all threads enter a single prioritised FIFO +queue. While this may not be optimally efficient for some +applications, it does ensure that one type does not starve the other.

+

Results are undefined if any of these functions are called with an +uninitialized read-write lock. +

+

Pthreads-w32 defines _POSIX_READER_WRITER_LOCKS in +pthread.h as 200112L to indicate that the reader/writer routines are +implemented and may be used.

+

Return Value

+

If successful, the pthread_rwlock_unlock function shall +return zero; otherwise, an error number shall be returned to indicate +the error. +

+

Errors

+

The pthread_rwlock_unlock function may fail if: +

+
+
EINVAL +
+ The value specified by rwlock does not refer to an + initialized read-write lock object. +
+

+
+

+The pthread_rwlock_unlock function shall not return an error +code of [EINTR]. +

+

The following sections are informative. +

+

Examples

+

None. +

+

Application Usage

+

None. +

+

Rationale

+

None. +

+

Future Directions

+

None. +

+

See Also

+

pthread_rwlock_destroy(3) +, pthread_rwlock_rdlock(3) +, pthread_rwlock_timedrdlock(3) +, pthread_rwlock_timedwrlock(3) +, pthread_rwlock_tryrdlock(3) +, pthread_rwlock_trywrlock(3) +, pthread_rwlock_wrlock(3) +, the Base Definitions volume of IEEE Std 1003.1-2001, +<pthread.h> +

+

Copyright

+

Portions of this text are reprinted and reproduced in electronic +form from IEEE Std 1003.1, 2003 Edition, Standard for Information +Technology -- Portable Operating System Interface (POSIX), The Open +Group Base Specifications Issue 6, Copyright (C) 2001-2003 by the +Institute of Electrical and Electronics Engineers, Inc and The Open +Group. In the event of any discrepancy between this version and the +original IEEE and The Open Group Standard, the original IEEE and The +Open Group Standard is the referee document. The original Standard +can be obtained online at http://www.opengroup.org/unix/online.html +. +

+

Modified by Ross Johnson for use with Pthreads-w32.

+
+

Table of Contents

+ + + diff --git a/pthreads/manual/pthread_rwlock_wrlock.html b/pthreads/manual/pthread_rwlock_wrlock.html new file mode 100644 index 000000000..02b3a19ea --- /dev/null +++ b/pthreads/manual/pthread_rwlock_wrlock.html @@ -0,0 +1,153 @@ + + + + + "PTHREAD_RWLOCK_TRYWRLOCK"(P) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

pthread_rwlock_trywrlock, pthread_rwlock_wrlock - lock a +read-write lock object for writing +

+

Synopsis

+

#include <pthread.h> +

+

int pthread_rwlock_trywrlock(pthread_rwlock_t *rwlock); +
int pthread_rwlock_wrlock(pthread_rwlock_t *rwlock); + +

+

Description

+

The pthread_rwlock_trywrlock function shall apply a write +lock like the pthread_rwlock_wrlock function, with the +exception that the function shall fail if any thread currently holds +rwlock (for reading or writing). +

+

The pthread_rwlock_wrlock function shall apply a write lock +to the read-write lock referenced by rwlock. The calling +thread acquires the write lock if no other thread (reader or writer) +holds the read-write lock rwlock. Otherwise, the thread shall +block until it can acquire the lock. The calling thread may deadlock +if at the time the call is made it holds the read-write lock (whether +a read or write lock). +

+

Pthreads-win32 does not prefer either writers or readers in +acquiring the lock – all threads enter a single prioritised FIFO +queue. While this may not be optimally efficient for some +applications, it does ensure that one type does not starve the other.

+

Results are undefined if any of these functions are called with an +uninitialized read-write lock. +

+

Pthreads-w32 defines _POSIX_READER_WRITER_LOCKS in +pthread.h as 200112L to indicate that the reader/writer routines are +implemented and may be used.

+

Return Value

+

The pthread_rwlock_trywrlock function shall return zero if +the lock for writing on the read-write lock object referenced by +rwlock is acquired. Otherwise, an error number shall be +returned to indicate the error. +

+

If successful, the pthread_rwlock_wrlock function shall +return zero; otherwise, an error number shall be returned to indicate +the error. +

+

Errors

+

The pthread_rwlock_trywrlock function shall fail if: +

+
+
EBUSY +
+ The read-write lock could not be acquired for writing because it was + already locked for reading or writing. +
+

+The pthread_rwlock_trywrlock and pthread_rwlock_wrlock +functions may fail if: +

+
+
EINVAL +
+ The value specified by rwlock does not refer to an + initialized read-write lock object. +
+

+These functions shall not return an error code of [EINTR]. +

+

The following sections are informative. +

+

Examples

+

None. +

+

Application Usage

+

Applications using these functions may be subject to priority +inversion, as discussed in the Base Definitions volume of +IEEE Std 1003.1-2001, Section 3.285, Priority Inversion. +

+

Rationale

+

None. +

+

Future Directions

+

None. +

+

See Also

+

pthread_rwlock_destroy(3) +, pthread_rwlock_rdlock(3) +, pthread_rwlock_timedrdlock(3) +, pthread_rwlock_timedwrlock(3) +, pthread_rwlock_tryrdlock(3) +, pthread_rwlock_unlock(3) +, the Base Definitions volume of IEEE Std 1003.1-2001, +<pthread.h> +

+

Copyright

+

Portions of this text are reprinted and reproduced in electronic +form from IEEE Std 1003.1, 2003 Edition, Standard for Information +Technology -- Portable Operating System Interface (POSIX), The Open +Group Base Specifications Issue 6, Copyright (C) 2001-2003 by the +Institute of Electrical and Electronics Engineers, Inc and The Open +Group. In the event of any discrepancy between this version and the +original IEEE and The Open Group Standard, the original IEEE and The +Open Group Standard is the referee document. The original Standard +can be obtained online at http://www.opengroup.org/unix/online.html +. +

+

Modified by Ross Johnson for use with Pthreads-w32.

+
+

Table of Contents

+ + + diff --git a/pthreads/manual/pthread_rwlockattr_init.html b/pthreads/manual/pthread_rwlockattr_init.html new file mode 100644 index 000000000..67da876cc --- /dev/null +++ b/pthreads/manual/pthread_rwlockattr_init.html @@ -0,0 +1,141 @@ + + + + + "PTHREAD_RWLOCKATTR_DESTROY"(P) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

pthread_rwlockattr_destroy, pthread_rwlockattr_init - destroy and +initialize the read-write lock attributes object +

+

Synopsis

+

#include <pthread.h> +

+

int pthread_rwlockattr_destroy(pthread_rwlockattr_t *attr); +
int pthread_rwlockattr_init(pthread_rwlockattr_t *attr); + +

+

Description

+

The pthread_rwlockattr_destroy function shall destroy a +read-write lock attributes object. A destroyed attr attributes +object can be reinitialized using pthread_rwlockattr_init ; +the results of otherwise referencing the object after it has been +destroyed are undefined. An implementation may cause +pthread_rwlockattr_destroy to set the object referenced by +attr to an invalid value. +

+

The pthread_rwlockattr_init function shall initialize a +read-write lock attributes object attr with the default value +for all of the attributes defined by the implementation. +

+

Results are undefined if pthread_rwlockattr_init is called +specifying an already initialized attr attributes object. +

+

After a read-write lock attributes object has been used to +initialize one or more read-write locks, any function affecting the +attributes object (including destruction) shall not affect any +previously initialized read-write locks. +

+

Pthreads-w32 defines _POSIX_READER_WRITER_LOCKS in +pthread.h as 200112L to indicate that the reader/writer routines are +implemented and may be used.

+

Return Value

+

If successful, the pthread_rwlockattr_destroy and +pthread_rwlockattr_init functions shall return zero; +otherwise, an error number shall be returned to indicate the error. +

+

Errors

+

The pthread_rwlockattr_destroy function may fail if: +

+
+
EINVAL +
+ The value specified by attr is invalid. +
+

+The pthread_rwlockattr_init function shall fail if: +

+
+
ENOMEM +
+ Insufficient memory exists to initialize the read-write lock + attributes object. +
+

+These functions shall not return an error code of [EINTR]. +

+

The following sections are informative. +

+

Examples

+

None. +

+

Application Usage

+

None. +

+

Rationale

+

None. +

+

Future Directions

+

None. +

+

See Also

+

pthread_rwlock_destroy(3) +, pthread_rwlockattr_getpshared(3) +, pthread_rwlockattr_setpshared(3) +, the Base Definitions volume of IEEE Std 1003.1-2001, +<pthread.h> +

+

Copyright

+

Portions of this text are reprinted and reproduced in electronic +form from IEEE Std 1003.1, 2003 Edition, Standard for Information +Technology -- Portable Operating System Interface (POSIX), The Open +Group Base Specifications Issue 6, Copyright (C) 2001-2003 by the +Institute of Electrical and Electronics Engineers, Inc and The Open +Group. In the event of any discrepancy between this version and the +original IEEE and The Open Group Standard, the original IEEE and The +Open Group Standard is the referee document. The original Standard +can be obtained online at http://www.opengroup.org/unix/online.html +. +

+

Modified by Ross Johnson for use with Pthreads-w32.

+
+

Table of Contents

+ + + diff --git a/pthreads/manual/pthread_rwlockattr_setpshared.html b/pthreads/manual/pthread_rwlockattr_setpshared.html new file mode 100644 index 000000000..9db6f4cdc --- /dev/null +++ b/pthreads/manual/pthread_rwlockattr_setpshared.html @@ -0,0 +1,160 @@ + + + + + "PTHREAD_RWLOCKATTR_GETPSHARED"(P) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

pthread_rwlockattr_getpshared, pthread_rwlockattr_setpshared - get +and set the process-shared attribute of the read-write lock +attributes object +

+

Synopsis

+

#include <pthread.h> +

+

int pthread_rwlockattr_getpshared(const pthread_rwlockattr_t * +restrict attr, int *restrict pshared); +
int pthread_rwlockattr_setpshared(pthread_rwlockattr_t *attr, +int pshared); +

+

Description

+

The pthread_rwlockattr_getpshared function shall obtain the +value of the process-shared attribute from the initialized +attributes object referenced by attr. The +pthread_rwlockattr_setpshared function shall set the +process-shared attribute in an initialized attributes object +referenced by attr. +

+

The process-shared attribute shall be set to +PTHREAD_PROCESS_SHARED to permit a read-write lock to be +operated upon by any thread that has access to the memory where the +read-write lock is allocated, even if the read-write lock is +allocated in memory that is shared by multiple processes. If the +process-shared attribute is PTHREAD_PROCESS_PRIVATE, +the read-write lock shall only be operated upon by threads created +within the same process as the thread that initialized the read-write +lock; if threads of differing processes attempt to operate on such a +read-write lock, the behavior is undefined. The default value of the +process-shared attribute shall be PTHREAD_PROCESS_PRIVATE. +

+

Pthreads-w32 defines _POSIX_THREAD_PROCESS_SHARED in +pthread.h as -1 to indicate that these routines are implemented but +they do not support the process shared option.

+

Additional attributes, their default values, and the names of the +associated functions to get and set those attribute values are +implementation-defined. +

+

Pthreads-w32 defines _POSIX_READER_WRITER_LOCKS in +pthread.h as 200112L to indicate that the reader/writer routines are +implemented and may be used.

+

Return Value

+

Upon successful completion, the pthread_rwlockattr_getpshared +function shall return zero and store the value of the process-shared +attribute of attr into the object referenced by the pshared +parameter. Otherwise, an error number shall be returned to indicate +the error. +

+

If successful, the pthread_rwlockattr_setpshared function +shall return zero; otherwise, an error number shall be returned to +indicate the error. +

+

Errors

+

The pthread_rwlockattr_getpshared and +pthread_rwlockattr_setpshared functions may fail if: +

+
+
EINVAL +
+ The value specified by attr is invalid. +
+

+The pthread_rwlockattr_setpshared function may fail if: +

+
+
EINVAL +
+ The new value specified for the attribute is outside the range of + legal values for that attribute. +
+ ENOTSUP +
+ The new value specified for the attribute is PTHREAD_PROCESS_SHARED. +
+

+These functions shall not return an error code of [EINTR]. +

+

The following sections are informative. +

+

Examples

+

None. +

+

Application Usage

+

None. +

+

Rationale

+

None. +

+

Future Directions

+

None. +

+

See Also

+

pthread_rwlock_destroy(3) +, pthread_rwlockattr_destroy(3) +, pthread_rwlockattr_init(3) +, the Base Definitions volume of IEEE Std 1003.1-2001, +<pthread.h> +

+

Copyright

+

Portions of this text are reprinted and reproduced in electronic +form from IEEE Std 1003.1, 2003 Edition, Standard for Information +Technology -- Portable Operating System Interface (POSIX), The Open +Group Base Specifications Issue 6, Copyright (C) 2001-2003 by the +Institute of Electrical and Electronics Engineers, Inc and The Open +Group. In the event of any discrepancy between this version and the +original IEEE and The Open Group Standard, the original IEEE and The +Open Group Standard is the referee document. The original Standard +can be obtained online at http://www.opengroup.org/unix/online.html +. +

+

Modified by Ross Johnson for use with Pthreads-w32.

+
+

Table of Contents

+ + + diff --git a/pthreads/manual/pthread_self.html b/pthreads/manual/pthread_self.html new file mode 100644 index 000000000..82e16eaa7 --- /dev/null +++ b/pthreads/manual/pthread_self.html @@ -0,0 +1,70 @@ + + + + + PTHREAD_SELF(3) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

pthread_self - return identifier of current thread +

+

Synopsis

+

#include <pthread.h> +

+

pthread_t pthread_self(void); +

+

Description

+

pthread_self return the thread identifier for the calling +thread. +

+

Pthreads-w32 also provides support for Win32 native +threads to interact with POSIX threads through the pthreads API. +Whereas all threads created via a call to pthread_create have a POSIX +thread ID and thread state, the library ensures that any Win32 native +threads that interact through the Pthreads API also generate a POSIX +thread ID and thread state when and if necessary. This provides full +reciprocity between Win32 and POSIX +threads. Win32 native threads that generate a POSIX thread ID and +state are treated by the library as having been created with the +PTHREAD_CREATE_DETACHED attribute.

+

Any Win32 native thread may call pthread_self directly to +return it's POSIX thread identifier. The ID and state will be +generated if it does not already exist. Win32 native threads do not +need to call pthread_self before calling Pthreads-w32 routines +unless that routine requires a pthread_t parameter.

+

Author

+

Xavier Leroy <Xavier.Leroy@inria.fr> +

+

Modified by Ross Johnson for use with Pthreads-w32.

+

See Also

+

pthread_equal(3) , +pthread_join(3) , +pthread_detach(3) , +pthread_setschedparam(3) +, pthread_getschedparam(3) +. +

+
+

Table of Contents

+ + + diff --git a/pthreads/manual/pthread_setcancelstate.html b/pthreads/manual/pthread_setcancelstate.html new file mode 100644 index 000000000..3ce65c44d --- /dev/null +++ b/pthreads/manual/pthread_setcancelstate.html @@ -0,0 +1,207 @@ + + + + + PTHREAD_CANCEL(3) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

pthread_cancel, pthread_setcancelstate, pthread_setcanceltype, +pthread_testcancel - thread cancellation +

+

Synopsis

+

#include <pthread.h> +

+

int pthread_cancel(pthread_t thread); +

+

int pthread_setcancelstate(int state, int +*oldstate); +

+

int pthread_setcanceltype(int type, int +*oldtype); +

+

void pthread_testcancel(void); +

+

Description

+

Cancellation is the mechanism by which a thread can terminate the +execution of another thread. More precisely, a thread can send a +cancellation request to another thread. Depending on its settings, +the target thread can then either ignore the request, honor it +immediately, or defer it until it reaches a cancellation point. +

+

When a thread eventually honors a cancellation request, it +performs as if pthread_exit(PTHREAD_CANCELED) has been called +at that point: all cleanup handlers are executed in reverse order, +destructor functions for thread-specific data are called, and finally +the thread stops executing with the return value PTHREAD_CANCELED. +See pthread_exit(3) for more +information. +

+

pthread_cancel sends a cancellation request to the thread +denoted by the thread argument. +

+

pthread_setcancelstate changes the cancellation state for +the calling thread -- that is, whether cancellation requests are +ignored or not. The state argument is the new cancellation +state: either PTHREAD_CANCEL_ENABLE to enable cancellation, or +PTHREAD_CANCEL_DISABLE to disable cancellation (cancellation +requests are ignored). If oldstate is not NULL, the +previous cancellation state is stored in the location pointed to by +oldstate, and can thus be restored later by another call to +pthread_setcancelstate. +

+

pthread_setcanceltype changes the type of responses to +cancellation requests for the calling thread: asynchronous +(immediate) or deferred. The type argument is the new +cancellation type: either PTHREAD_CANCEL_ASYNCHRONOUS to +cancel the calling thread as soon as the cancellation request is +received, or PTHREAD_CANCEL_DEFERRED to keep the cancellation +request pending until the next cancellation point. If oldtype +is not NULL, the previous cancellation state is stored in the +location pointed to by oldtype, and can thus be restored later +by another call to pthread_setcanceltype. +

+

Pthreads-w32 provides two levels of support for +PTHREAD_CANCEL_ASYNCHRONOUS: full and partial. Full support +requires an additional DLL and driver be installed on the Windows +system (see the See Also section below) that allows blocked threads +to be cancelled immediately. Partial support means that the target +thread will not cancel until it resumes execution naturally. Partial +support is provided if either the DLL or the driver are not +automatically detected by the pthreads-w32 library at run-time.

+

Threads are always created by pthread_create(3) +with cancellation enabled and deferred. That is, the initial +cancellation state is PTHREAD_CANCEL_ENABLE and the initial +type is PTHREAD_CANCEL_DEFERRED. +

+

Cancellation points are those points in the program execution +where a test for pending cancellation requests is performed and +cancellation is executed if positive. The following POSIX threads +functions are cancellation points: +

+

pthread_join(3) +
pthread_cond_wait(3) +
pthread_cond_timedwait(3) +
pthread_testcancel(3) +
sem_wait(3)
sem_timedwait(3) +
sigwait(3) (not supported under +Pthreads-w32)

+

Pthreads-w32 provides two functions to enable additional +cancellation points to be created in user functions that block on +Win32 HANDLEs:

+

pthreadCancelableWait() +
pthreadCancelableTimedWait()

+

All other POSIX threads functions are guaranteed not to be +cancellation points. That is, they never perform cancellation in +deferred cancellation mode. +

+

pthread_testcancel does nothing except testing for pending +cancellation and executing it. Its purpose is to introduce explicit +checks for cancellation in long sequences of code that do not call +cancellation point functions otherwise. +

+

Return Value

+

pthread_cancel, pthread_setcancelstate and +pthread_setcanceltype return 0 on success and a non-zero error +code on error. +

+

Errors

+

pthread_cancel returns the following error code on error: +

+
+
+
ESRCH +
+ no thread could be found corresponding to that specified by the + thread ID. +
+
+

+pthread_setcancelstate returns the following error code on +error: +

+
+
+
EINVAL +
+ the state argument is not +
+
+
+PTHREAD_CANCEL_ENABLE nor PTHREAD_CANCEL_DISABLE +
+

pthread_setcanceltype returns the following error code on +error: +

+
+
+
EINVAL +
+ the type argument is not +
+
+
+PTHREAD_CANCEL_DEFERRED nor PTHREAD_CANCEL_ASYNCHRONOUS +
+

Author

+

Xavier Leroy <Xavier.Leroy@inria.fr> +

+

Modified by Ross Johnson for use with Pthreads-w32.

+

See Also

+

pthread_exit(3) , +pthread_cleanup_push(3) +, pthread_cleanup_pop(3) +, Pthreads-w32 package README file 'Prerequisites' section. +

+

Bugs

+

POSIX specifies that a number of system calls (basically, all +system calls that may block, such as read(2) +, write(2) , wait(2) +, etc.) and library functions that may call these system calls (e.g. +fprintf(3) ) are cancellation +points. Pthreads-win32 is not integrated enough with the C +library to implement this, and thus none of the C library functions +is a cancellation point. +

+

A workaround for these calls is to temporarily switch to +asynchronous cancellation (assuming full asynchronous cancellation +support is installed). So, checking for cancellation during a read +system call, for instance, can be achieved as follows: +

+


+
+
pthread_setcanceltype(PTHREAD_CANCEL_ASYNCHRONOUS, &oldCancelType);
+read(fd, buffer, length);
+pthread_setcanceltype(oldCancelType, NULL);
+
+
Table of Contents
+ + + diff --git a/pthreads/manual/pthread_setcanceltype.html b/pthreads/manual/pthread_setcanceltype.html new file mode 100644 index 000000000..935ed822c --- /dev/null +++ b/pthreads/manual/pthread_setcanceltype.html @@ -0,0 +1,207 @@ + + + + + PTHREAD_CANCEL(3) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

pthread_cancel, pthread_setcancelstate, pthread_setcanceltype, +pthread_testcancel - thread cancellation +

+

Synopsis

+

#include <pthread.h> +

+

int pthread_cancel(pthread_t thread); +

+

int pthread_setcancelstate(int state, int +*oldstate); +

+

int pthread_setcanceltype(int type, int +*oldtype); +

+

void pthread_testcancel(void); +

+

Description

+

Cancellation is the mechanism by which a thread can terminate the +execution of another thread. More precisely, a thread can send a +cancellation request to another thread. Depending on its settings, +the target thread can then either ignore the request, honor it +immediately, or defer it until it reaches a cancellation point. +

+

When a thread eventually honors a cancellation request, it +performs as if pthread_exit(PTHREAD_CANCELED) has been called +at that point: all cleanup handlers are executed in reverse order, +destructor functions for thread-specific data are called, and finally +the thread stops executing with the return value PTHREAD_CANCELED. +See pthread_exit(3) for more +information. +

+

pthread_cancel sends a cancellation request to the thread +denoted by the thread argument. +

+

pthread_setcancelstate changes the cancellation state for +the calling thread -- that is, whether cancellation requests are +ignored or not. The state argument is the new cancellation +state: either PTHREAD_CANCEL_ENABLE to enable cancellation, or +PTHREAD_CANCEL_DISABLE to disable cancellation (cancellation +requests are ignored). If oldstate is not NULL, the +previous cancellation state is stored in the location pointed to by +oldstate, and can thus be restored later by another call to +pthread_setcancelstate. +

+

pthread_setcanceltype changes the type of responses to +cancellation requests for the calling thread: asynchronous +(immediate) or deferred. The type argument is the new +cancellation type: either PTHREAD_CANCEL_ASYNCHRONOUS to +cancel the calling thread as soon as the cancellation request is +received, or PTHREAD_CANCEL_DEFERRED to keep the cancellation +request pending until the next cancellation point. If oldtype +is not NULL, the previous cancellation state is stored in the +location pointed to by oldtype, and can thus be restored later +by another call to pthread_setcanceltype. +

+

Pthreads-w32 provides two levels of support for +PTHREAD_CANCEL_ASYNCHRONOUS: full and partial. Full support +requires an additional DLL and driver be installed on the Windows +system (see the See Also section below) that allows blocked threads +to be cancelled immediately. Partial support means that the target +thread will not cancel until it resumes execution naturally. Partial +support is provided if either the DLL or the driver are not +automatically detected by the pthreads-w32 library at run-time.

+

Threads are always created by pthread_create(3) +with cancellation enabled and deferred. That is, the initial +cancellation state is PTHREAD_CANCEL_ENABLE and the initial +type is PTHREAD_CANCEL_DEFERRED. +

+

Cancellation points are those points in the program execution +where a test for pending cancellation requests is performed and +cancellation is executed if positive. The following POSIX threads +functions are cancellation points: +

+

pthread_join(3) +
pthread_cond_wait(3) +
pthread_cond_timedwait(3) +
pthread_testcancel(3) +
sem_wait(3)
sem_timedwait(3) +
sigwait(3) (not supported under +Pthreads-w32)

+

Pthreads-w32 provides two functions to enable additional +cancellation points to be created in user functions that block on +Win32 HANDLEs:

+

pthreadCancelableWait() +
pthreadCancelableTimedWait()

+

All other POSIX threads functions are guaranteed not to be +cancellation points. That is, they never perform cancellation in +deferred cancellation mode. +

+

pthread_testcancel does nothing except testing for pending +cancellation and executing it. Its purpose is to introduce explicit +checks for cancellation in long sequences of code that do not call +cancellation point functions otherwise. +

+

Return Value

+

pthread_cancel, pthread_setcancelstate and +pthread_setcanceltype return 0 on success and a non-zero error +code on error. +

+

Errors

+

pthread_cancel returns the following error code on error: +

+
+
+
ESRCH +
+ no thread could be found corresponding to that specified by the + thread ID. +
+
+

+pthread_setcancelstate returns the following error code on +error: +

+
+
+
EINVAL +
+ the state argument is not +
+
+
+PTHREAD_CANCEL_ENABLE nor PTHREAD_CANCEL_DISABLE +
+

pthread_setcanceltype returns the following error code on +error: +

+
+
+
EINVAL +
+ the type argument is not +
+
+
+PTHREAD_CANCEL_DEFERRED nor PTHREAD_CANCEL_ASYNCHRONOUS +
+

Author

+

Xavier Leroy <Xavier.Leroy@inria.fr> +

+

Modified by Ross Johnson for use with Pthreads-w32.

+

See Also

+

pthread_exit(3) , +pthread_cleanup_push(3) +, pthread_cleanup_pop(3) +, Pthreads-w32 package README file 'Prerequisites' section. +

+

Bugs

+

POSIX specifies that a number of system calls (basically, all +system calls that may block, such as read(2) +, write(2) , wait(2) +, etc.) and library functions that may call these system calls (e.g. +fprintf(3) ) are cancellation +points. Pthreads-win32 is not integrated enough with the C +library to implement this, and thus none of the C library functions +is a cancellation point. +

+

A workaround for these calls is to temporarily switch to +asynchronous cancellation (assuming full asynchronous cancellation +support is installed). So, checking for cancellation during a read +system call, for instance, can be achieved as follows: +

+


+
+
pthread_setcanceltype(PTHREAD_CANCEL_ASYNCHRONOUS, &oldCancelType);
+read(fd, buffer, length);
+pthread_setcanceltype(oldCancelType, NULL);
+
+
Table of Contents
+ + + diff --git a/pthreads/manual/pthread_setconcurrency.html b/pthreads/manual/pthread_setconcurrency.html new file mode 100644 index 000000000..cdd4f5840 --- /dev/null +++ b/pthreads/manual/pthread_setconcurrency.html @@ -0,0 +1,155 @@ + + + + + "PTHREAD_GETCONCURRENCY"(P) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

pthread_getconcurrency, pthread_setconcurrency - get and set the +level of concurrency +

+

Synopsis

+

#include <pthread.h> +

+

int pthread_getconcurrency(void);
int +pthread_setconcurrency(int new_level); +

+

Description

+

Unbound threads in a process may or may not be required to be +simultaneously active. By default, the threads implementation ensures +that a sufficient number of threads are active so that the process +can continue to make progress. While this conserves system resources, +it may not produce the most effective level of concurrency. +

+

The pthread_setconcurrency function allows an application +to inform the threads implementation of its desired concurrency +level, new_level. The actual level of concurrency provided by +the implementation as a result of this function call is unspecified. +

+

If new_level is zero, it causes the implementation to +maintain the concurrency level at its discretion as if +pthread_setconcurrency had never been called. +

+

The pthread_getconcurrency function shall return the value +set by a previous call to the pthread_setconcurrency function. +If the pthread_setconcurrency function was not previously +called, this function shall return zero to indicate that the +implementation is maintaining the concurrency level. +

+

A call to pthread_setconcurrency shall inform the +implementation of its desired concurrency level. The implementation +shall use this as a hint, not a requirement. +

+

If an implementation does not support multiplexing of user threads +on top of several kernel-scheduled entities, the +pthread_setconcurrency and pthread_getconcurrency +functions are provided for source code compatibility but they shall +have no effect when called. To maintain the function semantics, the +new_level parameter is saved when pthread_setconcurrency +is called so that a subsequent call to pthread_getconcurrency +shall return the same value. +

+

Pthreads-w32 provides these routines for source code +compatibility only, as described in the previous paragraph.

+

Return Value

+

If successful, the pthread_setconcurrency function shall +return zero; otherwise, an error number shall be returned to indicate +the error. +

+

The pthread_getconcurrency function shall always return the +concurrency level set by a previous call to pthread_setconcurrency +. If the pthread_setconcurrency function has never been +called, pthread_getconcurrency shall return zero. +

+

Errors

+

The pthread_setconcurrency function shall fail if: +

+
+
EINVAL +
+ The value specified by new_level is negative. +
+ EAGAIN +
+ The value specific by new_level would cause a system resource + to be exceeded. +
+

+These functions shall not return an error code of [EINTR]. +

+

The following sections are informative. +

+

Examples

+

None. +

+

Application Usage

+

Use of these functions changes the state of the underlying +concurrency upon which the application depends. Library developers +are advised to not use the pthread_getconcurrency and +pthread_setconcurrency functions since their use may conflict +with an applications use of these functions. +

+

Rationale

+

None. +

+

Future Directions

+

None. +

+

See Also

+

The Base Definitions volume of IEEE Std 1003.1-2001, +<pthread.h> +

+

Copyright

+

Portions of this text are reprinted and reproduced in electronic +form from IEEE Std 1003.1, 2003 Edition, Standard for Information +Technology -- Portable Operating System Interface (POSIX), The Open +Group Base Specifications Issue 6, Copyright (C) 2001-2003 by the +Institute of Electrical and Electronics Engineers, Inc and The Open +Group. In the event of any discrepancy between this version and the +original IEEE and The Open Group Standard, the original IEEE and The +Open Group Standard is the referee document. The original Standard +can be obtained online at http://www.opengroup.org/unix/online.html +. +

+

Modified by Ross Johnson for use with Pthreads-w32.

+
+

Table of Contents

+ + + diff --git a/pthreads/manual/pthread_setschedparam.html b/pthreads/manual/pthread_setschedparam.html new file mode 100644 index 000000000..920c20bab --- /dev/null +++ b/pthreads/manual/pthread_setschedparam.html @@ -0,0 +1,113 @@ + + + + + PTHREAD_SETSCHEDPARAM(3) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

pthread_setschedparam, pthread_getschedparam - control thread +scheduling +

+

parameters +

+

Synopsis

+

#include <pthread.h> +

+

int pthread_setschedparam(pthread_t target_thread, +int policy, const struct sched_param *param); +

+

int pthread_getschedparam(pthread_t target_thread, +int *policy, struct sched_param *param); +

+

Description

+

pthread_setschedparam sets the scheduling parameters for +the thread target_thread as indicated by policy and +param. policy can be either SCHED_OTHER +(regular, non-real-time scheduling), SCHED_RR (real-time, +round-robin) or SCHED_FIFO (real-time, first-in first-out). +param specifies the scheduling priority for the two real-time +policies.

+

Pthreads-w32 only supports SCHED_OTHER and does not support +the real-time scheduling policies SCHED_RR and SCHED_FIFO. +

+

pthread_getschedparam retrieves the scheduling policy and +scheduling parameters for the thread target_thread and stores +them in the locations pointed to by policy and param, +respectively. +

+

Return Value

+

pthread_setschedparam and pthread_getschedparam +return 0 on success and a non-zero error code on error. +

+

Errors

+

On error, pthread_setschedparam returns the following error +codes: +

+
+
+
ENOTSUP +
+ policy is not SCHED_OTHER.
+ EINVAL +
+ One of the arguments is invalid, or the priority value specified by + param is not valid for the specified policy.
+ ESRCH +
+ The target_thread is invalid or has already terminated +
+
+

+On error, pthread_getschedparam returns the following error +codes: +

+
+
+
ESRCH +
+ the target_thread is invalid or has already terminated +
+
+

+Author

+

Xavier Leroy <Xavier.Leroy@inria.fr> +

+

Modified by Ross Johnson for use with Pthreads-w32.

+

See Also

+

sched_setscheduler(2) +, sched_getscheduler(2) +, sched_getparam(2) , +pthread_attr_setschedpolicy(3) +, pthread_attr_setschedparam(3) +. +

+
+

Table of Contents

+ + + \ No newline at end of file diff --git a/pthreads/manual/pthread_spin_init.html b/pthreads/manual/pthread_spin_init.html new file mode 100644 index 000000000..35e657be4 --- /dev/null +++ b/pthreads/manual/pthread_spin_init.html @@ -0,0 +1,176 @@ + + + + + "PTHREAD_SPIN_DESTROY"(P) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

pthread_spin_destroy, pthread_spin_init - destroy or initialize a +spin lock object (ADVANCED REALTIME THREADS) +

+

Synopsis

+

#include <pthread.h> +

+

pthread_spinlock_t lock = +PTHREAD_SPINLOCK_INITIALIZER;

+

int pthread_spin_destroy(pthread_spinlock_t *lock); +
int pthread_spin_init(pthread_spinlock_t *lock, int +pshared); +

+

Description

+

The pthread_spin_destroy function shall destroy the spin +lock referenced by lock and release any resources used by the +lock. The effect of subsequent use of the lock is undefined until the +lock is reinitialized by another call to pthread_spin_init . +The results are undefined if pthread_spin_destroy is called +when a thread holds the lock, or if this function is called with an +uninitialized thread spin lock. +

+

The pthread_spin_init function shall allocate any resources +required to use the spin lock referenced by lock and +initialize the lock to an unlocked state. +

+

Pthreads-w32 supports single and multiple processor systems +as well as process CPU affinity masking by checking the mask when the +spin lock is initialized. If the process is using only a single +processor at the time pthread_spin_init is called then the +spin lock is initialized as a PTHREAD_MUTEX_NORMAL mutex object. A +thread that calls pthread_spin_lock(3) +will block rather than spin in this case. If the process CPU affinity +mask is altered after the spin lock has been initialised, the spin +lock is not modified, and may no longer be optimal for the number of +CPUs available.

+

Pthreads-w32 defines _POSIX_THREAD_PROCESS_SHARED in +pthread.h as -1 to indicate that these routines do not support the +PTHREAD_PROCESS_SHARED attribute. pthread_spin_init +will return the error ENOTSUP if the value of pshared +is not PTHREAD_PROCESS_PRIVATE.

+

The results are undefined if pthread_spin_init is called +specifying an already initialized spin lock. The results are +undefined if a spin lock is used without first being initialized. +

+

If the pthread_spin_init function fails, the lock is not +initialized and the contents of lock are undefined. +

+

Only the object referenced by lock may be used for +performing synchronization. +

+

The result of referring to copies of that object in calls to +pthread_spin_destroy , pthread_spin_lock(3) +, pthread_spin_trylock(3), +or pthread_spin_unlock(3) +is undefined. +

+

Pthreads-w32 supports statically initialized spin locks +using PTHREAD_SPINLOCK_INITIALIZER. An application should +still call pthread_spin_destroy at some point to ensure that +any resources consumed by the spin lock are released.

+

Return Value

+

Upon successful completion, these functions shall return zero; +otherwise, an error number shall be returned to indicate the error. +

+

Errors

+

These functions may fail if: +

+
+
EBUSY +
+ The implementation has detected an attempt to initialize or destroy + a spin lock while it is in use (for example, while being used in a + pthread_spin_lock(3) + call) by another thread. +
+ EINVAL +
+ The value specified by lock is invalid. +
+

+The pthread_spin_init function shall fail if: +

+
+
ENOTSUP +
+ The value of pshared is not PTHREAD_PROCESS_PRIVATE.
+ ENOMEM +
+ Insufficient memory exists to initialize the lock. +
+

+These functions shall not return an error code of [EINTR]. +

+

The following sections are informative. +

+

Examples

+

None. +

+

Application Usage

+

The pthread_spin_destroy and pthread_spin_init +functions are part of the Spin Locks option and need not be provided +on all implementations. +

+

Rationale

+

None. +

+

Future Directions

+

None. +

+

See Also

+

pthread_spin_lock(3) , +pthread_spin_unlock(3) +, the Base Definitions volume of IEEE Std 1003.1-2001, +<pthread.h> +

+

Copyright

+

Portions of this text are reprinted and reproduced in electronic +form from IEEE Std 1003.1, 2003 Edition, Standard for Information +Technology -- Portable Operating System Interface (POSIX), The Open +Group Base Specifications Issue 6, Copyright (C) 2001-2003 by the +Institute of Electrical and Electronics Engineers, Inc and The Open +Group. In the event of any discrepancy between this version and the +original IEEE and The Open Group Standard, the original IEEE and The +Open Group Standard is the referee document. The original Standard +can be obtained online at http://www.opengroup.org/unix/online.html +. +

+

Modified by Ross Johnson for use with Pthreads-w32.

+
+

Table of Contents

+ + + diff --git a/pthreads/manual/pthread_spin_lock.html b/pthreads/manual/pthread_spin_lock.html new file mode 100644 index 000000000..dd180ae6a --- /dev/null +++ b/pthreads/manual/pthread_spin_lock.html @@ -0,0 +1,141 @@ + + + + + "PTHREAD_SPIN_LOCK"(P) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

pthread_spin_lock, pthread_spin_trylock - lock a spin lock object +(ADVANCED REALTIME THREADS) +

+

Synopsis

+

#include <pthread.h> +

+

int pthread_spin_lock(pthread_spinlock_t *lock); +
int pthread_spin_trylock(pthread_spinlock_t *lock); + +

+

Description

+

The pthread_spin_lock function shall lock the spin lock +referenced by lock. The calling thread shall acquire the lock +if it is not held by another thread. Otherwise, the thread shall spin +(that is, shall not return from the pthread_spin_lock call) +until the lock becomes available. The results are undefined if the +calling thread holds the lock at the time the call is made.

+

Pthreads-w32 supports single and multiple processor systems +as well as process CPU affinity masking by checking the mask when the +spin lock is initialized. If the process is using only a single +processor at the time pthread_spin_init(3) +is called then the spin lock is initialized as a PTHREAD_MUTEX_NORMAL +mutex object. A thread that calls pthread_spin_lock will block +rather than spin in this case. If the process CPU affinity mask is +altered after the spin lock has been initialised, the spin lock is +not modified, and may no longer be optimal for the number of CPUs +available.

+

The pthread_spin_trylock function shall lock the spin lock +referenced by lock if it is not held by any thread. Otherwise, +the function shall fail. +

+

The results are undefined if any of these functions is called with +an uninitialized spin lock. +

+

Return Value

+

Upon successful completion, these functions shall return zero; +otherwise, an error number shall be returned to indicate the error. +

+

Errors

+

These functions may fail if: +

+
+
EINVAL +
+ The value specified by lock does not refer to an initialized + spin lock object. +
+

+The pthread_spin_trylock function shall fail if: +

+
+
EBUSY +
+ A thread currently holds the lock. +
+

+These functions shall not return an error code of [EINTR]. +

+

The following sections are informative. +

+

Examples

+

None. +

+

Application Usage

+

Applications using this function may be subject to priority +inversion, as discussed in the Base Definitions volume of +IEEE Std 1003.1-2001, Section 3.285, Priority Inversion. +

+

Rationale

+

None. +

+

Future Directions

+

None. +

+

See Also

+

pthread_spin_destroy(3) +, pthread_spin_unlock(3) +, the Base Definitions volume of IEEE Std 1003.1-2001, +<pthread.h> +

+

Copyright

+

Portions of this text are reprinted and reproduced in electronic +form from IEEE Std 1003.1, 2003 Edition, Standard for Information +Technology -- Portable Operating System Interface (POSIX), The Open +Group Base Specifications Issue 6, Copyright (C) 2001-2003 by the +Institute of Electrical and Electronics Engineers, Inc and The Open +Group. In the event of any discrepancy between this version and the +original IEEE and The Open Group Standard, the original IEEE and The +Open Group Standard is the referee document. The original Standard +can be obtained online at http://www.opengroup.org/unix/online.html +. +

+

Modified by Ross Johnson for use with Pthreads-w32.

+
+

Table of Contents

+ + + diff --git a/pthreads/manual/pthread_spin_unlock.html b/pthreads/manual/pthread_spin_unlock.html new file mode 100644 index 000000000..221570058 --- /dev/null +++ b/pthreads/manual/pthread_spin_unlock.html @@ -0,0 +1,124 @@ + + + + + "PTHREAD_SPIN_UNLOCK"(P) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

pthread_spin_unlock - unlock a spin lock object (ADVANCED +REALTIME THREADS) +

+

Synopsis

+

#include <pthread.h> +

+

int pthread_spin_unlock(pthread_spinlock_t *lock); + +

+

Description

+

The pthread_spin_unlock function shall release the spin +lock referenced by lock which was locked via the +pthread_spin_lock(3) or +pthread_spin_trylock(3) +functions. If there are threads spinning on the lock when +pthread_spin_unlock is called, the lock becomes available and +an unspecified spinning thread shall acquire the lock. +

+

Pthreads-w32 does not check ownership of the lock and it is +therefore possible for a thread other than the locker to unlock the +spin lock. This is not a feature that should be exploited.

+

The results are undefined if this function is called with an +uninitialized thread spin lock. +

+

Return Value

+

Upon successful completion, the pthread_spin_unlock +function shall return zero; otherwise, an error number shall be +returned to indicate the error. +

+

Errors

+

The pthread_spin_unlock function may fail if: +

+
+
EINVAL +
+ An invalid argument was specified. +
+
+
+

+This function shall not return an error code of [EINTR]. +

+

The following sections are informative. +

+

Examples

+

None. +

+

Application Usage

+

Pthreads-w32 does not check ownership of the lock and it is +therefore possible for a thread other than the locker to unlock the +spin lock. This is not a feature that should be exploited.

+

Rationale

+

None. +

+

Future Directions

+

None. +

+

See Also

+

pthread_spin_destroy(3) +, pthread_spin_lock(3) +, the Base Definitions volume of IEEE Std 1003.1-2001, +<pthread.h> +

+

Copyright

+

Portions of this text are reprinted and reproduced in electronic +form from IEEE Std 1003.1, 2003 Edition, Standard for Information +Technology -- Portable Operating System Interface (POSIX), The Open +Group Base Specifications Issue 6, Copyright (C) 2001-2003 by the +Institute of Electrical and Electronics Engineers, Inc and The Open +Group. In the event of any discrepancy between this version and the +original IEEE and The Open Group Standard, the original IEEE and The +Open Group Standard is the referee document. The original Standard +can be obtained online at http://www.opengroup.org/unix/online.html +. +

+

Modified by Ross Johnson for use with Pthreads-w32.

+
+

Table of Contents

+ + + diff --git a/pthreads/manual/pthread_timechange_handler_np.html b/pthreads/manual/pthread_timechange_handler_np.html new file mode 100644 index 000000000..54226da7d --- /dev/null +++ b/pthreads/manual/pthread_timechange_handler_np.html @@ -0,0 +1,76 @@ + + + + + PTHREAD_TIMECHANGE_HANDLER_NP manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

pthread_timechange_handler_np – +alert timed waiting condition variables to system time changes.

+

Synopsis

+

#include <pthread.h> +

+

void * pthread_timechange_handler_np(void * dummy);

+

Description

+

To improve tolerance against operator or time service initiated +system clock changes.

+

pthread_timechange_handler_np can be called by an +application when it receives a WM_TIMECHANGE message from the system. +At present it broadcasts all condition variables so that waiting +threads can wake up and re-evaluate their conditions and restart +their timed waits if required.

+

pthread_timechange_handler_np has the same return type and +argument type as a thread routine so that it may be called directly +through pthread_create(), i.e. as a separate thread. If run as a +thread, the return code must be retrieved through pthread_join().

+

Although the dummy parameter is required it is not used and +any value including NULL can be given.

+

Cancellation

+

None.

+

Return Value

+

pthread_timechange_handler_np returns 0 on success, or an +error code.

+

Errors

+

The pthread_timechange_handler_np function returns the +following error code on error: +

+
+
+
EAGAIN +
+
+

+To indicate that not all condition variables were signalled for some +reason.

+

Author

+

Ross Johnson for use with Pthreads-w32.

+
+

Table of Contents

+ + + diff --git a/pthreads/manual/pthread_win32_attach_detach_np.html b/pthreads/manual/pthread_win32_attach_detach_np.html new file mode 100644 index 000000000..57f0339a6 --- /dev/null +++ b/pthreads/manual/pthread_win32_attach_detach_np.html @@ -0,0 +1,74 @@ + + + + + PTHREAD_WIN32_ATTACH_DETACH_NP manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

pthread_win32_process_attach_np, +pthread_win32_process_detach_np, pthread_win32_thread_attach_np, +pthread_win32_thread_detach_np – exposed versions of the +pthreads-w32 DLL dllMain() switch functionality for use when +statically linking the library.

+

Synopsis

+

#include <pthread.h> +

+

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);

+

Description

+

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 the +implicit pthread handle that is allocated to a Win32 thread if it +calls certain pthreads routines. Call this routine when the Win32 +thread exits.

+

These functions invariably return TRUE except for +pthread_win32_process_attach_np which will return FALSE if +pthreads-w32 initialisation fails.

+

Cancellation

+

None.

+

Return Value

+

These routines return TRUE (non-zero) on success, or FALSE (0) if +they fail.

+

Errors

+

None.

+

Author

+

Ross Johnson for use with Pthreads-w32.

+
+

Table of Contents

+ + + diff --git a/pthreads/manual/pthread_win32_test_features_np.html b/pthreads/manual/pthread_win32_test_features_np.html new file mode 100644 index 000000000..1d8e11233 --- /dev/null +++ b/pthreads/manual/pthread_win32_test_features_np.html @@ -0,0 +1,68 @@ + + + + + PTHREAD_WIN32_TEST_FEATURES_NP manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

pthread_win32_test_features_np – +find out what features were detected at process attach time.

+

Synopsis

+

#include <pthread.h> +

+

BOOL pthread_win32_test_features_np(int mask);

+

Description

+

pthread_win32_test_features_np allows an application to +check which run-time auto-detected features are available within the +library.

+

The possible features are:

+

PTW32_SYSTEM_INTERLOCKED_COMPARE_EXCHANGE

+

Return TRUE if the Win32 version of +InterlockedCompareExchange() is being used. On IA32 systems the +library can use optimised and inlinable assembler versions of +InterlockedExchange() and InterlockedCompareExchange().

+

PTW32_ALERTABLE_ASYNC_CANCEL

+

Return TRUE if the QueueUserAPCEx package +QUSEREX.DLL and the AlertDrv.sys driver was detected. This package +provides alertable (pre-emptive) asynchronous threads cancellation. +If this feature returns FALSE then the default async cancel scheme is +in use, which cannot cancel blocked threads.

+

Cancellation

+

None.

+

Return Value

+

pthread_win32_test_features_np returns TRUE (non-zero) if +the specified feature is present, and FALSE (0) otherwise.

+

Errors

+

None.

+

Author

+

Ross Johnson for use with Pthreads-w32.

+
+

Table of Contents

+ + + \ No newline at end of file diff --git a/pthreads/manual/sched_get_priority_max.html b/pthreads/manual/sched_get_priority_max.html new file mode 100644 index 000000000..54869029b --- /dev/null +++ b/pthreads/manual/sched_get_priority_max.html @@ -0,0 +1,115 @@ + + + + + "SCHED_GET_PRIORITY_MAX"(P) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

sched_get_priority_max, sched_get_priority_min - get priority +limits (REALTIME) +

+

Synopsis

+

#include <sched.h> +

+

int sched_get_priority_max(int policy);
int +sched_get_priority_min(int policy); +

+

Description

+

The sched_get_priority_max and sched_get_priority_min +functions shall return the appropriate maximum or minimum, +respectively, for the scheduling policy specified by policy. +

+

The value of policy shall be one of the scheduling policy +values defined in <sched.h>. +

+

Return Value

+

If successful, the sched_get_priority_max and +sched_get_priority_min functions shall return the appropriate +maximum or minimum values, respectively. If unsuccessful, they shall +return a value of -1 and set errno to indicate the error. +

+

Errors

+

The sched_get_priority_max and sched_get_priority_min +functions shall fail if: +

+
+
EINVAL +
+ The value of the policy parameter does not represent a + defined scheduling policy. +
+

+The following sections are informative. +

+

Examples

+

None. +

+

Application Usage

+

None. +

+

Rationale

+

None. +

+

Future Directions

+

None. +

+

See Also

+

sched_getscheduler(3) +, sched_setscheduler(3) +, the Base Definitions volume of IEEE Std 1003.1-2001, +<sched.h> +

+

Copyright

+

Portions of this text are reprinted and reproduced in electronic +form from IEEE Std 1003.1, 2003 Edition, Standard for Information +Technology -- Portable Operating System Interface (POSIX), The Open +Group Base Specifications Issue 6, Copyright (C) 2001-2003 by the +Institute of Electrical and Electronics Engineers, Inc and The Open +Group. In the event of any discrepancy between this version and the +original IEEE and The Open Group Standard, the original IEEE and The +Open Group Standard is the referee document. The original Standard +can be obtained online at http://www.opengroup.org/unix/online.html +. +

+

Modified by Ross Johnson for use with Pthreads-w32.

+
+

Table of Contents

+ + + \ No newline at end of file diff --git a/pthreads/manual/sched_getscheduler.html b/pthreads/manual/sched_getscheduler.html new file mode 100644 index 000000000..0089e244f --- /dev/null +++ b/pthreads/manual/sched_getscheduler.html @@ -0,0 +1,127 @@ + + + + + "SCHED_GETSCHEDULER"(P) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

sched_getscheduler - get scheduling policy (REALTIME) +

+

Synopsis

+

#include <sched.h> +

+

int sched_getscheduler(pid_t pid); +

+

Description

+

The sched_getscheduler function shall return the scheduling +policy of the process specified by pid. If the value of pid +is negative, the behavior of the sched_getscheduler function +is unspecified. +

+

The values that can be returned by sched_getscheduler are +defined in the <sched.h> header. +

+

Pthreads-w32 only supports the SCHED_OTHER policy, +which is the only value that can be returned. However, checks on pid +and permissions are performed first so that the other useful side +effects of this routine are retained.

+

If a process specified by pid exists, and if the calling +process has permission, the scheduling policy shall be returned for +the process whose process ID is equal to pid. +

+

If pid is zero, the scheduling policy shall be returned for +the calling process. +

+

Return Value

+

Upon successful completion, the sched_getscheduler function +shall return the scheduling policy of the specified process. If +unsuccessful, the function shall return -1 and set errno to +indicate the error. +

+

Errors

+

The sched_getscheduler function shall fail if: +

+
+
EPERM +
+ The requesting process does not have permission to determine the + scheduling policy of the specified process. +
+ ESRCH +
+ No process can be found corresponding to that specified by pid. +
+

+The following sections are informative. +

+

Examples

+

None. +

+

Application Usage

+

None. +

+

Rationale

+

None. +

+

Future Directions

+

None. +

+

See Also

+

sched_setscheduler(3) +, the Base Definitions volume of IEEE Std 1003.1-2001, +<sched.h> +

+

Copyright

+

Portions of this text are reprinted and reproduced in electronic +form from IEEE Std 1003.1, 2003 Edition, Standard for Information +Technology -- Portable Operating System Interface (POSIX), The Open +Group Base Specifications Issue 6, Copyright (C) 2001-2003 by the +Institute of Electrical and Electronics Engineers, Inc and The Open +Group. In the event of any discrepancy between this version and the +original IEEE and The Open Group Standard, the original IEEE and The +Open Group Standard is the referee document. The original Standard +can be obtained online at http://www.opengroup.org/unix/online.html +. +

+

Modified by Ross Johnson for use with Pthreads-w32.

+
+

Table of Contents

+ + + diff --git a/pthreads/manual/sched_setscheduler.html b/pthreads/manual/sched_setscheduler.html new file mode 100644 index 000000000..c6e62ae0d --- /dev/null +++ b/pthreads/manual/sched_setscheduler.html @@ -0,0 +1,181 @@ + + + + + "SCHED_SETSCHEDULER"(P) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

sched_setscheduler - set scheduling policy and parameters +(REALTIME) +

+

Synopsis

+

#include <sched.h> +

+

int sched_setscheduler(pid_t pid, int policy, +const struct sched_param *param); +

+

Description

+

The sched_setscheduler function shall set the scheduling +policy and scheduling parameters of the process specified by pid +to policy and the parameters specified in the sched_param +structure pointed to by param, respectively. The value of the +sched_priority member in the sched_param structure +shall be any integer within the inclusive priority range for the +scheduling policy specified by policy. If the value of pid +is negative, the behavior of the sched_setscheduler function +is unspecified. +

+

The possible values for the policy parameter are defined in +the <sched.h> header. +

+

Pthreads-w32 only supports the SCHED_OTHER policy. +Any other value for policy will return failure with errno set +to ENOSYS. However, checks on pid and permissions are +performed first so that the other useful side effects of this routine +are retained.

+

If a process specified by pid exists, and if the calling +process has permission, the scheduling policy and scheduling +parameters shall be set for the process whose process ID is equal to +pid. +

+

If pid is zero, the scheduling policy and scheduling +parameters shall be set for the calling process. +

+

Implementations may require that the requesting process have +permission to set its own scheduling parameters or those of another +process. Additionally, implementation-defined restrictions may apply +as to the appropriate privileges required to set a process’ own +scheduling policy, or another process’ scheduling policy, to a +particular value. +

+

The sched_setscheduler function shall be considered +successful if it succeeds in setting the scheduling policy and +scheduling parameters of the process specified by pid to the +values specified by policy and the structure pointed to by +param, respectively. +

+

The effect of this function on individual threads is dependent on +the scheduling contention scope of the threads: +

+
+
* +
+ For threads with system scheduling contention scope, these functions + shall have no effect on their scheduling. +
+ * +
+ For threads with process scheduling contention scope, the threads’ + scheduling policy and associated parameters shall not be affected. + However, the scheduling of these threads with respect to threads in + other processes may be dependent on the scheduling parameters of + their process, which are governed using these functions. +
+

+This function is not atomic with respect to other threads in the +process. Threads may continue to execute while this function call is +in the process of changing the scheduling policy and associated +scheduling parameters for the underlying kernel-scheduled entities +used by the process contention scope threads. +

+

Return Value

+

Upon successful completion, the function shall return the former +scheduling policy of the specified process. If the sched_setscheduler +function fails to complete successfully, the policy and scheduling +parameters shall remain unchanged, and the function shall return a +value of -1 and set errno to indicate the error. +

+

Errors

+

The sched_setscheduler function shall fail if: +

+
+
EINVAL +
+ The value of the policy parameter is invalid, or one or more + of the parameters contained in param is outside the valid + range for the specified scheduling policy. +
+ EPERM +
+ The requesting process does not have permission to set either or + both of the scheduling parameters or the scheduling policy of the + specified process. +
+ ESRCH +
+ No process can be found corresponding to that specified by pid. +
+

+The following sections are informative. +

+

Examples

+

None. +

+

Application Usage

+

None. +

+

Rationale

+

None. +

+

Future Directions

+

None. +

+

See Also

+

sched_getscheduler(3) +, the Base Definitions volume of IEEE Std 1003.1-2001, +<sched.h> +

+

Copyright

+

Portions of this text are reprinted and reproduced in electronic +form from IEEE Std 1003.1, 2003 Edition, Standard for Information +Technology -- Portable Operating System Interface (POSIX), The Open +Group Base Specifications Issue 6, Copyright (C) 2001-2003 by the +Institute of Electrical and Electronics Engineers, Inc and The Open +Group. In the event of any discrepancy between this version and the +original IEEE and The Open Group Standard, the original IEEE and The +Open Group Standard is the referee document. The original Standard +can be obtained online at http://www.opengroup.org/unix/online.html +. +

+

Modified by Ross Johnson for use with Pthreads-w32.

+
+

Table of Contents

+ + + diff --git a/pthreads/manual/sched_yield.html b/pthreads/manual/sched_yield.html new file mode 100644 index 000000000..fa5ed04d5 --- /dev/null +++ b/pthreads/manual/sched_yield.html @@ -0,0 +1,98 @@ + + + + + "SCHED_YIELD"(P) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

sched_yield - yield the processor +

+

Synopsis

+

#include <sched.h> +

+

int sched_yield(void); +

+

Description

+

The sched_yield function shall force the running thread to +relinquish the processor until it again becomes the head of its +thread list. It takes no arguments. +

+

Return Value

+

The sched_yield function shall return 0 if it completes +successfully; otherwise, it shall return a value of -1 and set errno +to indicate the error. +

+

Errors

+

No errors are defined. +

+

The following sections are informative. +

+

Examples

+

None. +

+

Application Usage

+

None. +

+

Rationale

+

None. +

+

Future Directions

+

None. +

+

See Also

+

The Base Definitions volume of IEEE Std 1003.1-2001, +<sched.h> +

+

Copyright

+

Portions of this text are reprinted and reproduced in electronic +form from IEEE Std 1003.1, 2003 Edition, Standard for Information +Technology -- Portable Operating System Interface (POSIX), The Open +Group Base Specifications Issue 6, Copyright (C) 2001-2003 by the +Institute of Electrical and Electronics Engineers, Inc and The Open +Group. In the event of any discrepancy between this version and the +original IEEE and The Open Group Standard, the original IEEE and The +Open Group Standard is the referee document. The original Standard +can be obtained online at http://www.opengroup.org/unix/online.html +. +

+
+

Table of Contents

+ + + diff --git a/pthreads/manual/sem_init.html b/pthreads/manual/sem_init.html new file mode 100644 index 000000000..80e0580dc --- /dev/null +++ b/pthreads/manual/sem_init.html @@ -0,0 +1,200 @@ + + + + + SEMAPHORES(3) manual page + + + + + + + +

POSIX Threads for Windows – REFERENCE - Pthreads-w32

+

Reference Index

+

Table of Contents

+

Name

+

sem_init, sem_wait, sem_trywait, sem_post, sem_getvalue, +sem_destroy - operations on semaphores +

+

Synopsis

+

#include <semaphore.h> +

+

int sem_init(sem_t *sem, int pshared, +unsigned int value); +

+

int sem_wait(sem_t * sem); +

+

int sem_timedwait(sem_t * sem, const struct +timespec *abstime); +

+

int sem_trywait(sem_t * sem); +

+

int sem_post(sem_t * sem); +

+

int sem_post_multiple(sem_t * sem, int +number); +

+

int sem_getvalue(sem_t * sem, int * sval); +

+

int sem_destroy(sem_t * sem); +

+

Description

+

Semaphores are counters for resources shared between threads. The +basic operations on semaphores are: increment the counter atomically, +and wait until the counter is non-null and decrement it atomically. +

+

sem_init initializes the semaphore object pointed to by +sem. The count associated with the semaphore is set initially +to value. The pshared argument indicates whether the +semaphore is local to the current process ( pshared is zero) +or is to be shared between several processes ( pshared is not +zero).

+

Pthreads-w32 currently does not support process-shared +semaphores, thus sem_init always returns with error EPERM +if pshared is not zero. +

+

sem_wait atomically decrements sem's count if it is +greater than 0 and returns immediately or it suspends the calling +thread until it can resume following a call to sem_post or +sem_post_multiple.

+

sem_timedwait atomically decrements sem's count if +it is greater than 0 and returns immediately, or it suspends the +calling thread. If abstime time arrives before the thread can +resume following a call to sem_post or sem_post_multiple, +then sem_timedwait returns with a return code of -1 after +having set errno to ETIMEDOUT. If the call can return +without suspending then abstime is not checked.

+

sem_trywait atomically decrements sem's count if it +is greater than 0 and returns immediately, or it returns immediately +with a return code of -1 after having set errno to EAGAIN. +sem_trywait never blocks.

+

sem_post either releases one thread if there are any +waiting on sem, or it atomically increments sem's +count.

+

sem_post_multiple either releases multiple threads if there +are any waiting on sem and/or it atomically increases sem's +count. If there are currently n waiters, where n the +largest number less than or equal to number, then n +waiters are released and sem's count is incremented by number +minus n.

+

sem_getvalue stores in the location pointed to by sval +the current count of the semaphore sem. In the Pthreads-w32 +implementation: if the value returned in sval is greater than +or equal to 0 it was the sem's count at some point during the +call to sem_getvalue. If the value returned in sval is +less than 0 then it's absolute value represents the number of threads +waiting on sem at some point during the call to sem_getvalue. +POSIX does not require an implementation of sem_getvalue +to return a value in sval that is less than 0, but if it does +then it's absolute value must represent the number of waiters.

+

sem_destroy destroys a semaphore object, freeing the +resources it might hold. No threads should be waiting on the +semaphore at the time sem_destroy is called.

+

Cancellation

+

sem_wait and sem_timedwait are cancellation points. +

+

Async-signal Safety

+

These routines are not async-cancel safe.

+

Return Value

+

All semaphore functions return 0 on success, or -1 on error in +which case they write an error code in errno. +

+

Errors

+

The sem_init function sets errno to the following +codes on error: +

+
+
+
EINVAL +
+ value exceeds the maximal counter value SEM_VALUE_MAX +
+ ENOSYS +
+
+
+pshared is not zero +
+

The sem_timedwait function sets errno to the +following error code on error: +

+
+
+
ETIMEDOUT +
+
+
+if abstime arrives before the waiting thread can resume +following a call to sem_post or sem_post_multiple. +
+

The sem_trywait function sets errno to the following +error code on error: +

+
+
+
EAGAIN +
+
+
+if the semaphore count is currently 0 +
+

The sem_post and sem_post_multiple functions set +errno to the following error code on error: +

+
+
+
ERANGE +
+ if after incrementing, the semaphore count would exceed + SEM_VALUE_MAX (the semaphore count is left unchanged in this + case) +
+
+

+The sem_destroy function sets errno to the following +error code on error: +

+
+
+
EBUSY +
+ if some threads are currently blocked waiting on the semaphore. +
+
+

+Author

+

Xavier Leroy <Xavier.Leroy@inria.fr> +

+

Modified by Ross Johnson for use with Pthreads-w32.

+

See Also

+

pthread_mutex_init(3) +, pthread_cond_init(3) , +pthread_cancel(3) . +

+
+

Table of Contents

+ + + \ No newline at end of file -- cgit v1.2.3