Re: For review: pthread_setschedparam.3

[Loic Domaigne <tech-Z4JMKDdsf89Wk0Htik3J/w@public.gmane.org>]

Hallo Michael,

enclosed my review comments.

Regards,
Loïc.
--

> .\" Copyright (c) 2008 Linux Foundation, written by Michael Kerrisk
> .\"     <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
> .\"
> .\" Permission is granted to make and distribute verbatim copies of this
> .\" manual provided the copyright notice and this permission notice are
> .\" preserved on all copies.
> .\"
> .\" Permission is granted to copy and distribute modified versions of this
> .\" manual under the conditions for verbatim copying, provided that the
> .\" entire resulting derived work is distributed under the terms of a
> .\" permission notice identical to this one.
> .\"
> .\" Since the Linux kernel and libraries are constantly changing, this
> .\" manual page may be incorrect or out-of-date.  The author(s) assume no
> .\" responsibility for errors or omissions, or for damages resulting from
> .\" the use of the information contained herein.  The author(s) may not
> .\" have taken the same level of care in the production of this manual,
> .\" which is licensed free of charge, as they might when working
> .\" professionally.
> .\"
> .\" Formatted or processed versions of this manual, if unaccompanied by
> .\" the source, must acknowledge the copyright and authors of this work.
> .\"
> .TH PTHREAD_SETSCHEDPARAM 3 2008-11-07 "Linux" "Linux Programmer's Manual"
> .SH NAME
> pthread_setschedparam, pthread_setschedparam \- set/get
> scheduling policy and parameters of a thread
> .SH SYNOPSIS
> .nf
> .B #include <pthread.h>
> 
> .BI "pthread_setschedparam(pthread_t " thread ", int " policy ,
> .BI "                      const struct sched_param *" param );
> .BI "pthread_getschedparam(pthread_t " thread ", int *" policy ,
> .BI "                      struct sched_param *" param );
> .sp
> Compile and link with \fI\-pthread\fP.

One question regarding the synopsis. Is there a reason with the 
"restrict" keyword is not used for pthread_getschedparam(). Accordingly 
to /usr/include/pthread.h:

extern int pthread_getschedparam (pthread_t __target_thread,
                                   int *__restrict __policy,
                                   struct sched_param *__restrict __param);


> .SH DESCRIPTION
> The
> .BR pthread_setschedparam ()
> function sets the scheduling policy and parameters of the thread
> .IR thread .
> 
> .I policy
> specifies the new scheduling policy for
> .IR thread .
> The supported values for
> .IR policy ,
> and their semantics, are described in
> .BR sched_setscheduler (2).
> .\" 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

Perhaps it's my poor english... But why "new scheduling policy"? I may 
just want to change the priority, within the same scheduling policy...

> The structure pointed to by
> .I param
> specifies the new scheduling parameters for
> .IR thread .

Similar comment here. I may just want to change the scheduling policy, 
without changing the priority. ( I admit, this one is seldom compared to 
the previous one ).

> Scheduling parameters are maintained in the following structure:
> 
> .in +4n
> .nf
> struct sched_param {
>     int sched_priority;     /* Scheduling priority */
> };
> .fi
> .in
> 
> As can be seen, only one scheduling parameter is supported
> (this is the only parameter specified by POSIX.1-2001.)

No, it think this is not correct? If a system support SCHED_SPORADIC, 
then the sched_param structure has additional fields.


> For details of the permitted ranges for scheduling priorities
> in each scheduling policy, see
> .BR sched_setscheduler (2).

> 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 .

Hmm, that's perfectly right from a POSIX point of view. Knowing how 
Linux implements threads, I have been interested about the effect of 
sched_setscheduler() on a MT-process (since NPTL uses 1:1 model, this 
should be a NOP).

I tested the following program against the stable glibc-2.7... 
Apparently, it seems that sched_setscheduler() might affect the main 
thread priority as well.

