POSIX Threads Test Suite

Summary

• VSTH verifies the IEEE Std POSIX® 1003.1c-1995 Threads (pthreads) extension, the X/Open CAE System Interfaces & Headers, Issue 5 Threads (aspen threads), UNIX 03 Threads and POSIX 1003.1, 2003 edition
• The Northwood version additionally covers UNIX V7 and IEEE Std 1003.1, 2013 Edition
• Built upon the proven VSXgen harness, yielding a configurable and productive tool.
• Using the VSXgen architecture, this suite is provided as a VSXgen testset.
• Coverage for functions and header file tests.
• Includes coverage for thread safety and re-entrancy
• Test modes for UNIX 98, pthreads, UNIX 03, POSIX.1, 2003 Edition, and in the Northwood version additionally UNIX V7 and POSIX.1, 2013 Edition.
• POSIX-style assertions have been developed for all tests, greatly aiding failure analysis.
• Mandatory for testing the Single UNIX® Specification Version 2, 3, and 4.
• An embedded derivative VSTH-PSE is available for separate licensing.

If your organization is developing a pthreads implementation then this test suite gives significant test coverage and is recommended for in-house quality-assurance as well as part of your branding campaign.

Keywords: POSIX® Threads, UNIX® 98, UNIX® 03, UNIX® V7, Threads, Pthreads, Aspen Threads, Testing, POSIX, X/Open.

Top

Introduction

The IEEE POSIX Threads standard known as pthreads is a general threads API, specifying a robust set of threads facilities, including new thread specific APIs for the following:

• Thread management
• Thread-specific data
• Thread cancellation
• Thread synchronization
• Thread execution scheduling
• Thread synchronization scheduling

Pthreads is incorporated into CAE Specification System Interfaces & Headers Issue 5 (XSH5) and later, part of the Single UNIX Specification, Version. XSH adds the following extensions:

• the ability to set and get level of thread concurrency, this is an efficiency issue which can lead to better program performance.
• implements reader/writer locks, allows simultaneous read-only access to data, which is very useful.
• extended mutex attribute types.
• extended mutex locking.
• extended scheduling policies.
• set guard size for stacks.

The Open Group Threads Test Suite, known as VSTH, is a stand alone test suite covering POSIX 1003.1c and the X/Open threads extension included in the Single UNIX Specification.

VSTH uses the robust VSXgen test harness, which in turn uses the industry standard Test Environment Toolkit (TET3) . The benefits of using VSXgen, which is derived from VSX4, is that the harness is familiar to existing users of X/Open Test suites, it has proven portability and robustness characteristics and it allows the VSTH tests to be integrated with other testsets that run under VSXgen, making the test suites easily useable for in-house quality assurance and automated regression testing.

TET3 is the latest version of the Test Environment Toolkit and supports multi-threaded testing. More information on the Test Environment Toolkit is described on the TETworks web site.

Top

Test Coverage

The test suite can be run in the following modes

• POSIX 1003.1-1996 mode, covering Pthreads only.
• UNIX 98 mode, covering Pthreads and the XSH5 extensions
• POSIX 1003.1-2003 mode
• UNIX 03 mode
• UNIX 10 mode
• POSIX 08 mode

This allows the test suite to easily be used during development of your threads implementation, for example initially you might only want to run the POSIX 1003.1-1996 subset.

The assertion counts are as follows:

• POSIX 96 MODE: PTHR.hdr 286, PTHR.os 445
• UNIX98 MODE: PTHR.hdr 365, PTHR.os 563

The test suite covers the following functional areas in the IEEE POSIX 1003.1c standard.

• Base _POSIX_THREADS functions:

