Linux libc-Doku
Files | |
file | pthread.h |
Functions | |
int | pthread_create (pthread_t *thread, const pthread_attr_t *attr, void *(*start_routine)(void *), void *arg) |
Create a thread. More... | |
void | pthread_exit (void *retval) |
Exit a thread. More... | |
int | pthread_join (pthread_t thread, void **retval) |
Wait for a thread. More... | |
int | pthread_detach (pthread_t thread) |
Detach a thread. More... | |
int | pthread_mutex_init (pthread_mutex_t *mutex, const pthread_mutexattr_t *mutexattr) |
Create a mutex. More... | |
int | pthread_mutex_lock (pthread_mutex_t *mutex) |
Lock a mutex. More... | |
int | pthread_mutex_unlock (pthread_mutex_t *mutex) |
Unlock a mutex. More... | |
int | pthread_mutex_destroy (pthread_mutex_t *mutex) |
Destroy a mutex. More... | |
Detailed Description
This page shows a simplified interface for POSIX threads (pthreads). Threads are a more lightweight method to use the concurrency potential of modern multi-core processors, compared to the process concept of Linux.
Disclaimer: Some parts of the interface are simplified. This page does not replace a thorough study of the manpages for the respective functions!
The pthread_*()
function family does not set the errno
variable to indicate the error cause, but instead returns an error value (or 0
on success). Thus, the return value of pthread_*()
functions can be usually assigned to errno
(except otherwise stated) and in case of an error perror() can be used to print a meaningful error message. Be aware, that the errno
is not a global but a thread-local variable, hence each thread has its own errno
.
If you intend to use this library, make sure to run your gcc
with the appropriate flags.
-pthread -std=c11 -Werror -Wall -pedantic -D_XOPEN_SOURCE=700 -O3
Minimal pthread
example:
Function Documentation
int pthread_create | ( | pthread_t * | thread, |
const pthread_attr_t * | attr, | ||
void *(*)(void *) | start_routine, | ||
void * | arg | ||
) |
The pthread_create() function creates and starts a new thread within the calling process. The new thread will initially execute the function specified in start_routine
, which receives a void *
pointer as parameter and returns a void *
pointer. The argument handed over to the new thread is specified in arg
.
The pthread_create() function uses the pointer in thread
to store the thread id in the underlying pthread_t
variable, which can be used to identify a thread in further pthread_*
function calls.
The attributes for the new thread are specified in attr
. For default attributes NULL
can be used.
A thread that has been created with pthread_create() must be joined with pthread_join() or marked as detached using pthread_detach() in order to free the resources associated with the thread. This is similar to fork() and waitpid() for processes.
- Parameters
-
thread pointer to the thread id attr thread attributes ( NULL
for default attributes)start_routine function the thread initially executes arg argument for start_routine
- Return values
-
0 on success !=0 on error
void pthread_exit | ( | void * | retval | ) |
The pthread_exit() function terminates the calling thread with the return value in retval
.
This function never returns.
- Parameters
-
retval return value visible to a pthread_join() caller
int pthread_join | ( | pthread_t | thread, |
void ** | retval | ||
) |
The pthread_join() function waits for the thread in thread
to terminate. If the thread has already been terminated, the pthread_join() function returns immediately. The return value of the terminated thread can be retrieved by retval
.
Be aware that threads marked as detached (pthread_detach()) can not be joined anymore!
Example code
- Parameters
-
thread thread to wait for retval buffer for a pointer to the return value
- Return values
-
0 on success !=0 on error
int pthread_detach | ( | pthread_t | thread | ) |
The pthread_detach() function marks the thread in thread
detached. This automatically frees all resources, when the threads exits. Once a thread is marked as detached it can not be joined using pthread_join() anymore!
- Parameters
-
thread thread to detach
- Return values
-
0 on success !=0 on error
int pthread_mutex_init | ( | pthread_mutex_t * | mutex, |
const pthread_mutexattr_t * | mutexattr | ||
) |
The pthread_mutex_init() function initializes a pthread mutex. It receives a pointer to a pthread_mutex_t
type and a pointer to the attributes in mutexattr
. For default attributes NULL
can be used for mutexattr
. If a mutex should be destroyed the pthread_mutex_destroy() function can be used.
- Parameters
-
mutex mutex to be initialized mutexattr attributes for mutex
(NULL
for default)
- Return values
-
0 on success != on error
int pthread_mutex_lock | ( | pthread_mutex_t * | mutex | ) |
The pthread_mutex_lock() function blocks the current thread, until it successfully acquired the mutex in mutex
. When this function returns, the thread can safely assume to be the only thread inside of the critical section guarded by mutex
.
- Parameters
-
mutex mutex to lock
int pthread_mutex_unlock | ( | pthread_mutex_t * | mutex | ) |
The pthread_mutex_unlock() function releases the mutex in mutex
.
- Parameters
-
mutex mutex to unlock
int pthread_mutex_destroy | ( | pthread_mutex_t * | mutex | ) |
The pthread_mutex_destroy() function destroys the mutex in mutex
. After this function returns, pthread_mutex_lock() and pthread_mutex_unlock() must not be called with this mutex as argument anymore.
- Parameters
-
mutex mutex to destroy