summaryrefslogtreecommitdiffstats
path: root/man3/pthread_setschedparam.3
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--man3/pthread_setschedparam.3448
1 files changed, 448 insertions, 0 deletions
diff --git a/man3/pthread_setschedparam.3 b/man3/pthread_setschedparam.3
new file mode 100644
index 0000000..62a5832
--- /dev/null
+++ b/man3/pthread_setschedparam.3
@@ -0,0 +1,448 @@
+'\" t
+.\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
+.\" <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH pthread_setschedparam 3 2023-07-20 "Linux man-pages 6.05.01"
+.SH NAME
+pthread_setschedparam, pthread_getschedparam \- set/get
+scheduling policy and parameters of a thread
+.SH LIBRARY
+POSIX threads library
+.RI ( libpthread ", " \-lpthread )
+.SH SYNOPSIS
+.nf
+.B #include <pthread.h>
+.PP
+.BI "int pthread_setschedparam(pthread_t " thread ", int " policy ,
+.BI " const struct sched_param *" param );
+.BI "int pthread_getschedparam(pthread_t " thread ", int *restrict " policy ,
+.BI " struct sched_param *restrict " param );
+.fi
+.SH DESCRIPTION
+The
+.BR pthread_setschedparam ()
+function sets the scheduling policy and parameters of the thread
+.IR thread .
+.PP
+.I policy
+specifies the new scheduling policy for
+.IR thread .
+The supported values for
+.IR policy ,
+and their semantics, are described in
+.BR sched (7).
+.\" FIXME . pthread_setschedparam() places no restriction on the policy,
+.\" but pthread_attr_setschedpolicy() restricts policy to RR/FIFO/OTHER
+.\" http://sourceware.org/bugzilla/show_bug.cgi?id=7013
+.PP
+The structure pointed to by
+.I param
+specifies the new scheduling parameters for
+.IR thread .
+Scheduling parameters are maintained in the following structure:
+.PP
+.in +4n
+.EX
+struct sched_param {
+ int sched_priority; /* Scheduling priority */
+};
+.EE
+.in
+.PP
+As can be seen, only one scheduling parameter is supported.
+For details of the permitted ranges for scheduling priorities
+in each scheduling policy, see
+.BR sched (7).
+.PP
+The
+.BR pthread_getschedparam ()
+function returns the scheduling policy and parameters of the thread
+.IR thread ,
+in the buffers pointed to by
+.I policy
+and
+.IR param ,
+respectively.
+The returned priority value is that set by the most recent
+.BR pthread_setschedparam (),
+.BR pthread_setschedprio (3),
+or
+.BR pthread_create (3)
+call that affected
+.IR thread .
+The returned priority does not reflect any temporary priority adjustments
+as a result of calls to any priority inheritance or
+priority ceiling functions (see, for example,
+.BR pthread_mutexattr_setprioceiling (3)
+and
+.BR pthread_mutexattr_setprotocol (3)).
+.\" FIXME . nptl/pthread_setschedparam.c has the following
+.\" /* If the thread should have higher priority because of some
+.\" PTHREAD_PRIO_PROTECT mutexes it holds, adjust the priority. */
+.\" Eventually (perhaps after writing the mutexattr pages), we
+.\" may want to add something on the topic to this page.
+.SH RETURN VALUE
+On success, these functions return 0;
+on error, they return a nonzero error number.
+If
+.BR pthread_setschedparam ()
+fails, the scheduling policy and parameters of
+.I thread
+are not changed.
+.SH ERRORS
+Both of these functions can fail with the following error:
+.TP
+.B ESRCH
+No thread with the ID
+.I thread
+could be found.
+.PP
+.BR pthread_setschedparam ()
+may additionally fail with the following errors:
+.TP
+.B EINVAL
+.I policy
+is not a recognized policy, or
+.I param
+does not make sense for the
+.IR policy .
+.TP
+.B EPERM
+The caller does not have appropriate privileges
+to set the specified scheduling policy and parameters.
+.PP
+POSIX.1 also documents an
+.B ENOTSUP
+("attempt was made to set the policy or scheduling parameters
+to an unsupported value") error for
+.BR pthread_setschedparam ().
+.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_setschedparam (),
+.BR pthread_getschedparam ()
+T} Thread safety MT-Safe
+.TE
+.sp 1
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+glibc 2.0
+POSIX.1-2001.
+.SH NOTES
+For a description of the permissions required to, and the effect of,
+changing a thread's scheduling policy and priority,
+and details of the permitted ranges for priorities
+in each scheduling policy, see
+.BR sched (7).
+.SH EXAMPLES
+The program below demonstrates the use of
+.BR pthread_setschedparam ()
+and
+.BR pthread_getschedparam (),
+as well as the use of a number of other scheduling-related
+pthreads functions.
+.PP
+In the following run, the main thread sets its scheduling policy to
+.B SCHED_FIFO
+with a priority of 10,
+and initializes a thread attributes object with
+a scheduling policy attribute of
+.B SCHED_RR
+and a scheduling priority attribute of 20.
+The program then sets (using
+.BR pthread_attr_setinheritsched (3))
+the inherit scheduler attribute of the thread attributes object to
+.BR PTHREAD_EXPLICIT_SCHED ,
+meaning that threads created using this attributes object should
+take their scheduling attributes from the thread attributes object.
+The program then creates a thread using the thread attributes object,
+and that thread displays its scheduling policy and priority.
+.PP
+.in +4n
+.EX
+$ \fBsu\fP # Need privilege to set real\-time scheduling policies
+Password:
+# \fB./a.out \-mf10 \-ar20 \-i e\fP
+Scheduler settings of main thread
+ policy=SCHED_FIFO, priority=10
+\&
+Scheduler settings in \[aq]attr\[aq]
+ policy=SCHED_RR, priority=20
+ inheritsched is EXPLICIT
+\&
+Scheduler attributes of new thread
+ policy=SCHED_RR, priority=20
+.EE
+.in
+.PP
+In the above output, one can see that the scheduling policy and priority
+were taken from the values specified in the thread attributes object.
+.PP
+The next run is the same as the previous,
+except that the inherit scheduler attribute is set to
+.BR PTHREAD_INHERIT_SCHED ,
+meaning that threads created using the thread attributes object should
+ignore the scheduling attributes specified in the attributes object
+and instead take their scheduling attributes from the creating thread.
+.PP
+.in +4n
+.EX
+# \fB./a.out \-mf10 \-ar20 \-i i\fP
+Scheduler settings of main thread
+ policy=SCHED_FIFO, priority=10
+\&
+Scheduler settings in \[aq]attr\[aq]
+ policy=SCHED_RR, priority=20
+ inheritsched is INHERIT
+\&
+Scheduler attributes of new thread
+ policy=SCHED_FIFO, priority=10
+.EE
+.in
+.PP
+In the above output, one can see that the scheduling policy and priority
+were taken from the creating thread,
+rather than the thread attributes object.
+.PP
+Note that if we had omitted the
+.I \-i\~i
+option, the output would have been the same, since
+.B PTHREAD_INHERIT_SCHED
+is the default for the inherit scheduler attribute.
+.SS Program source
+\&
+.\" SRC BEGIN (pthreads_sched_test.c)
+.EX
+/* pthreads_sched_test.c */
+\&
+#include <errno.h>
+#include <pthread.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <unistd.h>
+\&
+#define handle_error_en(en, msg) \e
+ do { errno = en; perror(msg); exit(EXIT_FAILURE); } while (0)
+\&
+static void
+usage(char *prog_name, char *msg)
+{
+ if (msg != NULL)
+ fputs(msg, stderr);
+\&
+ fprintf(stderr, "Usage: %s [options]\en", prog_name);
+ fprintf(stderr, "Options are:\en");
+#define fpe(msg) fprintf(stderr, "\et%s", msg) /* Shorter */
+ fpe("\-a<policy><prio> Set scheduling policy and priority in\en");
+ fpe(" thread attributes object\en");
+ fpe(" <policy> can be\en");
+ fpe(" f SCHED_FIFO\en");
+ fpe(" r SCHED_RR\en");
+ fpe(" o SCHED_OTHER\en");
+ fpe("\-A Use default thread attributes object\en");
+ fpe("\-i {e|i} Set inherit scheduler attribute to\en");
+ fpe(" \[aq]explicit\[aq] or \[aq]inherit\[aq]\en");
+ fpe("\-m<policy><prio> Set scheduling policy and priority on\en");
+ fpe(" main thread before pthread_create() call\en");
+ exit(EXIT_FAILURE);
+}
+\&
+static int
+get_policy(char p, int *policy)
+{
+ switch (p) {
+ case \[aq]f\[aq]: *policy = SCHED_FIFO; return 1;
+ case \[aq]r\[aq]: *policy = SCHED_RR; return 1;
+ case \[aq]o\[aq]: *policy = SCHED_OTHER; return 1;
+ default: return 0;
+ }
+}
+\&
+static void
+display_sched_attr(int policy, struct sched_param *param)
+{
+ printf(" policy=%s, priority=%d\en",
+ (policy == SCHED_FIFO) ? "SCHED_FIFO" :
+ (policy == SCHED_RR) ? "SCHED_RR" :
+ (policy == SCHED_OTHER) ? "SCHED_OTHER" :
+ "???",
+ param\->sched_priority);
+}
+\&
+static void
+display_thread_sched_attr(char *msg)
+{
+ int policy, s;
+ struct sched_param param;
+\&
+ s = pthread_getschedparam(pthread_self(), &policy, &param);
+ if (s != 0)
+ handle_error_en(s, "pthread_getschedparam");
+\&
+ printf("%s\en", msg);
+ display_sched_attr(policy, &param);
+}
+\&
+static void *
+thread_start(void *arg)
+{
+ display_thread_sched_attr("Scheduler attributes of new thread");
+\&
+ return NULL;
+}
+\&
+int
+main(int argc, char *argv[])
+{
+ int s, opt, inheritsched, use_null_attrib, policy;
+ pthread_t thread;
+ pthread_attr_t attr;
+ pthread_attr_t *attrp;
+ char *attr_sched_str, *main_sched_str, *inheritsched_str;
+ struct sched_param param;
+\&
+ /* Process command\-line options. */
+\&
+ use_null_attrib = 0;
+ attr_sched_str = NULL;
+ main_sched_str = NULL;
+ inheritsched_str = NULL;
+\&
+ while ((opt = getopt(argc, argv, "a:Ai:m:")) != \-1) {
+ switch (opt) {
+ case \[aq]a\[aq]: attr_sched_str = optarg; break;
+ case \[aq]A\[aq]: use_null_attrib = 1; break;
+ case \[aq]i\[aq]: inheritsched_str = optarg; break;
+ case \[aq]m\[aq]: main_sched_str = optarg; break;
+ default: usage(argv[0], "Unrecognized option\en");
+ }
+ }
+\&
+ if (use_null_attrib
+ && (inheritsched_str != NULL || attr_sched_str != NULL))
+ {
+ usage(argv[0], "Can\[aq]t specify \-A with \-i or \-a\en");
+ }
+\&
+ /* Optionally set scheduling attributes of main thread,
+ and display the attributes. */
+\&
+ if (main_sched_str != NULL) {
+ if (!get_policy(main_sched_str[0], &policy))
+ usage(argv[0], "Bad policy for main thread (\-m)\en");
+ param.sched_priority = strtol(&main_sched_str[1], NULL, 0);
+\&
+ s = pthread_setschedparam(pthread_self(), policy, &param);
+ if (s != 0)
+ handle_error_en(s, "pthread_setschedparam");
+ }
+\&
+ display_thread_sched_attr("Scheduler settings of main thread");
+ printf("\en");
+\&
+ /* Initialize thread attributes object according to options. */
+\&
+ attrp = NULL;
+\&
+ if (!use_null_attrib) {
+ s = pthread_attr_init(&attr);
+ if (s != 0)
+ handle_error_en(s, "pthread_attr_init");
+ attrp = &attr;
+ }
+\&
+ if (inheritsched_str != NULL) {
+ if (inheritsched_str[0] == \[aq]e\[aq])
+ inheritsched = PTHREAD_EXPLICIT_SCHED;
+ else if (inheritsched_str[0] == \[aq]i\[aq])
+ inheritsched = PTHREAD_INHERIT_SCHED;
+ else
+ usage(argv[0], "Value for \-i must be \[aq]e\[aq] or \[aq]i\[aq]\en");
+\&
+ s = pthread_attr_setinheritsched(&attr, inheritsched);
+ if (s != 0)
+ handle_error_en(s, "pthread_attr_setinheritsched");
+ }
+\&
+ if (attr_sched_str != NULL) {
+ if (!get_policy(attr_sched_str[0], &policy))
+ usage(argv[0], "Bad policy for \[aq]attr\[aq] (\-a)\en");
+ param.sched_priority = strtol(&attr_sched_str[1], NULL, 0);
+\&
+ s = pthread_attr_setschedpolicy(&attr, policy);
+ if (s != 0)
+ handle_error_en(s, "pthread_attr_setschedpolicy");
+ s = pthread_attr_setschedparam(&attr, &param);
+ if (s != 0)
+ handle_error_en(s, "pthread_attr_setschedparam");
+ }
+\&
+ /* If we initialized a thread attributes object, display
+ the scheduling attributes that were set in the object. */
+\&
+ if (attrp != NULL) {
+ s = pthread_attr_getschedparam(&attr, &param);
+ if (s != 0)
+ handle_error_en(s, "pthread_attr_getschedparam");
+ s = pthread_attr_getschedpolicy(&attr, &policy);
+ if (s != 0)
+ handle_error_en(s, "pthread_attr_getschedpolicy");
+\&
+ printf("Scheduler settings in \[aq]attr\[aq]\en");
+ display_sched_attr(policy, &param);
+\&
+ pthread_attr_getinheritsched(&attr, &inheritsched);
+ printf(" inheritsched is %s\en",
+ (inheritsched == PTHREAD_INHERIT_SCHED) ? "INHERIT" :
+ (inheritsched == PTHREAD_EXPLICIT_SCHED) ? "EXPLICIT" :
+ "???");
+ printf("\en");
+ }
+\&
+ /* Create a thread that will display its scheduling attributes. */
+\&
+ s = pthread_create(&thread, attrp, &thread_start, NULL);
+ if (s != 0)
+ handle_error_en(s, "pthread_create");
+\&
+ /* Destroy unneeded thread attributes object. */
+\&
+ if (!use_null_attrib) {
+ s = pthread_attr_destroy(&attr);
+ if (s != 0)
+ handle_error_en(s, "pthread_attr_destroy");
+ }
+\&
+ s = pthread_join(thread, NULL);
+ if (s != 0)
+ handle_error_en(s, "pthread_join");
+\&
+ exit(EXIT_SUCCESS);
+}
+.EE
+.\" SRC END
+.SH SEE ALSO
+.ad l
+.nh
+.BR getrlimit (2),
+.BR sched_get_priority_min (2),
+.BR pthread_attr_init (3),
+.BR pthread_attr_setinheritsched (3),
+.BR pthread_attr_setschedparam (3),
+.BR pthread_attr_setschedpolicy (3),
+.BR pthread_create (3),
+.BR pthread_self (3),
+.BR pthread_setschedprio (3),
+.BR pthreads (7),
+.BR sched (7)