postwait.2 (2010 09)

p
postwait(2) postwait(2)
NAME
postwait: pw_getukid(), pw_wait(), pw_post(), pw_postv(), pw_getvmax() - 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 cooperat-
ing 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, the call
expires, or 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
)
indicating 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, -1 otherwise.
pw_wait() returns 0 if posted, -1 otherwise.
pw_post() returns 0 if the post succeeds, -1 otherwise.
pw_postv() returns 0 if every post succeeds, -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 implementa-
tion dependent.
pw_wait() sets errno to one of the following values if it fails:
[EAGAIN]
pw_wait() was called with a timeout of 0 but the caller has no post(s) pending.
[EAGAIN]
pw_wait() was called with a timeout that expired.
[EFAULT] ts points to an illegal address. The reliable detection of this error is implementation
dependent.
HP-UX 11i Version 3: September 2010 − 1 − Hewlett-Packard Company 1