HP-UX Reference (11i v2 07/12) - 2 System Calls (vol 5)

p
postwait(2) postwait(2)
NAME
postwait: pw_getukid(), pw_getvmax(), pw_post(), pw_postv(), pw_wait() - lightweight synchronization
mechanism
SYNOPSIS
#include <sys/time.h>
#include <sys/pw.h>
int pw_getukid(ukid_t *
ukid);
int pw_wait(struct timespec *
ts);
int pw_post(ukid_t ukid);
int pw_postv(int count, ukid_t
targets[], int errors
[]);
int pw_getvmax(void);
DESCRIPTION
postwait() is a fast, lightweight sleep/wakeup mechanism that can be used for synchronization by
cooperating kernel threads within a single process or between separate processes.
A thread calls pw_wait() to block. It resumes execution when it is posted by another thread, when the
call expires, or when the call is signaled. If one or more posts are already pending, pw_wait()
returns
immediately.
Threads using postwait are identified by their ukid. A thread retrieves its ukid by calling
pw_getukid() . It shares this ukid with anyone it chooses by any means it considers appropriate (for
example, shared memory).
pw_wait() is called with a timeout ts.Ifts is NULL, the thread will not timeout. It will remain blocked
until posted or a signal wakes it up.
If ts points to a zero-valued timespec, pw_wait() will return immediately with a value (and errno
) indi-
cating whether or not it was posted.
If ts points to a timespec whose value is greater than zero, the thread will block for that amount of time
unless it is posted or interrupted by a signal, in which case the timespec pointed to by ts is updated with the
remaining time. The return value and
errno are set to indicate the reason the call returned.
pw_postv() is used to post many threads with a single call. It posts to all threads in the targets array.
An
errno value for each target is returned in the errors array. (0 indicates success.) If the errors pointer
is zero, no target-specific errors are copied out.
There is a maximum number of threads that can be posted with a single
pw_postv() call. This value is
returned by
pw_getvmax() .
Posts sent to a kernel thread that already has a post pending against it are discarded.
RETURN VALUE
pw_getukid() returns 0 if it succeeds, and returns -1 otherwise.
pw_wait() returns 0 if posted, and returns -1 otherwise.
pw_post() returns 0 if the post succeeds, and returns -1 otherwise.
pw_postv() returns 0 if every post succeeds, and returns -1 otherwise.
pw_getvmax() returns the maximum number of kernel threads that can be posted with a single call to
pw_postv() .
ERRORS
pw_getukid() sets errno to one of the following values if it fails:
[EFAULT] ukid points to an illegal address. The reliable detection of this error is implementation
dependent.
pw_wait() sets errno to one of the following values if it fails:
[EAGAIN] pw_wait() was called with a timeout that expired with no post(s) pending.
[EFAULT] ts points to an illegal address. The reliable detection of this error is implementation depen-
dent.
256 Hewlett-Packard Company − 1 − HP-UX 11i Version 2: December 2007 Update