Cleanup and fixes to thread priority management. Other minor changes.snap-2003-09-18

1 files changed, 258 insertions, 149 deletions

diff --git a/README.NONPORTABLE b/README.NONPORTABLE
index 0985097..12336bd 100644
--- a/README.NONPORTABLE
+++ b/README.NONPORTABLE
@@ -1,149 +1,258 @@
-Non-portable functions included in pthreads-win32
--------------------------------------------------
-
-void *
-pthread_timechange_handler_np(void *)
-
-        To improve tolerance against operator or time service
-        initiated system clock changes.
-
-        This routine 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.
-
-        It has the same return type and argument type as a
-        thread routine so that it may be called directly
-        through pthread_create() for asynchronicity.
-
-        Parameters
-
-        Although a parameter must be supplied, it is ignored.
-        The value NULL can be used.
-
-        Return values
-
-        It can return an error EAGAIN to indicate that not
-        all condition variables were broadcast for some reason.
-        Otherwise, 0 is returned.
-
-        If run as a thread, the return value is returned
-        through pthread_join(), otherwise directly.
-
-        The return value should be cast to an integer.
-
-
-HANDLE
-pthread_getw32threadhandle_np(pthread_t thread);
-
-	Returns the win32 thread handle that the POSIX
-	thread "thread" is running as.
-
-	Applications can use the win32 handle to set
-	win32 specific attributes of the thread.
-
-
-int
-pthread_mutexattr_setkind_np(pthread_mutexattr_t * attr, int kind)
-
-int
-pthread_mutexattr_getkind_np(pthread_mutexattr_t * attr, int *kind)
-
-        These two routines are included for Linux compatibility
-        and are direct equivalents to the standard routines
-                pthread_mutexattr_settype
-                pthread_mutexattr_gettype
-
-        pthread_mutexattr_setkind_np accepts the following
-        mutex kinds:
-                PTHREAD_MUTEX_FAST_NP
-                PTHREAD_MUTEX_ERRORCHECK_NP
-                PTHREAD_MUTEX_RECURSIVE_NP
-
-        These are really just equivalent to (respectively):
-                PTHREAD_MUTEX_NORMAL
-                PTHREAD_MUTEX_ERRORCHECK
-                PTHREAD_MUTEX_RECURSIVE
-
-int
-pthread_delay_np (const struct timespec *interval);
-
-        This routine causes a thread to delay execution for a specific period of time.
-        This period ends at the current time plus the specified interval. The routine
-        will not return before the end of the period is reached, but may return an
-        arbitrary amount of time after the period has gone by. This can be due to
-        system load, thread priorities, and system timer granularity.
-
-        Specifying an interval of zero (0) seconds and zero (0) nanoseconds is
-        allowed and can be used to force the thread to give up the processor or to
-        deliver a pending cancelation request.
-
-        This routine is a cancelation point.
-
-        The timespec structure contains the following two fields:
-
-                tv_sec is an integer number of seconds.
-                tv_nsec is an integer number of nanoseconds. 
-
-        Return Values
-
-        If an error condition occurs, this routine returns an integer value
-        indicating the type of error. Possible return values are as follows:
-
-        0          Successful completion. 
-        [EINVAL]   The value specified by interval is invalid. 
-
-int
-pthread_num_processors_np
-
-        This routine (found on HPUX systems) 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.
-
-BOOL
-pthread_win32_process_attach_np (void);
-
-BOOL
-pthread_win32_process_detach_np (void);
-
-BOOL
-pthread_win32_thread_attach_np (void);
-
-BOOL
-pthread_win32_thread_detach_np (void);
-
-	These functions contain the code normally run via dllMain
-	when the library is used as a dll but which need to be
-	called explicitly by an application when the library
-	is statically linked.
-
-	You will need to call pthread_win32_process_attach_np() before
-	you can call any pthread routines when statically linking.
-	You should call pthread_win32_process_detach_np() before
-	exiting your application to clean up.
-
-	pthread_win32_thread_attach_np() is currently a no-op, but
-	pthread_win32_thread_detach_np() is needed to clean up
-	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-win32 initialisation fails.
-
-int
-pthreadCancelableWait (HANDLE waitHandle);
-
-int
-pthreadCancelableTimedWait (HANDLE waitHandle, DWORD timeout);
-
-	These two functions provide hooks into the pthread_cancel
-	mechanism that will allow you to wait on a Windows handle
-	and make it a cancellation point. Both functions block
-	until either the given w32 handle is signaled, or
-	pthread_cancel has been called. It is implemented using
-	WaitForMultipleObjects on 'waitHandle' and a manually
-	reset w32 event used to implement pthread_cancel.
+This file documents non-portable functions and other issues.

