Debian Codegraph @

upstream/debian-trixie/man3/pthread_attr_setscope.3

raw
1 '\" t
2 .\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
3 .\" <[email protected]>
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH pthread_attr_setscope 3 2024-05-02 "Linux man-pages 6.9.1"
8 .SH NAME
9 pthread_attr_setscope, pthread_attr_getscope \- set/get contention scope
10 attribute in thread attributes object
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_attr_setscope(pthread_attr_t *" attr ", int " scope );
19 .BI "int pthread_attr_getscope(const pthread_attr_t *restrict " attr ,
20 .BI " int *restrict " scope );
21 .fi
22 .SH DESCRIPTION
23 The
24 .BR pthread_attr_setscope ()
25 function sets the contention scope attribute of the
26 thread attributes object referred to by
27 .I attr
28 to the value specified in
29 .IR scope .
30 The contention scope attribute defines the set of threads
31 against which a thread competes for resources such as the CPU.
32 POSIX.1 specifies two possible values for
33 .IR scope :
34 .TP
35 .B PTHREAD_SCOPE_SYSTEM
36 The thread competes for resources with all other threads
37 in all processes on the system that are in the same scheduling
38 allocation domain (a group of one or more processors).
39 .B PTHREAD_SCOPE_SYSTEM
40 threads are scheduled relative to one another
41 according to their scheduling policy and priority.
42 .TP
43 .B PTHREAD_SCOPE_PROCESS
44 The thread competes for resources with all other threads
45 in the same process that were also created with the
46 .B PTHREAD_SCOPE_PROCESS
47 contention scope.
48 .B PTHREAD_SCOPE_PROCESS
49 threads are scheduled relative to other threads in the process
50 according to their scheduling policy and priority.
51 POSIX.1 leaves it unspecified how these threads contend
52 with other threads in other process on the system or
53 with other threads in the same process that
54 were created with the
55 .B PTHREAD_SCOPE_SYSTEM
56 contention scope.
57 .P
58 POSIX.1 requires that an implementation support at least one of these
59 contention scopes.
60 Linux supports
61 .BR PTHREAD_SCOPE_SYSTEM ,
62 but not
63 .BR PTHREAD_SCOPE_PROCESS .
64 .P
65 On systems that support multiple contention scopes, then,
66 in order for the parameter setting made by
67 .BR pthread_attr_setscope ()
68 to have effect when calling
69 .BR pthread_create (3),
70 the caller must use
71 .BR pthread_attr_setinheritsched (3)
72 to set the inherit-scheduler attribute of the attributes object
73 .I attr
74 to
75 .BR PTHREAD_EXPLICIT_SCHED .
76 .P
77 The
78 .BR pthread_attr_getscope ()
79 function returns the contention scope attribute of the
80 thread attributes object referred to by
81 .I attr
82 in the buffer pointed to by
83 .IR scope .
84 .SH RETURN VALUE
85 On success, these functions return 0;
86 on error, they return a nonzero error number.
87 .SH ERRORS
88 .BR pthread_attr_setscope ()
89 can fail with the following errors:
90 .TP
91 .B EINVAL
92 An invalid value was specified in
93 .IR scope .
94 .TP
95 .B ENOTSUP
96 .I scope
97 specified the value
98 .BR PTHREAD_SCOPE_PROCESS ,
99 which is not supported on Linux.
100 .SH ATTRIBUTES
101 For an explanation of the terms used in this section, see
102 .BR attributes (7).
103 .TS
104 allbox;
105 lbx lb lb
106 l l l.
107 Interface Attribute Value
108 T{
109 .na
110 .nh
111 .BR pthread_attr_setscope (),
112 .BR pthread_attr_getscope ()
113 T} Thread safety MT-Safe
114 .TE
115 .SH STANDARDS
116 POSIX.1-2008.
117 .SH HISTORY
118 POSIX.1-2001.
119 .SH NOTES
120 The
121 .B PTHREAD_SCOPE_SYSTEM
122 contention scope typically indicates that a user-space thread is
123 bound directly to a single kernel-scheduling entity.
124 This is the case on Linux for the obsolete LinuxThreads implementation
125 and the modern NPTL implementation,
126 which are both 1:1 threading implementations.
127 .P
128 POSIX.1 specifies that the default contention scope is
129 implementation-defined.
130 .SH SEE ALSO
131 .ad l
132 .nh
133 .BR pthread_attr_init (3),
134 .BR pthread_attr_setaffinity_np (3),
135 .BR pthread_attr_setinheritsched (3),
136 .BR pthread_attr_setschedparam (3),
137 .BR pthread_attr_setschedpolicy (3),
138 .BR pthread_create (3),
139 .BR pthreads (7)