--
#include <stdio.h>
#include <pthread.h>
#include <sched.h>
#include <unistd.h>

void
print_schedinfo(const char* thread)
{
    struct sched_param param;
    int policy;
    int rc;

    rc = pthread_getschedparam(pthread_self(), &policy, &param);
    if (rc!=0) printf("##%d\n", rc);
    printf("%s > Policy=%s, prio=%d\n",
           thread,
           (policy==SCHED_FIFO) ? "FIFO" : "*NOT* FIFO",
	  param.sched_priority);
}

// dummy thread...
//
void*
thread(void* ignore)
{
    sleep(3);
    print_schedinfo("dummy thread");
    pthread_exit(NULL);
}

int
main()
{
    struct sched_param param;
    int    policy;
    int    rc;
    pthread_t tid;

    // create dummy thread
    //
    pthread_create(&tid, NULL, thread, NULL);
    param.sched_priority=1;

    // now we shall change the process policy/prio using
    // sched_setscheduler().
    // Normally: this should be a NOP. But due to the way Linux
    // implements threads, I am suspecting that this shall affect
    // the main thread
    //
    rc=sched_setscheduler(0, SCHED_FIFO, &param);
    if (rc==-1) printf("sched_setscheduler FAILED\n");

    // print my scheduling info
    //
    print_schedinfo("main");

    // join dummy thread and terminate
    //
    pthread_join(tid, NULL);
    return 0;
}

--

> 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.

If I understood correctly, the thread can't lower the priority that he 
has resulting from priority inheritance/ceiling. That makes perfectly 
sense to me, otherwise this could defeat the purpose of such schemes, 
among others avoiding priority inversion.

> .SH RETURN VALUE
> On success, these functions return 0;
> on error, they return a non-zero error number.
> If
> .BR pthread_setschedparam ()
> fails, the scheduling policy and parameters of
> .I thread
> are not changed.
> .SH ERRORS
> Both of these functions may fail with the following error:
> .TP
> .B ESRCH
> No thread with the ID
> .I thread
> could be found.

Should the ERSCH error description be consistent across pthread_* linux
man-pages? See for instance pthread_attr_setaffinity_np().

> .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 .

I got troubled by the "may additionally", as "may" has a particular 
meaning in POSIX.1...

But I guess, you just want to express that pthread_setschedparam() shall 
fail if the policy or the param is invalid, right?

