| 1 |
'\" t |
| 2 |
.\" Copyright 2009, Michael Kerrisk <[email protected]> |
| 3 |
.\" Copyright, the authors of the Linux man-pages project |
| 4 |
.\" |
| 5 |
.\" SPDX-License-Identifier: Linux-man-pages-copyleft |
| 6 |
.\" |
| 7 |
.TH pthread_setconcurrency 3 2026-02-08 "Linux man-pages 6.18" |
| 8 |
.SH NAME |
| 9 |
pthread_setconcurrency, pthread_getconcurrency \- set/get |
| 10 |
the concurrency level |
| 11 |
.SH LIBRARY |
| 12 |
POSIX threads library |
| 13 |
.RI ( libpthread ,\~ \-lpthread ) |
| 14 |
.SH SYNOPSIS |
| 15 |
.nf |
| 16 |
.B #include <pthread.h> |
| 17 |
.P |
| 18 |
.BI "int pthread_setconcurrency(int " new_level ); |
| 19 |
.BI "int pthread_getconcurrency(" void ); |
| 20 |
.fi |
| 21 |
.SH DESCRIPTION |
| 22 |
The |
| 23 |
.BR pthread_setconcurrency () |
| 24 |
function informs the implementation of the application's |
| 25 |
desired concurrency level, specified in |
| 26 |
.IR new_level . |
| 27 |
The implementation takes this only as a hint: |
| 28 |
POSIX.1 does not specify the level of concurrency that |
| 29 |
should be provided as a result of calling |
| 30 |
.BR pthread_setconcurrency (). |
| 31 |
.P |
| 32 |
Specifying |
| 33 |
.I new_level |
| 34 |
as 0 instructs the implementation to manage the concurrency level |
| 35 |
as it deems appropriate. |
| 36 |
.P |
| 37 |
.BR pthread_getconcurrency () |
| 38 |
returns the current value of the concurrency level for this process. |
| 39 |
.SH RETURN VALUE |
| 40 |
On success, |
| 41 |
.BR pthread_setconcurrency () |
| 42 |
returns 0; |
| 43 |
on error, it returns a nonzero error number. |
| 44 |
.P |
| 45 |
.BR pthread_getconcurrency () |
| 46 |
always succeeds, returning the concurrency level set by a previous call to |
| 47 |
.BR pthread_setconcurrency (), |
| 48 |
or 0, if |
| 49 |
.BR pthread_setconcurrency () |
| 50 |
has not previously been called. |
| 51 |
.SH ERRORS |
| 52 |
.BR pthread_setconcurrency () |
| 53 |
can fail with the following error: |
| 54 |
.TP |
| 55 |
.B EINVAL |
| 56 |
.I new_level |
| 57 |
is negative. |
| 58 |
.P |
| 59 |
POSIX.1 also documents an |
| 60 |
.B EAGAIN |
| 61 |
error ("the value specified by |
| 62 |
.I new_level |
| 63 |
would cause a system resource to be exceeded"). |
| 64 |
.SH ATTRIBUTES |
| 65 |
For an explanation of the terms used in this section, see |
| 66 |
.BR attributes (7). |
| 67 |
.TS |
| 68 |
allbox; |
| 69 |
lbx lb lb |
| 70 |
l l l. |
| 71 |
Interface Attribute Value |
| 72 |
T{ |
| 73 |
.na |
| 74 |
.nh |
| 75 |
.BR pthread_setconcurrency (), |
| 76 |
.BR pthread_getconcurrency () |
| 77 |
T} Thread safety MT-Safe |
| 78 |
.TE |
| 79 |
.SH STANDARDS |
| 80 |
POSIX.1-2008. |
| 81 |
.SH HISTORY |
| 82 |
glibc 2.1. |
| 83 |
POSIX.1-2001. |
| 84 |
.SH NOTES |
| 85 |
The default concurrency level is 0. |
| 86 |
.P |
| 87 |
Concurrency levels are meaningful only for M:N threading implementations, |
| 88 |
where at any moment a subset of a process's set of user-level threads |
| 89 |
may be bound to a smaller number of kernel-scheduling entities. |
| 90 |
Setting the concurrency level allows the application to |
| 91 |
give the system a hint as to the number of kernel-scheduling entities |
| 92 |
that should be provided for efficient execution of the application. |
| 93 |
.P |
| 94 |
Both LinuxThreads and NPTL are 1:1 threading implementations, |
| 95 |
so setting the concurrency level has no meaning. |
| 96 |
In other words, |
| 97 |
on Linux these functions merely exist for compatibility with other systems, |
| 98 |
and they have no effect on the execution of a program. |
| 99 |
.SH SEE ALSO |
| 100 |
.BR pthread_attr_setscope (3), |
| 101 |
.BR pthreads (7) |