1PTHREAD_ATTR_SETSCOPE(3)   Linux Programmer's Manual  PTHREAD_ATTR_SETSCOPE(3)
2
3
4

NAME

6       pthread_attr_setscope, pthread_attr_getscope - set/get contention scope
7       attribute in thread attributes object
8

SYNOPSIS

10       #include <pthread.h>
11
12       int pthread_attr_setscope(pthread_attr_t *attr, int scope);
13       int pthread_attr_getscope(const pthread_attr_t *restrict attr,
14                                 int *restrict scope);
15
16       Compile and link with -pthread.
17

DESCRIPTION

19       The pthread_attr_setscope() function sets the contention  scope  attri‐
20       bute  of  the thread attributes object referred to by attr to the value
21       specified in scope.  The contention scope attribute defines the set  of
22       threads  against which a thread competes for resources such as the CPU.
23       POSIX.1 specifies two possible values for scope:
24
25       PTHREAD_SCOPE_SYSTEM
26              The thread competes for resources with all other threads in  all
27              processes  on the system that are in the same scheduling alloca‐
28              tion   domain   (a   group   of   one   or   more   processors).
29              PTHREAD_SCOPE_SYSTEM  threads  are scheduled relative to one an‐
30              other according to their scheduling policy and priority.
31
32       PTHREAD_SCOPE_PROCESS
33              The thread competes for resources with all other threads in  the
34              same    process    that    were    also    created    with   the
35              PTHREAD_SCOPE_PROCESS contention  scope.   PTHREAD_SCOPE_PROCESS
36              threads  are  scheduled relative to other threads in the process
37              according to their  scheduling  policy  and  priority.   POSIX.1
38              leaves  it  unspecified  how  these  threads  contend with other
39              threads in other process on the system or with other threads  in
40              the same process that were created with the PTHREAD_SCOPE_SYSTEM
41              contention scope.
42
43       POSIX.1 requires that an implementation support at least one  of  these
44       contention   scopes.   Linux  supports  PTHREAD_SCOPE_SYSTEM,  but  not
45       PTHREAD_SCOPE_PROCESS.
46
47       On systems that support multiple contention scopes, then, in order  for
48       the  parameter  setting  made by pthread_attr_setscope() to have effect
49       when calling pthread_create(3), the caller must  use  pthread_attr_set‐
50       inheritsched(3)  to  set  the  inherit-scheduler  attribute  of the at‐
51       tributes object attr to PTHREAD_EXPLICIT_SCHED.
52
53       The pthread_attr_getscope() function returns the contention  scope  at‐
54       tribute of the thread attributes object referred to by attr in the buf‐
55       fer pointed to by scope.
56

RETURN VALUE

58       On success, these functions return 0; on error, they return  a  nonzero
59       error number.
60

ERRORS

62       pthread_attr_setscope() can fail with the following errors:
63
64       EINVAL An invalid value was specified in scope.
65
66       ENOTSUP
67              scope  specified  the  value PTHREAD_SCOPE_PROCESS, which is not
68              supported on Linux.
69

ATTRIBUTES

71       For an  explanation  of  the  terms  used  in  this  section,  see  at‐
72       tributes(7).
73
74       ┌────────────────────────────────────────────┬───────────────┬─────────┐
75Interface                                   Attribute     Value   
76       ├────────────────────────────────────────────┼───────────────┼─────────┤
77pthread_attr_setscope(),                    │ Thread safety │ MT-Safe │
78pthread_attr_getscope()                     │               │         │
79       └────────────────────────────────────────────┴───────────────┴─────────┘
80

CONFORMING TO

82       POSIX.1-2001, POSIX.1-2008.
83

NOTES

85       The PTHREAD_SCOPE_SYSTEM contention scope typically  indicates  that  a
86       user-space thread is bound directly to a single kernel-scheduling enti‐
87       ty.  This is the case on Linux for the obsolete LinuxThreads  implemen‐
88       tation and the modern NPTL implementation, which are both 1:1 threading
89       implementations.
90
91       POSIX.1 specifies that the default contention scope is  implementation-
92       defined.
93

SEE ALSO

95       pthread_attr_init(3), pthread_attr_setaffinity_np(3),
96       pthread_attr_setinheritsched(3), pthread_attr_setschedparam(3),
97       pthread_attr_setschedpolicy(3), pthread_create(3), pthreads(7)
98

COLOPHON

100       This page is part of release 5.12 of the Linux man-pages project.  A
101       description of the project, information about reporting bugs, and the
102       latest version of this page, can be found at
103       https://www.kernel.org/doc/man-pages/.
104
105
106
107Linux                             2021-03-22          PTHREAD_ATTR_SETSCOPE(3)
Impressum