GNU Info

(libc.info)Basic Thread Operations

---

Next: Thread Attributes Up: POSIX Threads

---

Enter node , (file) or (file)node

Basic Thread Operations
=======================

   These functions are the thread equivalents of `fork', `exit', and
`wait'.

 - Function: int pthread_create (pthread_t * THREAD, pthread_attr_t *
          ATTR, void * (*START_ROUTINE)(void *), void * ARG)
     `pthread_create' creates a new thread of control that executes
     concurrently with the calling thread. The new thread calls the
     function START_ROUTINE, passing it ARG as first argument. The new
     thread terminates either explicitly, by calling `pthread_exit', or
     implicitly, by returning from the START_ROUTINE function. The
     latter case is equivalent to calling `pthread_exit' with the result
     returned by START_ROUTINE as exit code.

     The ATTR argument specifies thread attributes to be applied to the
     new thread. Note: Thread Attributes, for details. The ATTR
     argument can also be `NULL', in which case default attributes are
     used: the created thread is joinable (not detached) and has an
     ordinary (not realtime) scheduling policy.

     On success, the identifier of the newly created thread is stored
     in the location pointed by the THREAD argument, and a 0 is
     returned. On error, a non-zero error code is returned.

     This function may return the following errors:
    `EAGAIN'
          Not enough system resources to create a process for the new
          thread, or more than `PTHREAD_THREADS_MAX' threads are
          already active.

 - Function: void pthread_exit (void *RETVAL)
     `pthread_exit' terminates the execution of the calling thread.  All
     cleanup handlers (Note: Cleanup Handlers) that have been set for
     the calling thread with `pthread_cleanup_push' are executed in
     reverse order (the most recently pushed handler is executed
     first). Finalization functions for thread-specific data are then
     called for all keys that have non-`NULL' values associated with
     them in the calling thread (Note: Thread-Specific Data).
     Finally, execution of the calling thread is stopped.

     The RETVAL argument is the return value of the thread. It can be
     retrieved from another thread using `pthread_join'.

     The `pthread_exit' function never returns.

 - Function: int pthread_cancel (pthread_t THREAD)
     `pthread_cancel' sends a cancellation request to the thread denoted
     by the THREAD argument.  If there is no such thread,
     `pthread_cancel' fails and returns `ESRCH'.  Otherwise it returns
     0. Note: Cancellation, for details.

 - Function: int pthread_join (pthread_t TH, void **thread_RETURN)
     `pthread_join' suspends the execution of the calling thread until
     the thread identified by TH terminates, either by calling
     `pthread_exit' or by being canceled.

     If THREAD_RETURN is not `NULL', the return value of TH is stored
     in the location pointed to by THREAD_RETURN.  The return value of
     TH is either the argument it gave to `pthread_exit', or
     `PTHREAD_CANCELED' if TH was canceled.

     The joined thread `th' must be in the joinable state: it must not
     have been detached using `pthread_detach' or the
     `PTHREAD_CREATE_DETACHED' attribute to `pthread_create'.

     When a joinable thread terminates, its memory resources (thread
     descriptor and stack) are not deallocated until another thread
     performs `pthread_join' on it. Therefore, `pthread_join' must be
     called once for each joinable thread created to avoid memory leaks.

     At most one thread can wait for the termination of a given thread.
     Calling `pthread_join' on a thread TH on which another thread is
     already waiting for termination returns an error.

     `pthread_join' is a cancellation point. If a thread is canceled
     while suspended in `pthread_join', the thread execution resumes
     immediately and the cancellation is executed without waiting for
     the TH thread to terminate. If cancellation occurs during
     `pthread_join', the TH thread remains not joined.

     On success, the return value of TH is stored in the location
     pointed to by THREAD_RETURN, and 0 is returned. On error, one of
     the following values is returned:
    `ESRCH'
          No thread could be found corresponding to that specified by
          TH.

    `EINVAL'
          The TH thread has been detached, or another thread is already
          waiting on termination of TH.

    `EDEADLK'
          The TH argument refers to the calling thread.