Re: [RFC] Add pthread_cond_timedwaitonclock_np

["Carlos O'Donell" <carlos at redhat dot com>]

On 07/27/2015 03:00 PM, Mike Crowe wrote:
>> New APIs also need documentation in the glibc manual.
> 
> I'm having some trouble with the safety section. pthread_cond_timedwait
> isn't documented in the glibc manual since it is a POSIX function.
> 
> The pthread_cond_timedwait man page tells me that pthread_cond_timedwait is
> MT-Safe but it's presumably neither AC-Safe nor AS-Safe. I'm not sure what to put in
> the asunsafe and acunsafe reasons. Cut and paste gave me:

Yes, the pthread_* functions are by definition MT-safe.

>  @safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@asulock}}
> 
> is this correct?

Almost.

@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock}}

Note: Use of "aculock" for acunsafe. Here it matters that the lock is lost
      not that we deadlock.

With suggested source level comments like this:

@c If exactly the same function with arguments is called from a signal
@c handler that interrupts between the mutex unlock and sleep then it
@c will unlock the mutex twice resulting in undefined behaviour. Keep
@c in mind that the unlock and sleep are only atomic with respect to other
@c threads (really a happens-after relationship for pthread_cond_broadcast
@c and pthread_cond_signal).
@c In the AC case we would cancel the thread and the mutex would remain
@c locked and we can't recover from that.
 
> (I also plan to submit changes to the pthread_cond_timedwait man page.)
> 
> Thanks for the review.

This does not constitute a full review, and I think a lot more people need
to review this before we have consensus over a new API like this.

Cheers,
Carlos.