home *** CD-ROM | disk | FTP | other *** search
/ Game Programming - All in One (3rd Edition) / game_prog_all_in_one_3rd_ed.iso / pthread / docs / README.NONPORTABLE < prev    next >
Encoding:
Text File  |  2003-09-18  |  10.8 KB  |  259 lines
  1. This file documents non-portable functions and other issues.
  2.  
  3. Non-portable functions included in pthreads-win32
  4. -------------------------------------------------
  5.  
  6. void *
  7. pthread_timechange_handler_np(void *)
  8.  
  9.         To improve tolerance against operator or time service
  10.         initiated system clock changes.
  11.  
  12.         This routine can be called by an application when it
  13.         receives a WM_TIMECHANGE message from the system. At
  14.         present it broadcasts all condition variables so that
  15.         waiting threads can wake up and re-evaluate their
  16.         conditions and restart their timed waits if required.
  17.  
  18.         It has the same return type and argument type as a
  19.         thread routine so that it may be called directly
  20.         through pthread_create() for asynchronicity.
  21.  
  22.         Parameters
  23.  
  24.         Although a parameter must be supplied, it is ignored.
  25.         The value NULL can be used.
  26.  
  27.         Return values
  28.  
  29.         It can return an error EAGAIN to indicate that not
  30.         all condition variables were broadcast for some reason.
  31.         Otherwise, 0 is returned.
  32.  
  33.         If run as a thread, the return value is returned
  34.         through pthread_join(), otherwise directly.
  35.  
  36.         The return value should be cast to an integer.
  37.  
  38.  
  39. HANDLE
  40. pthread_getw32threadhandle_np(pthread_t thread);
  41.  
  42.     Returns the win32 thread handle that the POSIX
  43.     thread "thread" is running as.
  44.  
  45.     Applications can use the win32 handle to set
  46.     win32 specific attributes of the thread.
  47.  
  48.  
  49. int
  50. pthread_mutexattr_setkind_np(pthread_mutexattr_t * attr, int kind)
  51.  
  52. int
  53. pthread_mutexattr_getkind_np(pthread_mutexattr_t * attr, int *kind)
  54.  
  55.         These two routines are included for Linux compatibility
  56.         and are direct equivalents to the standard routines
  57.                 pthread_mutexattr_settype
  58.                 pthread_mutexattr_gettype
  59.  
  60.         pthread_mutexattr_setkind_np accepts the following
  61.         mutex kinds:
  62.                 PTHREAD_MUTEX_FAST_NP
  63.                 PTHREAD_MUTEX_ERRORCHECK_NP
  64.                 PTHREAD_MUTEX_RECURSIVE_NP
  65.  
  66.         These are really just equivalent to (respectively):
  67.                 PTHREAD_MUTEX_NORMAL
  68.                 PTHREAD_MUTEX_ERRORCHECK
  69.                 PTHREAD_MUTEX_RECURSIVE
  70.  
  71. int
  72. pthread_delay_np (const struct timespec *interval);
  73.  
  74.         This routine causes a thread to delay execution for a specific period of time.
  75.         This period ends at the current time plus the specified interval. The routine
  76.         will not return before the end of the period is reached, but may return an
  77.         arbitrary amount of time after the period has gone by. This can be due to
  78.         system load, thread priorities, and system timer granularity.
  79.  
  80.         Specifying an interval of zero (0) seconds and zero (0) nanoseconds is
  81.         allowed and can be used to force the thread to give up the processor or to
  82.         deliver a pending cancelation request.
  83.  
  84.         This routine is a cancelation point.
  85.  
  86.         The timespec structure contains the following two fields:
  87.  
  88.                 tv_sec is an integer number of seconds.
  89.                 tv_nsec is an integer number of nanoseconds. 
  90.  
  91.         Return Values
  92.  
  93.         If an error condition occurs, this routine returns an integer value
  94.         indicating the type of error. Possible return values are as follows:
  95.  
  96.         0          Successful completion. 
  97.         [EINVAL]   The value specified by interval is invalid. 
  98.  
  99. int
  100. pthread_num_processors_np
  101.  
  102.         This routine (found on HPUX systems) returns the number of processors
  103.         in the system. This implementation actually returns the number of
  104.         processors available to the process, which can be a lower number
  105.         than the system's number, depending on the process's affinity mask.
  106.  
  107. BOOL
  108. pthread_win32_process_attach_np (void);
  109.  
  110. BOOL
  111. pthread_win32_process_detach_np (void);
  112.  
  113. BOOL
  114. pthread_win32_thread_attach_np (void);
  115.  
  116. BOOL
  117. pthread_win32_thread_detach_np (void);
  118.  
  119.     These functions contain the code normally run via dllMain
  120.     when the library is used as a dll but which need to be
  121.     called explicitly by an application when the library
  122.     is statically linked.
  123.  
  124.     You will need to call pthread_win32_process_attach_np() before
  125.     you can call any pthread routines when statically linking.
  126.     You should call pthread_win32_process_detach_np() before
  127.     exiting your application to clean up.
  128.  
  129.     pthread_win32_thread_attach_np() is currently a no-op, but
  130.     pthread_win32_thread_detach_np() is needed to clean up
  131.     the implicit pthread handle that is allocated to a Win32 thread if
  132.     it calls certain pthreads routines. Call this routine when the
  133.     Win32 thread exits.
  134.  
  135.     These functions invariably return TRUE except for
  136.     pthread_win32_process_attach_np() which will return FALSE
  137.     if pthreads-win32 initialisation fails.
  138.  
  139. int
  140. pthreadCancelableWait (HANDLE waitHandle);
  141.  
  142. int
  143. pthreadCancelableTimedWait (HANDLE waitHandle, DWORD timeout);
  144.  
  145.     These two functions provide hooks into the pthread_cancel
  146.     mechanism that will allow you to wait on a Windows handle
  147.     and make it a cancellation point. Both functions block
  148.     until either the given w32 handle is signaled, or
  149.     pthread_cancel has been called. It is implemented using
  150.     WaitForMultipleObjects on 'waitHandle' and a manually
  151.     reset w32 event used to implement pthread_cancel.
  152.  
  153.  
  154. Non-portable issues
  155. -------------------
  156.  
  157. Thread priority
  158.  
  159.     POSIX defines a single contiguous range of numbers that determine a
  160.     thread's priority. Win32 defines priority classes and priority
  161.     levels relative to these classes. Classes are simply priority base
  162.     levels that the defined priority levels are relative to such that,
  163.     changing a process's priority class will change the priority of all
  164.     of it's threads, while the threads retain the same relativity to each
  165.     other.
  166.  
  167.     A Win32 system defines a single contiguous monotonic range of values
  168.     that define system priority levels, just like POSIX. However, Win32
  169.     restricts individual threads to a subset of this range on a
  170.     per-process basis.
  171.  
  172.     The following table shows the base priority levels for combinations
  173.     of priority class and priority value in Win32.
  174.     
  175.      Process Priority Class               Thread Priority Level
  176.      -----------------------------------------------------------------
  177.      1 IDLE_PRIORITY_CLASS                THREAD_PRIORITY_IDLE
  178.      1 BELOW_NORMAL_PRIORITY_CLASS        THREAD_PRIORITY_IDLE
  179.      1 NORMAL_PRIORITY_CLASS              THREAD_PRIORITY_IDLE
  180.      1 ABOVE_NORMAL_PRIORITY_CLASS        THREAD_PRIORITY_IDLE
  181.      1 HIGH_PRIORITY_CLASS                THREAD_PRIORITY_IDLE
  182.      2 IDLE_PRIORITY_CLASS                THREAD_PRIORITY_LOWEST
  183.      3 IDLE_PRIORITY_CLASS                THREAD_PRIORITY_BELOW_NORMAL
  184.      4 IDLE_PRIORITY_CLASS                THREAD_PRIORITY_NORMAL
  185.      4 BELOW_NORMAL_PRIORITY_CLASS        THREAD_PRIORITY_LOWEST
  186.      5 IDLE_PRIORITY_CLASS                THREAD_PRIORITY_ABOVE_NORMAL
  187.      5 BELOW_NORMAL_PRIORITY_CLASS        THREAD_PRIORITY_BELOW_NORMAL
  188.      5 Background NORMAL_PRIORITY_CLASS   THREAD_PRIORITY_LOWEST
  189.      6 IDLE_PRIORITY_CLASS                THREAD_PRIORITY_HIGHEST
  190.      6 BELOW_NORMAL_PRIORITY_CLASS        THREAD_PRIORITY_NORMAL
  191.      6 Background NORMAL_PRIORITY_CLASS   THREAD_PRIORITY_BELOW_NORMAL
  192.      7 BELOW_NORMAL_PRIORITY_CLASS        THREAD_PRIORITY_ABOVE_NORMAL
  193.      7 Background NORMAL_PRIORITY_CLASS   THREAD_PRIORITY_NORMAL
  194.      7 Foreground NORMAL_PRIORITY_CLASS   THREAD_PRIORITY_LOWEST
  195.       8 BELOW_NORMAL_PRIORITY_CLASS        THREAD_PRIORITY_HIGHEST
  196.      8 NORMAL_PRIORITY_CLASS              THREAD_PRIORITY_ABOVE_NORMAL
  197.      8 Foreground NORMAL_PRIORITY_CLASS   THREAD_PRIORITY_BELOW_NORMAL
  198.      8 ABOVE_NORMAL_PRIORITY_CLASS        THREAD_PRIORITY_LOWEST
  199.      9 NORMAL_PRIORITY_CLASS              THREAD_PRIORITY_HIGHEST
  200.      9 Foreground NORMAL_PRIORITY_CLASS   THREAD_PRIORITY_NORMAL
  201.      9 ABOVE_NORMAL_PRIORITY_CLASS        THREAD_PRIORITY_BELOW_NORMAL
  202.     10 Foreground NORMAL_PRIORITY_CLASS   THREAD_PRIORITY_ABOVE_NORMAL
  203.     10 ABOVE_NORMAL_PRIORITY_CLASS        THREAD_PRIORITY_NORMAL
  204.     11 Foreground NORMAL_PRIORITY_CLASS   THREAD_PRIORITY_HIGHEST
  205.     11 ABOVE_NORMAL_PRIORITY_CLASS        THREAD_PRIORITY_ABOVE_NORMAL
  206.     11 HIGH_PRIORITY_CLASS                THREAD_PRIORITY_LOWEST
  207.     12 ABOVE_NORMAL_PRIORITY_CLASS        THREAD_PRIORITY_HIGHEST
  208.     12 HIGH_PRIORITY_CLASS                THREAD_PRIORITY_BELOW_NORMAL
  209.     13 HIGH_PRIORITY_CLASS                THREAD_PRIORITY_NORMAL
  210.     14 HIGH_PRIORITY_CLASS                THREAD_PRIORITY_ABOVE_NORMAL
  211.     15 HIGH_PRIORITY_CLASS                THREAD_PRIORITY_HIGHEST
  212.     15 HIGH_PRIORITY_CLASS                THREAD_PRIORITY_TIME_CRITICAL
  213.     15 IDLE_PRIORITY_CLASS                THREAD_PRIORITY_TIME_CRITICAL
  214.     15 BELOW_NORMAL_PRIORITY_CLASS        THREAD_PRIORITY_TIME_CRITICAL
  215.     15 NORMAL_PRIORITY_CLASS              THREAD_PRIORITY_TIME_CRITICAL
  216.     15 ABOVE_NORMAL_PRIORITY_CLASS        THREAD_PRIORITY_TIME_CRITICAL
  217.     16 REALTIME_PRIORITY_CLASS            THREAD_PRIORITY_IDLE
  218.     17 REALTIME_PRIORITY_CLASS            -7
  219.     18 REALTIME_PRIORITY_CLASS            -6
  220.     19 REALTIME_PRIORITY_CLASS            -5
  221.     20 REALTIME_PRIORITY_CLASS            -4
  222.     21 REALTIME_PRIORITY_CLASS            -3
  223.     22 REALTIME_PRIORITY_CLASS            THREAD_PRIORITY_LOWEST
  224.     23 REALTIME_PRIORITY_CLASS            THREAD_PRIORITY_BELOW_NORMAL
  225.     24 REALTIME_PRIORITY_CLASS            THREAD_PRIORITY_NORMAL
  226.     25 REALTIME_PRIORITY_CLASS            THREAD_PRIORITY_ABOVE_NORMAL
  227.     26 REALTIME_PRIORITY_CLASS            THREAD_PRIORITY_HIGHEST
  228.     27 REALTIME_PRIORITY_CLASS             3
  229.     28 REALTIME_PRIORITY_CLASS             4
  230.     29 REALTIME_PRIORITY_CLASS             5
  231.     30 REALTIME_PRIORITY_CLASS             6
  232.     31 REALTIME_PRIORITY_CLASS            THREAD_PRIORITY_TIME_CRITICAL
  233.     
  234.     Windows NT:  Values -7, -6, -5, -4, -3, 3, 4, 5, and 6 are not supported.
  235.  
  236.  
  237.     As you can see, the real priority levels available to any individual
  238.     Win32 thread are non-contiguous.
  239.  
  240.     An application using pthreads-win32 should not make assumptions about
  241.     the numbers used to represent thread priority levels, except that they
  242.     are monotonic between the values returned by sched_get_priority_min()
  243.     and sched_get_priority_max(). E.g. Windows 95, 98, NT, 2000, XP make
  244.     available a non-contiguous range of numbers between -15 and 15, while
  245.     at least one version of WinCE (3.0) defines the minimum priority
  246.     (THREAD_PRIORITY_LOWEST) as 5, and the maximum priority
  247.     (THREAD_PRIORITY_HIGHEST) as 1.
  248.  
  249.     Internally, pthreads-win32 maps any priority levels between
  250.     THREAD_PRIORITY_IDLE and THREAD_PRIORITY_LOWEST to THREAD_PRIORITY_LOWEST,
  251.     or between THREAD_PRIORITY_TIME_CRITICAL and THREAD_PRIORITY_HIGHEST to
  252.     THREAD_PRIORITY_HIGHEST. Currently, this also applies to
  253.     REALTIME_PRIORITY_CLASSi even if levels -7, -6, -5, -4, -3, 3, 4, 5, and 6
  254.     are supported.
  255.  
  256.     If it wishes, a Win32 application using pthreads-win32 can use the Win32
  257.     defined priority macros THREAD_PRIORITY_IDLE through
  258.     THREAD_PRIORITY_TIME_CRITICAL.
  259.