Content
pthsem / GNU pth

pthsem / GNU pth

GNU pth is a user mode multi threading library.

pthsem is a fork, with support for semaphores added. It can be installed parallel to a normal pth and provides a compatibilty layer to compile GNU pth programs with pthsem. The header file is called pthsem.h, the configuration programm pthsem-config and the autoconf macro AC_CHECK_PTHSEM. If references to one of these names are changed, pthsem can be used as an replacement of GNU pth.

The current version is pthsem_2.0.8.tar.gz.

Debian Packages
RPM Packages

To build the Debian package, download the tar.gz and extract it, change into the created directory and then run

chmod a+x debian/rules
dpkg-buildpackage -rfakeroot
To build the RPM, download the tar.gz and run
rpmbuild -ta filename
For other distributions, extract the tar file and run
./configure
make
make install

Changelog

  • pthsem 2.0.4
  • The version 2.0.5 includes more bug fixes, a documentation update and some rebranding in the autoconf macro. Packaging scripts for RPM and Debian are included. All patches are included.
  • pthsem-2.0.7 is a maintainance release, which is based on pth 2.0.7
  • changes in pthsem-2.0.8:
    • Monotonic clock support to cope with system time changes
    • Switch to automake based build system
    • compat package for building pth applications with pthsem

Documentation

The interface provides functions to set/get the value of a semaphore, increment it with arbitrary values, wait, until the value becomes bigger than a given value (without or with decrementing, if the condition becomes true.

The data-type for the semaphore is names pth_sem_t and it has an initializer like pth_cond_t.

The functions are:
int pth_sem_init(pth_sem_t *sem) initialize sem (used like pth_cond_init)
int pth_sem_dec(pth_sem_t *sem) waits, until the value of sem is >= 1 and decrement it.
int pth_sem_dec_value(pth_sem_t *sem, unsigned value) waits, until the value of sem is >= value and subtracts value
int pth_sem_inc(pth_sem_t *sem, int notify) increments sem. the scheduler is started, if notify is not null
int pth_sem_inc_value(pth_sem_t *sem, unsigned value, int notify) adds value to sem. the sheduler is started, if notify is not null
int pth_sem_set_value(pth_sem_t *sem, unsigned value) sets the value of sem to value
int pth_sem_get_value(pth_sem_t *sem, unsigned *value) stores the value of sem in *value

events for waiting for an semaphore can be create with PTH_EVENT_SEM in the specs-parameter of pth_event. Then a pointer to a semaphore is expected as parameter.

Additionally there two flags:

  • PTH_UNTIL_DECREMENT
    decrement, the value of the semaphore, if the value of the semaphore is big enough. If the flag is not specified, the lock will not be obtained, the event will occur, if obtaining a lock would be possible.
  • PTH_UNTIL_COUNT
    as an additional parameter, an unsigned int is passed. The event will occur, if the value of the semaphore is >= this parameter. If the flag is not specified, 1 is used as default.
eg:
  • pth_event(PTH_EVENT_SEM|PTH_UNTIL_DECREMENT|PTH_UNTIL_COUNT, &sem,2)
    event waits, utils the value of the semaphore is >= 2 and subtracts then two from it
  • pth_event(PTH_EVENT_SEM|PTH_UNTIL_COUNT, &sem,2)
    event waits, util the value of the semaphore is >= 2
  • pth_event(PTH_EVENT_SEM|PTH_UNTIL_DECREMENT, &sem)
    event waits, util the value of the semaphore is >= 1 and subtracts then 1 from it
  • pth_event(PTH_EVENT_SEM, &sem)
    event waits, util the value of the semaphore is >= 1
The interface is so open, that the semphores can be used for various purposes.

The new event type PTH_EVENT_RTIME is a time interval event. The additional argument has to be of type pth_time_t (usually on-the-fly generated via pth_time(3)), containing a time interval. During creation, it is converted into PTH_EVENT_TIME. It has the advantage, that it only uses the pthsem internal clock.Example:
pth_event(PTH_EVENT_TIME, pth_timeout(2,0))
is equal to
pth_event(PTH_EVENT_RTIME, pth_time(2,0))

Martin Kögler <mkoegler@auto.tuwien.ac.at> (please no html mails)
http://www.auto.tuwien.ac.at/~mkoegler