> .TP
> .B EPERM
> The caller does not have appropriate privileges
> .RB ( CAP_SYS_NICE )
> to set the specified scheduling policy and parameters.
> See
> .BR sched_setscheduler (2)
> for more details on what scheduling changes require privileges.
> .PP
> POSIX.1-2001 also documents an
> .B ENOTSUP
> ("attempt was made to set the policy or scheduling parameters
> to an unsupported value") error for
> .BR pthread_setschedparam ().

... but it doesn't seem to be used by Linux/Glibc...

> .\" .SH VERSIONS
> .\" Available since glibc 2.0
> .SH CONFORMING TO
> POSIX.1-2001.
> .SH NOTES
> See
> .BR sched_setscheduler (2)
> for a description of the effect of changing a thread's
> scheduling policy and priority.
> .SH EXAMPLE
> 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.
> 
> In the following run, the main thread sets its scheduling policy to
> .BR SCHED_FIFO
> with a priority of 10,
> and initializes a thread attributes object with
> a scheduling policy attribute of
> .BR 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.
> .in +4n
> .nf
> 
> $ \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 \(aqattr\(aq
>     policy=SCHED_RR, priority=20
>     inheritsched is EXPLICIT
> 
> Scheduler attributes of new thread
>     policy=SCHED_RR, priority=20
> .fi
> .in
> 
> In the above output, one can see that the scheduling policy and priority
> were taken from the values specified in the thread attributes object.
> 
> 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.
> 
> .in +4n
> .nf
> # \fB./a.out \-mf10 \-ar20 \-i i\fP
> Scheduler settings of main thread
>     policy=SCHED_FIFO, priority=10
> 
> Scheduler settings in \(aqattr\(aq
>     policy=SCHED_RR, priority=20
>     inheritsched is INHERIT
> 
> Scheduler attributes of new thread
>     policy=SCHED_FIFO, priority=10
> .fi
> .in
> 
> 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.

A classical trap is that people don't set inheritsched to explicit, and 
by default it is inherit... You could illustrate this by the following 
example: ./a.out -mf10 -ar20.

( I don't know however if it is the right place to speak about such 
things ).


> .SS Program source
> \&
> .nf
> /* pthreads_sched_test.c */
> 
> #include <pthread.h>
> #include <stdio.h>
> #include <stdlib.h>
> #include <unistd.h>
> #include <errno.h>
> 
> /* Simple error handling functions */
> 
> #define errExit(msg)            { perror(msg); exit(EXIT_FAILURE); }
> 
> #define errExitEN(en, msg)      { errno = en; perror(msg); \\
>                                   exit(EXIT_FAILURE); }
> 
> static void
> usage(char *prog_name, char *msg)
> {
>     if (msg != NULL)
>         fputs(msg, stderr);
> 
>     fprintf(stderr, "Usage: %s [options]\\n", prog_name);
>     fprintf(stderr, "Options are:\\n");
> #define fpe(msg) fprintf(stderr, "\\t%s", msg);          /* Shorter */
>     fpe("\-a<policy><prio> Set scheduling policy and priority in\\n");
>     fpe("                 thread attributes object\\n");
>     fpe("                 <policy> can be\\n");
>     fpe("                     f  SCHED_FIFO\\n");
>     fpe("                     r  SCHED_RR\\n");
>     fpe("                     o  SCHED_OTHER\\n");
>     fpe("\-A               Use default thread attributes object\\n");
>     fpe("\-i {e|s}         Set inherit scheduler attribute to\\n");
>     fpe("                 \(aqexplicit\(aq or \(aqinherit\(aq\\n");
>     fpe("\-m<policy><prio> Set scheduling policy and priority on\\n");
>     fpe("                 main thread before pthread_create() call\\n");
>     exit(EXIT_FAILURE);
> } /* usage */
> 
> static int
> get_policy(char p, int *policy)
> {
>     switch (p) {
>     case \(aqf\(aq: *policy = SCHED_FIFO;     return 1;
>     case \(aqr\(aq: *policy = SCHED_RR;       return 1;
>     case \(aqo\(aq: *policy = SCHED_OTHER;    return 1;
>     default:  return 0;
>     }
> } /* get_policy */
> 
> static void
> display_sched_attr(int policy, struct sched_param *param)
> {
>     printf("    policy=%s, priority=%d\\n",
>             (policy == SCHED_FIFO)  ? "SCHED_FIFO" :
>             (policy == SCHED_RR)    ? "SCHED_RR" :
>             (policy == SCHED_OTHER) ? "SCHED_OTHER" :
>             "???",
>             param\->sched_priority);
> } /* display_sched_attr */
> 
> 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)
>         errExitEN(s, "pthread_getschedparam");
> 
>     printf("%s\\n", msg);
>     display_sched_attr(policy, &param);
> } /* display_thread_sched_attr */
> 
> static void *
> thread_start(void *arg)
> {
>     display_thread_sched_attr("Scheduler attributes of new thread");
> 
>     return NULL;
> } /* thread_start */
> 
> 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 \(aqa\(aq: attr_sched_str = optarg;      break;
>         case \(aqA\(aq: use_null_attrib = 1;          break;
>         case \(aqi\(aq: inheritsched_str = optarg;    break;
>         case \(aqm\(aq: main_sched_str = optarg;      break;
>         default:  usage(argv[0], "Unrecognized option\\n");
>         }
>     }
> 
>     if (use_null_attrib &&
>             (inheritsched_str != NULL || attr_sched_str != NULL))
>         usage(argv[0], "Can\(aqt specify \-A with \-i or \-a\\n");
> 
>     /* 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 (\-s)\\n");
>         param.sched_priority = strtol(&main_sched_str[1], NULL, 0);
> 
>         s = pthread_setschedparam(pthread_self(), policy, &param);
>         if (s != 0)
>             errExitEN(s, "pthread_setschedparam");
>     }
> 
>     display_thread_sched_attr("Scheduler settings of main thread");
>     printf("\\n");
> 
>     /* Initialize thread attributes object according to options */
> 
>     attrp = NULL;
> 
>     if (!use_null_attrib) {
>         s = pthread_attr_init(&attr);
>         if (s != 0)
>             errExitEN(s, "pthread_attr_init");
>         attrp = &attr;
>     }
> 
>     if (inheritsched_str != NULL) {
>         if (inheritsched_str[0] == \(aqe\(aq)
>             inheritsched = PTHREAD_EXPLICIT_SCHED;
>         else if (inheritsched_str[0] == \(aqi\(aq)
>             inheritsched = PTHREAD_INHERIT_SCHED;
>         else
>             usage(argv[0], "Value for \-i must be \(aqe\(aq or \(aqi\(aq\\n");
> 
>         s = pthread_attr_setinheritsched(&attr, inheritsched);
>         if (s != 0)
>             errExitEN(s, "pthread_attr_setinheritsched");
>     }
> 
>     if (attr_sched_str != NULL) {
>         if (!get_policy(attr_sched_str[0], &policy))
>             usage(argv[0],
>                     "Bad policy for \(aqattr\(aq (\-a)\\n");
>         param.sched_priority = strtol(&attr_sched_str[1], NULL, 0);
> 
>         s = pthread_attr_setschedpolicy(&attr, policy);
>         if (s != 0)
>             errExitEN(s, "pthread_attr_setschedpolicy");
>         s = pthread_attr_setschedparam(&attr, &param);
>         if (s != 0)
>             errExitEN(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)
>             errExitEN(s, "pthread_attr_getschedparam");
>         s = pthread_attr_getschedpolicy(&attr, &policy);
>         if (s != 0)
>             errExitEN(s, "pthread_attr_getschedpolicy");
> 
>         printf("Scheduler settings in \(aqattr\(aq\\n");
>         display_sched_attr(policy, &param);
> 
>         s = pthread_attr_getinheritsched(&attr, &inheritsched);
>         printf("    inheritsched is %s\\n",
>                 (inheritsched == PTHREAD_INHERIT_SCHED)  ? "INHERIT" :
>                 (inheritsched == PTHREAD_EXPLICIT_SCHED) ? "EXPLICIT" :
>                 "???");
>         printf("\\n");
>     }
> 
>     /* Create a thread that will display its scheduling attributes */
> 
>     s = pthread_create(&thread, attrp, &thread_start, NULL);
>     if (s != 0)
>         errExitEN(s, "pthread_create");
> 
>     /* Destroy unneeded thread attributes object */
> 
>     s = pthread_attr_destroy(&attr);
>     if (s != 0)
>         errExitEN(s, "pthread_attr_destroy");
> 
>     s = pthread_join(thread, NULL);
>     if (s != 0)
>         errExitEN(s, "pthread_join");
> 
>     exit(EXIT_SUCCESS);
> } /* main */
> .fi
> .SH SEE ALSO
> .BR sched_get_priority_min (2),
> .BR sched_setscheduler (2),
> .BR pthread_attr_init (3),
> .BR pthread_attr_setinheritsched (3),
> .BR pthread_attr_setschedparam (3),
> .BR pthread_attr_setschedpolicy (3),
> .BR pthread_setschedprio (3),
> .BR pthread_create (3),
> .BR pthread_self (3),
> .BR pthreads (7)
> 
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html