taskblock(3P)

NAME
     taskblock, taskunblock, tasksetblockcnt - routines to block/unblock tasks

C SYNOPSIS
     #include <sys/types.h>
     #include <task.h>

     int taskblock (tid_t tid);

     int taskunblock (tid_t tid);

     int tasksetblockcnt (tid_t tid, int count);

DESCRIPTION
     These routines provide a complete set of blocking/unblocking capabilities
     for tasks.  Blocking is implemented via a counting semaphore in the
     system.  Each call to taskblock decrements the count and, if it goes
     negative, the task is suspended.  When taskunblock is called, the count
     is incremented, and if it goes positive (or zero), the task is re-
     started.  This provides both a simple, race free synchronization ability
     between two tasks, as well as a much more powerful capability to
     synchronize multiple tasks.

     In order to guarantee a known starting place the tasksetblockcnt function
     may be called which will force the semaphore count to the value given by
     count. New tasks have their semaphore zeroed.  Normally, count should be
     set to 0.  If the resulting block count is greater than or equal to zero
     and the task is currently blocked, it will be unblocked.  If the
     resulting block count is less than zero, the task will be blocked.  Using
     this, a simple rendezvous mechanism can be set up.  If one task wanted to
     wait for n other tasks to complete, it could set its block count to -n.
     This would immediately force the task to block.  Then as each task
     finishes it unblocks the waiting task.  When the n'th task finishes the
     waiting task will be woken.

     A task may block another task provided that standard UNIX permissions are
     satisfied.

     These routines will fail and no operation will be performed if one or
     more of the following are true:

     [EINVAL]
          The tid specified is not a valid task id.

     [EPERM]
          The caller is not operating on itself, its effective user ID is not
          super-user, and its real or effective user ID does not match the
          real or effective user ID of the to be acted on task.
SEE ALSO
     blockproc(2), taskdestroy(3P), taskctl(3P), taskcreate(3P).

DIAGNOSTICS
     Upon successful completion, 0 is returned.  Otherwise, a value of -1 is
     returned to the calling task, and errno is set to indicate the error.