A NOTE has been added to this issue. ====================================================================== http://austingroupbugs.net/view.php?id=1216 ====================================================================== Reported By: mikecrowe Assigned To: ajosey ====================================================================== Project: 1003.1(2016)/Issue7+TC2 Issue ID: 1216 Category: System Interfaces Type: Enhancement Request Severity: Comment Priority: normal Status: Under Review Name: Mike Crowe Organization: User Reference: Section: pthread Page Number: 0 Line Number: 0 Interp Status: --- Final Accepted Text: ====================================================================== Date Submitted: 2018-11-26 18:53 UTC Last Modified: 2019-05-07 12:09 UTC ====================================================================== Summary: Adding clockid parameter to functions that accept absolute struct timespec timeouts ====================================================================== Relationships ID Summary ---------------------------------------------------------------------- related to 0001164 Correct C++11 std::condition_variable r... ======================================================================
---------------------------------------------------------------------- (0004387) mikecrowe (reporter) - 2019-05-07 12:09 http://austingroupbugs.net/view.php?id=1216#c4387 ---------------------------------------------------------------------- Suggested wording updates for all new functions: ** General *** Insert after p3622:123506 It was later found necessary to add variants of almost all interfaces that accept absolute timeouts that allow the clock to be specified. This is because, despite the claim in the previous paragraph, it is not possible to safely use a CLOCK_REALTIME absolute timeout even to prevent errors when the system clock is warped by a potentially large amount. A "safety timeout" of a minute on a call pthread_mutex_timedlock() could actually mean no timeout at all if the system clock is warped forwards immediately prior to the call. This functionality is provided by the new "clockwait" variants of the existing "timedwait" functions that accept an extra clockid_t parameter to indicate the clock to be used for the wait. The clock parameter is passed rather than using attributes as previously for pthread_cond_timedwait in order to allow ISOXXX C++11 and later to be implemented correctly. C++ requires that the clock to use for the wait is not known until the time of the wait call, so it cannot be supplied during creation. The new functions are sem_clockwait(), pthread_cond_clockwait(), pthread_mutex_clocklock(), pthread_mutex_clockrdlock() and pthread_mutex_clockwrlock(). It is expected that mq_clockreceive() and mq_clocksend() functions will be added in a future version of this standard too. ** pthread_cond_clockwait *** Add to lists at lines - p111:3070 - p318:10833 - p518:18119 - p1604:52281 - p1612:52599 - p1615:52710 - p1695:55292 - p3641:124395 - p3793:130171 pthread_cond_clockwait() *** After line p316:10727 insert: int pthread_cond_clockwait(pthread_cond_t *restrict, pthread_mutex_t *restrict, clockid_t, const struct timespec *restrict); *** After line p514:17967 insert: It calls pthread_cond_clockwait() with m as the mutex argument and the call returns zero or certain error numbers (see pthread_cond_clockwait()). *** After line p514:17972 insert: It blocks in a call to pthread_cond_clockwait() with m as the mutex argument. *** Line p900:30449 Change "and pthread_cond_timedwait" to ", pthread_cond_timedwait and pthread_cond_clockwait". *** Lines p1610:52513,52515,52519, p1611:52582, p3643:124488 Change "or pthread_cond_timedwait" to ", pthread_cond_timedwait or pthread_cond_clockwait". *** After line p1617:52743 insert: int pthread_cond_clockwait(pthread_cond_t *restrict cond, pthread_mutex_t *restrict mutex, clockid_t clock_id, const struct timespec *restrict abstime); *** Lines p1617:52747,52762,52763,52766,52781,52783, p1618:52786, p1619:52848, p1620:52882 Add ", pthread_cond_clockwait()" after "pthread_cond_timedwait()" *** After line p1618:52797 insert: The pthread_cond_clockwait() function shall be equivalent to pthread_cond_timedwait(), except that the absolute time specified by abstime is measured against the clock indicated by clock_id rather than the clock specified in the condition variable's clock attribute. All implementations shall support passing CLOCK_REALTIME to pthread_cond_clockwait() as the clock_id parameter. If the Monotonic Clock option is supported, all implementations shall support a clock_id of CLOCK_MONOTONIC. *** Line p1618:52822: Change to "The pthread_cond_timedwait() and pthread_cond_clockwait() functions shall fail if:" *** Line p1618:52823, p1619:52850: Change "pthread_cond_timedwait()" to "pthread_cond_timedwait() or pthread_cond_clockwait()" *** Line p1618:52825: Add "or the clock_id parameter passed to pthread_cond_clockwait is invalid or not supported." *** Insert after line p1620:52879: Choice of clock Care should be taken to decide which clock is most appropriate when waiting with a timeout. The system clock, CLOCK_REALTIME, as used by default with pthread_cond_timedwait() may be subject to jumps forwards and backwards in order to correct it against actual time. CLOCK_MONOTONIC is guaranteed not to jump backwards and must also advance in real time, so using it via pthread_cond_clockwait() or pthread_condattr_setclock() may be more appropriate. *** Line p1621:52943: Replace CLOCK_REALTIME with CLOCK_MONOTONIC *** Line p1621:52947: Replace line with: rc = pthread_cond_clockwait(&t.cond, &t.mn, CLOCK_MONOTONIC, &ts); *** After line line p1622:52956 insert: Using CLOCK_MONOTONIC rather than CLOCK_REALTIME means that the timeout is not influenced by the system clock being changed. *** After line p1626:53084 insert: Note that the /clock/ attribute shall have no effect on the pthread_cond_clockwait() function. *** Lines p1661:54147, p1662:54186, p1665:54321, p1694:55282: After "pthread_cond_timedwait()" insert ", pthread_cond_clockwait()". *** Line p3621:123502: Delete remainder of paragraph starting with "This capability has not been added to other functions...". Insert in its place: For condition variables, this capability is also available by passing CLOCK_MONOTONIC to the pthread_cond_clockwait() function. Similarly, CLOCK_MONOTONIC can be specified when calling sem_clockwait, pthread_mutex_clocklock, pthread_rwlock_clockrdlock and pthread_rwlock_clockwrlock. *** After line p3622:123535: Subsequently, it was discovered that using a particular clock for the timeout was desired by some users. In particular, the ISO C++11 standard requires the clock to be a property of the wait for its std::condtion_variable and std::timed_mutex. This led to the addition of sem_clockwait(), pthread_mutex_clockwait(), pthread_cond_clockwait(), pthread_rwlock_clockrdlock() and pthread_rwlock_clockwrlock() functions that accepted a clock parameter to measure their absolute timeout against. The addition of the corresponding mq_clockreceive and mq_clocksend may be considered in the future. ** sem_clockwait *** Add to list at p111:3069 sem_clockwait *** After line p329:11164 insert int sem_clockwait(sem_t *restrict, clockid_t clock_id, const struct timespec *restrict) *** Add to list at p427:14548 sem_clockwait *** Add to list at p517:18120 sem_clockwait *** Add to lists at p681:23337,23362 sem_clockwait *** Add to lists at p1849:59892: sem_clockwait *** Add to lists at p1851:59918,59922,59924,59946 sem_clockwait *** Add to list at p1853:59972 sem_clockwait *** Add to list at p1855:60057 sem_clockwait *** Add to lists at p1856:60113,60121 sem_clockwait *** p1858:60140 Add sem_clockwait to NAME *** After p1858:60145 insert int sem_clockwait(sem_t *restrict, clockid_t clock_id, const struct timespec *restrict abstime) *** After p1858:60147 "sem_timedwait", insert and sem_clockwait *** Before p1858:60155 insert: For sem_timedwait, *** On p1858:60156 insert new sentence after sentence end: For sem_clockwait, the timeout shall be measured against the clock represented by the clock_id parameter. *** p1858:60162, p1858:60167 replace "function" with and sem_clockwait() functions *** Append to p1858:p60170 Alternatively the sem_clockwait() function was passed an invalid or unsupported clock_id. *** p1860:60230 Replace "CLOCK_REALTIME" with "CLOCK_MONOTONIC". *** p1860:60235 Replace "sem_timedwait" with "sem_clockwait". *** p1860:60236 Replace "sem_timedwait(&sem, &ts)" with "sem_clockwait(&sem, CLOCK_MONOTONIC, &ts)" *** p1860:60241,60243,60245: Replace "sem_timedwait" with "sem_clockwait". *** Add to list p1862:60307 sem_clockwait *** Add to list p3563:120877 sem_clockwait *** Add to list p3770:129389,129400 sem_clockwait *** Add to list p3792:130143 sem_clockwait ** pthread_mutex_clocklock *** Add to list p111:3075 pthread_mutex_clocklock *** Insert after p317:10761 int pthread_mutex_clocklock(pthread_mutex_t *restrict, clockid_t clock_id, const struct timespec *restrict); *** Add to list p318:10838 pthread_mutex_clocklock *** Add to list p427:14547: pthread_mutex_clocklock *** Insert after p514:17962: It calls pthread_mutex_clocklock( ) with m as the mutex argument and the call returns zero or [EOWNERDEAD]. *** Add to list p681:23337: pthread_mutex_clocklock *** Add to list p1665:54333: pthread_mutex_clocklock *** Add to list p1668:54417: pthread_mutex_clocklock *** Add to list p1673:54574: pthread_mutex_clocklock *** In line p1676:54616, insert pthread_mutex_clocklock *** After line p1676:54621, insert int pthread_mutex_clocklock(pthread_mutex_t *restrict mutex, clockid_t clock_id, const struct timespec *restrict abstime); *** Begin line p1676:54623 with The pthread_mutex_timedlock() and pthread_mutex_clocklock() functions shall lock... *** Begin line p1676:54631 with For pthread_mutex_timedlock, the timeout shall... *** On line p1676:54632, insert new sentence after sentence end: For pthread_mutex_clocklock, the timeout shall be measured against the clock represented by the clock_id parameter. *** On line p1676:54642 and p1676:54644 replace "pthread_mutex_timedlock()" with pthread_mutex_timedlock() or pthread_mutex_clocklock() *** On line p1676:54653 and p1676:54656 replace "function" with and pthread_mutex_clocklock() functions *** Insert after p1677:54666 Alternatively the pthread_mutex_clocklock() function was passed an invalid or unsupported clock_id. *** On line p1677:54675 replace "function" with and pthread_mutex_clocklock() functions *** Add to list at p3563:120888 pthread_mutex_clocklock *** Add to list at p3770:129399 pthread_mutex_clocklock *** Add to list at p3793:130175 pthread_mutex_clocklock ** pthread_rwlock_clockrdlock & pthread_rwlock_clockwrlock *** Add to list at p111:3072 pthread_rwlock_clockwrlock, pthread_rwlock_clockrdlock *** Insert after line p317:10787 int pthread_rwlock_clockrdlock(pthread_rwlock_t *restrict, clockid_t clock_id, const struct timespec *restrict); *** Insert after line p317:10789 int pthread_rwlock_clockwrlock(pthread_rwlock_t *restrict, clockid_t clock_id, const struct timespec *restrict); *** Add to list at p318:10841 pthread_rwlock_clockwrlock(), pthread_rwlock_clockrdlock() *** Add to list at p319:10842 pthread_rwlock_clockwrlock(), pthread_rwlock_clockrdlock() *** Add to list at p427:14548 pthread_rwlock_clockwrlock(), pthread_rwlock_clockrdlock() *** Add to list at p519:18175 pthread_rwlock_clockwrlock(), pthread_rwlock_clockrdlock() *** Add to list at p1705:55499 pthread_rwlock_clockwrlock(), pthread_rwlock_clockrdlock() *** Add to list at p1708:55600 pthread_rwlock_clockwrlock(), pthread_rwlock_clockrdlock() *** Add to line p1710:55625 pthread_rwlock_clockrdlock *** Insert after line p1710:55630 int pthread_rwlock_clockrdlock(pthread_rwlock_t *restrict, clockid_t clock_id, const struct timespec *restrict); *** Replace p1710:55632 "function" with and pthread_rwlock_clockrdlock() functions *** Insert at beginning of p1710:55639 For pthread_rwlock_timedrdlock(), *** On line p1710:55640, insert new sentence after sentence end For pthread_rwlock_clockrdclock(), the timeout shall be measured against the clock represented by the clock_id parameter. *** On line p1710:55645, after "pthread_rwlock_timedrdlock" insert or pthread_rwlock_clockrdlock *** On line p1710:55650, replace "function" with and pthread_rwlock_clockrdlock functions *** On line p1710:55654, replace "function" with and pthread_rwlock_clockrdlock functions *** On line p1710:55656, replace "function" with and pthread_rwlock_clockrdlock functions *** On line p1710:55661 add Alternatively, the pthread_rwlock_clockrdlock() function was passed an invalid or unsupported clock_id. *** On line p1711:55671, after "pthread_rwlock_timedrdlock()" add or pthread_rwlock_clockrdlock() *** Add to list at p1711:55676: pthread_rwlock_clockwrlock() *** Add to line p1712:55688 pthread_rwlock_clockwrlock *** Insert after line p1712:55693 int pthread_rwlock_clockwrlock(pthread_rwlock_t *restrict rwlock, clockid_t clock_id, const struct timespec *restrict abstime); *** Replace p1712:55695 "function" with and pthread_rwlock_clockwrlock() functions *** Insert at beginning of p1712:55702 For pthread_rwlock_timedrdlock, *** On line p1712:55703, insert new sentence after sentence end For pthread_rwlock_clockwrclock(), the timeout shall be measured against the clock represented by the clock_id parameter. *** On line p1712:55708, after "pthread_rwlock_timedwrlock" insert or pthread_rwlock_clockwrlock *** On line p1712:55713 replace function with and pthread_rwlock_clockwrlock functions *** On line p1712:55717 replace function with and pthread_rwlock_clockwrlock functions *** On line p1712:55719 replace function with and pthread_rwlock_clockwrlock functions *** On line p1712:55723 add Alternatively, the pthread_rwlock_clockwrlock() function was passed an invalid or unsupported clock_id. *** On line p1713:55732, after "pthread_rwlock_timedwrlock()" add or pthread_rwlock_clockwrlock() *** Add to line p1713:55737 pthread_rwlock_clockrdlock *** Add to list on p1716:55801 pthread_rwlock_clockwrlock(), pthread_rwlock_clockrdlock() *** Add to list on p1718:55863 pthread_rwlock_clockwrlock(), pthread_rwlock_clockrdlock() *** Add to list on p3563:120899 pthread_rwlock_clockwrlock(), pthread_rwlock_clockrdlock() *** Add to list on p3770:129399 pthread_rwlock_clockwrlock(), pthread_rwlock_clockrdlock() *** Add to list on p3792:130137 pthread_rwlock_clockwrlock(), pthread_rwlock_clockrdlock() Issue History Date Modified Username Field Change ====================================================================== 2018-11-26 18:53 mikecrowe New Issue 2018-11-26 18:53 mikecrowe Status New => Under Review 2018-11-26 18:53 mikecrowe Assigned To => ajosey 2018-11-26 18:53 mikecrowe Name => Mike Crowe 2018-11-26 18:53 mikecrowe Section => pthread 2018-11-26 18:53 mikecrowe Page Number => 0 2018-11-26 18:53 mikecrowe Line Number => 0 2018-11-27 09:23 geoffclare Project 1003.1(2008)/Issue 7 => 1003.1(2016)/Issue7+TC2 2018-11-27 09:23 geoffclare Relationship added related to 0001164 2018-11-27 16:02 nick Note Added: 0004171 2019-01-07 21:26 mikecrowe Note Added: 0004196 2019-01-19 04:08 mikecrowe Note Added: 0004215 2019-03-06 13:17 mikecrowe Note Added: 0004276 2019-05-07 12:09 mikecrowe Note Added: 0004387 ======================================================================