nptl.BullOpenSource.Org

[tHeDoc]

POSIX

POSIX is a registered trademark from the IEEE. The following assertions are derived from copyrighted material. Original text and copyright information can be found at http://www.opengroup.org.

Here is what POSIX requires for this function:

1. pthread_cond_timedwait() causes the thread (which must own the mutex) to block on the conditionnal variable.
   
2. When inside the function, the thread releases the mutex before waiting for the conditionnal variable. Those two operations are atomic in the mean that no other thread can gain access to the mutex then signal (or broadcast) the condition without the blocked thread behaving as if this signal (or broadcast) had happened after it blocked on the conditionnal variable.
   
3. When the function returns successfully, everything is as if the thread had locked the mutex.
   
4. While a thread is blocked on a conditionnal variable, a dynamic binding exists between this conditionnal variable and the mutex which was the second argument. This dynamic binding stops existing when the last thread is unblocked. Even if the conditionnal variable can then be reused with another mutex, the thread which have been unblocked must still acquire the mutex they had associated with the conditionnal variable at call time.
   
5. This function is a cancelation point: when cancelability is PTHREAD_CANCEL_DEFERRED and a cancel request falls, the thread must relock the mutex before the first (if any) clean up handler is called.
   
6. When a cancel request unblocks the thread, it must not consume any pending condition signal request.
   
7. The function must return with an error when the system time is bigger than or equal to the abstime parameter, and the condition has not been signaled or broadcasted yet.
   
8. If the POSIX Clock Selection option is supported, the conditionnal variable must provide the information of which clock is used to measure abstime.
   
9. When the function fails because of a timeout, it must reacquire the mutex (as when it is successful)
   
10. When successful, the function must return 0.
    
11. When a timeout occurs, the function must return ETIMEDOUT
    
12. When the abstime parameter is invalid, the function must return EINVAL and the mutex state must not have changed during the call.
    
13. The function must not return EINTR.
    

[tHeDoc]

Conformance Status

• Assertion 1 is covered in the 1-1.c test in the PTS, but this test might report FAILED with the function being inside the POSIX scope (in case of a spurious wake up). Anyway, I think this assertion cannot be tested differently, and hope spurious wakeups won't happen there . The libc tst-cond3.c tests for this assertion for the pthread_cond_wait() routine.
  
• Assertion 2 is not tested yet. It will be tested in a stress test.
  
• Assertion 3 is partially tested in the 2-1.c test. A new test will be written here, dealing with different mutex attributes and with different condvar attributes.
  
• Assertion 4 is not tested yet. A new testcase will be written.
  
• Assertion 5 is not tested yet. A new testcase will be written.
  
• Assertion 6 is not tested yet. It will be tested in a stress test.
  
• Assertion 7 is tested in PTS 2-2.c and does not need more testing.
  
• Assertion 8 is tested in libc tst-cond11.c.
  This test might be ported to the PTS.
  
• Assertion 9 is not tested yet. A similar test as for assertion 3 must be written.
  
• Assertion 10 cannot be tested.
  
• Assertion 11 is tested in PTS 2-2.c ans does not need more testing.
  
• Assertion 12 is not tested yet. A new sample will be written here
  
• Assertion 13 is tested in libc tst-eintr5.c. This test might be ported to the PTS.
  

[tHeDoc]

Stress Status

Two stress sample will be written for conformance issues described in the previous post.

Another sample will be written to ensure that no condition signal or broadcast are lost.

[tHeDoc]

Scalability Status

A sample will be written to try and discover if there is a limit in the number of thread blocked in pthread_cond_timedwait which can be awaken with a call to pthread_cond_broadcast.
*Update* This will be tested in the pthread_cond_broadcast conformance tests.

Another sample will measure the duration between the abstime parameter and the moment the function returns the timeout error, trying to discover the influence of some parameters: the number of threads waiting on this conditionnal variable, the number of independent conditionnal variables in use in the system ...

[tHeDoc]

Conformance Samples



* Update * Jun 29, 2004

The following tests are now included in PTS:

• 2-4.c
  
• 2-5.c
  
• 2-6.c
  
• 2-7.c
  
• 4-2.c
  
• 4-3.c
  

[tHeDoc]

Scalability sample

Here is a sample which will measure the time between the end of the timeout and the actual function return, when the number of threads waiting on the condition increases; and with several mutex & condition attributes.

Alternatively, the output can be graphical. Thanx to the "do-plot" script from Iñaky Pérez-González - RobustMutexes project. Below is a (lightly) modified version of this script.

do-plot requires gnuplot to be installed.

Usage:
compile s-c.c with the macro PLOT_OUTPUT defined.
put the output from the run into a file, "datafile" for example.
./do-plot datafile

An example of output is also provided below.

* Update * 2004 - 08 - 13
The do-plot utility and scalability test are now part of the Open POSIX Test Suite.

• s-c.c
  
• do-plot
  

[tHeDoc]

Stress Tests

Three stress tests have been written and integrated to Open POSIX Test Suite.

• stress1.c tests for conformance assertion 2.
  
• stress2.c tests for conformance assertion 6.
  
• stress.c checks that no condition signal is lost.