+

+Non-portable functions included in pthreads-win32

+-------------------------------------------------

+

+void *

+pthread_timechange_handler_np(void *)

+

+        To improve tolerance against operator or time service

+        initiated system clock changes.

+

+        This routine 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.

+

+        It has the same return type and argument type as a

+        thread routine so that it may be called directly

+        through pthread_create() for asynchronicity.

+

+        Parameters

+

+        Although a parameter must be supplied, it is ignored.

+        The value NULL can be used.

+

+        Return values

+

+        It can return an error EAGAIN to indicate that not

+        all condition variables were broadcast for some reason.

+        Otherwise, 0 is returned.

+

+        If run as a thread, the return value is returned

+        through pthread_join(), otherwise directly.

+

+        The return value should be cast to an integer.

+

+

+HANDLE

+pthread_getw32threadhandle_np(pthread_t thread);

+

+	Returns the win32 thread handle that the POSIX

+	thread "thread" is running as.

+

+	Applications can use the win32 handle to set

+	win32 specific attributes of the thread.

+

+

+int

+pthread_mutexattr_setkind_np(pthread_mutexattr_t * attr, int kind)

+

+int

+pthread_mutexattr_getkind_np(pthread_mutexattr_t * attr, int *kind)

+

+        These two routines are included for Linux compatibility

+        and are direct equivalents to the standard routines

+                pthread_mutexattr_settype

+                pthread_mutexattr_gettype

+

+        pthread_mutexattr_setkind_np accepts the following

+        mutex kinds:

+                PTHREAD_MUTEX_FAST_NP

+                PTHREAD_MUTEX_ERRORCHECK_NP

+                PTHREAD_MUTEX_RECURSIVE_NP

+

+        These are really just equivalent to (respectively):

+                PTHREAD_MUTEX_NORMAL

+                PTHREAD_MUTEX_ERRORCHECK

+                PTHREAD_MUTEX_RECURSIVE

+

+int

+pthread_delay_np (const struct timespec *interval);

+

+        This routine causes a thread to delay execution for a specific period of time.

+        This period ends at the current time plus the specified interval. The routine

+        will not return before the end of the period is reached, but may return an

+        arbitrary amount of time after the period has gone by. This can be due to

+        system load, thread priorities, and system timer granularity.

+

+        Specifying an interval of zero (0) seconds and zero (0) nanoseconds is

+        allowed and can be used to force the thread to give up the processor or to

+        deliver a pending cancelation request.

+

+        This routine is a cancelation point.

+

+        The timespec structure contains the following two fields:

+

+                tv_sec is an integer number of seconds.

+                tv_nsec is an integer number of nanoseconds. 

+

+        Return Values

+

+        If an error condition occurs, this routine returns an integer value

+        indicating the type of error. Possible return values are as follows:

+

+        0          Successful completion. 

+        [EINVAL]   The value specified by interval is invalid. 

+

+int

+pthread_num_processors_np

+

+        This routine (found on HPUX systems) 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.

+

+BOOL

+pthread_win32_process_attach_np (void);

+

+BOOL

+pthread_win32_process_detach_np (void);

+

+BOOL

+pthread_win32_thread_attach_np (void);

+

+BOOL

+pthread_win32_thread_detach_np (void);

+

+	These functions contain the code normally run via dllMain

+	when the library is used as a dll but which need to be

+	called explicitly by an application when the library

+	is statically linked.

+

+	You will need to call pthread_win32_process_attach_np() before

+	you can call any pthread routines when statically linking.

+	You should call pthread_win32_process_detach_np() before

+	exiting your application to clean up.

+

+	pthread_win32_thread_attach_np() is currently a no-op, but

+	pthread_win32_thread_detach_np() is needed to clean up

+	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-win32 initialisation fails.

+

+int

+pthreadCancelableWait (HANDLE waitHandle);

+

+int

+pthreadCancelableTimedWait (HANDLE waitHandle, DWORD timeout);

+

+	These two functions provide hooks into the pthread_cancel

+	mechanism that will allow you to wait on a Windows handle

+	and make it a cancellation point. Both functions block

+	until either the given w32 handle is signaled, or

+	pthread_cancel has been called. It is implemented using

+	WaitForMultipleObjects on 'waitHandle' and a manually

+	reset w32 event used to implement pthread_cancel.

+

+

+Non-portable issues

+-------------------

+

+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-win32 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_CLASSi even if levels -7, -6, -5, -4, -3, 3, 4, 5, and 6

+	are supported.

+

+	If it wishes, a Win32 application using pthreads-win32 can use the Win32

+	defined priority macros THREAD_PRIORITY_IDLE through

+	THREAD_PRIORITY_TIME_CRITICAL.