diff options
Diffstat (limited to 'man3/pthread_attr_setscope.3')
| -rw-r--r-- | man3/pthread_attr_setscope.3 | 140 |
1 files changed, 140 insertions, 0 deletions
diff --git a/man3/pthread_attr_setscope.3 b/man3/pthread_attr_setscope.3 new file mode 100644 index 0000000..c9acfc4 --- /dev/null +++ b/man3/pthread_attr_setscope.3 @@ -0,0 +1,140 @@ +'\" t +.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk +.\" <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pthread_attr_setscope 3 2023-07-20 "Linux man-pages 6.05.01" +.SH NAME +pthread_attr_setscope, pthread_attr_getscope \- set/get contention scope +attribute in thread attributes object +.SH LIBRARY +POSIX threads library +.RI ( libpthread ", " \-lpthread ) +.SH SYNOPSIS +.nf +.B #include <pthread.h> +.PP +.BI "int pthread_attr_setscope(pthread_attr_t *" attr ", int " scope ); +.BI "int pthread_attr_getscope(const pthread_attr_t *restrict " attr , +.BI " int *restrict " scope ); +.fi +.SH DESCRIPTION +The +.BR pthread_attr_setscope () +function sets the contention scope attribute of the +thread attributes object referred to by +.I attr +to the value specified in +.IR scope . +The contention scope attribute defines the set of threads +against which a thread competes for resources such as the CPU. +POSIX.1 specifies two possible values for +.IR scope : +.TP +.B PTHREAD_SCOPE_SYSTEM +The thread competes for resources with all other threads +in all processes on the system that are in the same scheduling +allocation domain (a group of one or more processors). +.B PTHREAD_SCOPE_SYSTEM +threads are scheduled relative to one another +according to their scheduling policy and priority. +.TP +.B PTHREAD_SCOPE_PROCESS +The thread competes for resources with all other threads +in the same process that were also created with the +.B PTHREAD_SCOPE_PROCESS +contention scope. +.B PTHREAD_SCOPE_PROCESS +threads are scheduled relative to other threads in the process +according to their scheduling policy and priority. +POSIX.1 leaves it unspecified how these threads contend +with other threads in other process on the system or +with other threads in the same process that +were created with the +.B PTHREAD_SCOPE_SYSTEM +contention scope. +.PP +POSIX.1 requires that an implementation support at least one of these +contention scopes. +Linux supports +.BR PTHREAD_SCOPE_SYSTEM , +but not +.BR PTHREAD_SCOPE_PROCESS . +.PP +On systems that support multiple contention scopes, then, +in order for the parameter setting made by +.BR pthread_attr_setscope () +to have effect when calling +.BR pthread_create (3), +the caller must use +.BR pthread_attr_setinheritsched (3) +to set the inherit-scheduler attribute of the attributes object +.I attr +to +.BR PTHREAD_EXPLICIT_SCHED . +.PP +The +.BR pthread_attr_getscope () +function returns the contention scope attribute of the +thread attributes object referred to by +.I attr +in the buffer pointed to by +.IR scope . +.SH RETURN VALUE +On success, these functions return 0; +on error, they return a nonzero error number. +.SH ERRORS +.BR pthread_attr_setscope () +can fail with the following errors: +.TP +.B EINVAL +An invalid value was specified in +.IR scope . +.TP +.B ENOTSUP +.I scope +specified the value +.BR PTHREAD_SCOPE_PROCESS , +which is not supported on Linux. +.SH ATTRIBUTES +For an explanation of the terms used in this section, see +.BR attributes (7). +.TS +allbox; +lbx lb lb +l l l. +Interface Attribute Value +T{ +.na +.nh +.BR pthread_attr_setscope (), +.BR pthread_attr_getscope () +T} Thread safety MT-Safe +.TE +.sp 1 +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +The +.B PTHREAD_SCOPE_SYSTEM +contention scope typically indicates that a user-space thread is +bound directly to a single kernel-scheduling entity. +This is the case on Linux for the obsolete LinuxThreads implementation +and the modern NPTL implementation, +which are both 1:1 threading implementations. +.PP +POSIX.1 specifies that the default contention scope is +implementation-defined. +.SH SEE ALSO +.ad l +.nh +.BR pthread_attr_init (3), +.BR pthread_attr_setaffinity_np (3), +.BR pthread_attr_setinheritsched (3), +.BR pthread_attr_setschedparam (3), +.BR pthread_attr_setschedpolicy (3), +.BR pthread_create (3), +.BR pthreads (7) |