4.10.39 thd
Keywords: onyx

Next: 4.10.40 tsd Up: 4.10 Classes Previous: 4.10.38 qs Contents Index
Subsections

- 4.10.39.1 API

##
4.10.39 thd

The thd class implements a wrapper around the system POSIX threads library or GNU pth library. In most regards, this is a thin wrapper around the normal threading functionality, but some extra information is kept in order to allow implmentation of thread suspension/resumption, ``critical sections'', and ``single sections''.

The suspendibility of each thread is determined by the arguments passed to thd_new(). The initial thread is always suspensible. Other threads that are created via some mechanism other than thd_new() are not suspensible.

Depending on how libonyx is built, the additional functionality is implemented with the aid of the SIGUSR1 and SIGUSR2 signals. As a result, system calls may be interrupted by signals. The system calls will be automatically restarted if they have made no progress at the time of interruption, but will return a partial result otherwise. Therefore, if any of the additional functionality is utilized, the application must be careful to handle partial system call results. At least the following system calls can be interrupted: read(), write(), sendto(), recvfrom(), sendmsg(), recvmsg(), ioctl(), and wait(). See the system documentation for additional information.

### 4.10.39.1 API

cw_thd_t * thd_new(void *(*a_start_func)(void *), void *a_arg, bool a_suspensible):

  Input(s):
    a_start_func:
      Pointer to a start function.
    a_arg:
      Argument passed to a_start_func().
    a_suspensible:
      false:
        Not suspensible.
      true:
        Suspensible.
  Output(s):
    retval:
      Pointer to a thd.
  Exception(s):
    CW_ONYXX_OOM.
  Description:
    Constructor (creates a new thread).

void thd_delete(cw_thd_t *a_thd):

  Input(s):
    a_thd:
      Pointer to a thd.
  Output(s):
    None.
  Exception(s):
    None.
  Description:
    Destructor.

void * thd_join(cw_thd_t *a_thd):

  Input(s):
    a_thd:
      Pointer to a thd.
  Output(s):
    retval:
      Return value from thread entry function.
  Exception(s):
    None.
  Description:
    Join (wait for) the thread associated with a_thd.

cw_thd_t * thd_self(void):

  Input(s):
    None.
  Output(s):
    retval:
      Pointer to the calling thread's thd structure.
  Exception(s):
    None.
  Description:
    Return a pointer to the thd structure that corresponds to the calling thread.

void thd_yield(void):

  Input(s):
    None.
  Output(s):
    None.
  Exception(s):
    None.
  Description:
    Give up the rest of the calling thread's time slice.

int thd_sigmask(int a_how, const sigset_t *a_set, sigset_t *r_oset):

  Input(s):
    a_how:
      SIG_BLOCK:
        Block signals in a_set.
      SIG_UNBLOCK:
        Unblock signals in a_set.
      SIG_SETMASK:
        Set signal mask to a_set.
    a_set:
      Pointer to a signal set.
    r_oset:
      non-NULL:
        Pointer space to store the old signal mask.
      NULL:
        Ignored.
  Output(s):
    retval:
      Always zero, unless the arguments are invalid.
    *r_oset:
      Old signal set.
  Exception(s):
    None.
  Description:
    Set the calling thread's signal mask.

void thd_crit_enter(void):

  Input(s):
    None.
  Output(s):
    None.
  Exception(s):
    None.
  Description:
    Enter a critical region where the calling thread may not be suspended by thd_suspend(), thd_trysuspend(), or thd_single_enter().

void thd_crit_leave(void):

  Input(s):
    None.
  Output(s):
    None.
  Exception(s):
    None.
  Description:
    Leave a critical section; the calling thread may once again be suspended.

void thd_single_enter(void):

  Input(s):
    None.
  Output(s):
    None.
  Exception(s):
    None.
  Description:
    Enter a critical region where all other suspensible threads must be suspended.

void thd_single_leave(void):

  Input(s):
    None.
  Output(s):
    None.
  Exception(s):
    None.
  Description:
    Leave a critical section where all other threads must be suspended. All threads that were suspended in thd_single_enter() are resumed.

void thd_suspend(cw_thd_t *a_thd):

  Input(s):
    a_thd:
      Pointer to a thd.
  Output(s):
    None.
  Exception(s):
    None.
  Description:
    Suspend a_thd.

bool thd_trysuspend(cw_thd_t *a_thd):

  Input(s):
    a_thd:
      Pointer to a thd.
  Output(s):
    retval:
      false:
        Success.
      true:
        Failure.
  Exception(s):
    None.
  Description:
    Try to suspend a_thd, but fail if it is in a critical section.

void thd_resume(cw_thd_t *a_thd):

  Input(s):
    a_thd:
      Pointer to a thd.
  Output(s):
    None.
  Exception(s):
    None.
  Description:
    Resume (make runnable) a_thd.

Next: 4.10.40 tsd Up: 4.10 Classes Previous: 4.10.38 qs Contents Index