postwait(2)                                                     postwait(2)




 NAME    [Toc]    [Back]
      postwait: pw_getukid(), pw_wait(), pw_post(), pw_postv(), pw_getvmax()
      - lightweight synchronization mechanism

 SYNOPSIS    [Toc]    [Back]
      #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    [Toc]    [Back]
      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, 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.  If ts 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.




 Hewlett-Packard Company            - 1 -      HP-UX 11i Version 2: Sep 2004






 postwait(2)                                                     postwait(2)




      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    [Toc]    [Back]
      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    [Toc]    [Back]
      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 of 0 but the
                          caller has no post(s) pending.

           [EFAULT]       ts points to an illegal address.  The reliable
                          detection of this error is implementation
                          dependent.

           [EINTR]        pw_wait() was interrupted by a signal.

           [EINVAL]       The timespec pointed to by ts is invalid.

      pw_post() sets errno to one of the following values if it fails:

           [EINVAL]       The ukid refers to a non-existent kernel thread.

      pw_postv() sets errno to one of the following values if it fails:

           [EFAULT]       targets points to an illegal address.  The
                          reliable detection of this error is implementation
                          dependent.

           [EFAULT]       errors points to an illegal address.  The reliable
                          detection of this error is implementation
                          dependent.



 Hewlett-Packard Company            - 2 -      HP-UX 11i Version 2: Sep 2004






 postwait(2)                                                     postwait(2)




           [EINVAL]       count is less than 0.

           [EINVAL]       count exceeds the maximum value (as returned by
                          pw_getvmax()).

           [EINVAL]       A ukid refers to a non-existent kernel thread.


 Hewlett-Packard Company            - 3 -      HP-UX 11i Version 2: Sep 2004