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                          
======================================================================


Reply via email to