pthread_atfork
pthread_attr_destroy
pthread_attr_getdetachstate
pthread_attr_getschedparam
pthread_attr_getstackaddr
pthread_attr_getstacksize
pthread_attr_init
pthread_attr_setdetachstate
pthread_attr_setschedparam
pthread_attr_setstackaddr
pthread_attr_setstacksize
pthread_cancel
pthread_cleanup_pop
pthread_cleanup_push
pthread_cond_broadcast
pthread_cond_destroy
pthread_cond_init
pthread_cond_signal
pthread_cond_timedwait
pthread_cond_wait
pthread_condattr_destroy
pthread_condattr_getpshared
pthread_condattr_init
pthread_condattr_setpshared
pthread_create
pthread_detach
pthread_equal
pthread_exit
pthread_getspecific
pthread_join
pthread_key_create
pthread_key_delete
pthread_kill
pthread_mutex_destroy
pthread_mutex_init
pthread_mutex_lock
pthread_mutex_trylock
pthread_mutex_unlock
pthread_mutexattr_destroy
pthread_mutexattr_init
pthread_mutexattr_getpshared
pthread_mutexattr_setpshared
pthread_once
pthread_self
pthread_setcancelstate
pthread_setcanceltype
pthread_setspecific
pthread_sigmask
pthread_testcancel
sigwait

• Base _POSIX_THREAD_SAFE_FUNCTIONS

asctime_r
ctime_r
flockfile
ftrylockfile
funlockfile
getc_unlocked
getchar_unlocked
getgrgid_r
getgrnam_r
getpwnam_r
getpwuid_r
gmtime_r
localtime_r
putc_unlocked
putchar_unlocked
rand_r
readdir_r
strtok_r

• Functions in the _XOPEN_REALTIME_THREADS feature group

pthread_attr_getinheritsched
pthread_attr_getschedpolicy
pthread_attr_getscope
pthread_attr_setinheritsched
pthread_attr_setschedpolicy
pthread_attr_setscope
pthread_getschedparam
pthread_mutex_getprioceiling
pthread_mutex_setprioceiling
pthread_mutexattr_getprioceiling
pthread_mutexattr_getprotocol
pthread_mutexattr_setprioceiling
pthread_mutexattr_setprotocol
pthread_setschedparam

• X/Open threads extensions:

pthread_attr_getguardsize
pthread_attr_setguardsize
pthread_getconcurrency
pthread_mutexattr_gettype
pthread_mutexattr_settype
pthread_rwlock_destroy
pthread_rwlock_init
pthread_rwlock_rdlock
pthread_rwlock_tryrdlock
pthread_rwlock_trywrlock
pthread_rwlock_unlock
pthread_rwlock_wrlock
pthread_rwlockattr_destroy
pthread_rwlockattr_getpshared
pthread_rwlockattr_init
pthread_rwlockattr_setpshared
pthread_setconcurrency

Top

Modular Design

VSTH is modular, both at the implementation level and at the user level. The testing process is divided into clear stages -

• Preparation
• Configuration
• Installation
• Building
• Execution
• Reporting

Each stage is clearly documented in the User and Installation Guide, which accompanies the product.

Preparation

This stage includes setting up user-ids and groups for testing, and reading the tape. This stage includes configuring and installing the TET harness, which is used to control building, execution and cleanup of VSTH tests.

Configuration and Installation

VSTH automatically installs on most common platforms. Where system dependencies may vary, these are isolated into clearly defined user changeable sections of the test suite. During this stage VSTH builds the test harness and associated libraries.

Test Building

VSTH separates the building of the test harness and tools from the testsets themselves. The test suite may be built completely or in sub-sections, which decrease in granularity from test sections and areas down to individual testsets.

Test Execution

Once built, the test suite may be run as a whole in one pass, or in sub-sections which decrease in granularity from test areas down to individual tests within testsets. If you are producing an X/Open branding application the test suite must run in a single uninterrupted pass.

Test Reporting

VSTH generates an intermediate level journal file in a TET compliant format. This is sufficient for debugging purposes. When a formal report is required, such as for X/Open branding then the formal report writers provided with VSTH are used to process the journal file.

Top

POSIX is a registered trademark of the IEEE.

Further Information

• Current Test suite version information.
• Technical White papers.
• The Online Single UNIX Specification

Top