pthread_attr_setscope(3P)

NAME
     pthread_attr_setscope, pthread_attr_getscope - thread scheduling scope
     attributes

C SYNOPSIS
     #include <pthread.h>

     int pthread_attr_setscope(pthread_attr_t *attr, int scope);
     int pthread_attr_getscope(const pthread_attr_t *attr, int *oscope);

DESCRIPTION
     The pthread_attr_setscope() function sets the thread scheduling scope
     attribute in the object attr to the value scope.  Possible values for
     scope are PTHREAD_SCOPE_SYSTEM, PTHREAD_SCOPE_BOUND_NP and
     PTHREAD_SCOPE_PROCESS.  The scheduling scope for the attribute object
     attr, is returned via the oscope parameter of pthread_attr_getscope().
     The default scheduling scope is PTHREAD_SCOPE_PROCESS.

     Threads created with system scope have a direct effect on scheduling by
     the kernel [see pthread_attr_setschedpolicy() and
     pthread_attr_setschedparam()].  System scope threads are therefore
     suitable for real-time applications [see realtime].  For example a system
     scope thread may run at a higher priority than interrupt threads and
     system daemons.  Creation of system scope threads requires the
     CAP_SCHED_MGT capability [see capability].

     Threads created with bound scope are scheduled with respect to the
     process in which they are created. Creating bound scope threads does not
     require any special capability. Each bound scope thread executes on a
     separate kernel execution vehicle. The scheduling policy of these kernel
     execution vehicles is determined by the scheduling policy of the process.
     These execution vehicles share a single set of kernel scheduling
     characteristics.  The scheduling attributes of bound scope threads within
     the process are controlled by thread-based scheduling attributes [see
     pthread_attr_setschedpolicy() and pthread_attr_setschedparam()].

     Threads created with process scope are scheduled with respect to the
     other process scope pthreads in the process in which they are created
     (that is, they are scheduled in user space by the library).  Creating
     process scope threads does not require any special capability.  Although
     the scheduling attributes [see pthread_attr_setschedpolicy() and
     pthread_attr_setschedparam()] of these threads do not affect scheduling
     by the kernel, process scope threads execute on a (usually smaller) pool
     of kernel execution vehicles [see pthread_setconcurrency()].  The
     scheduling policy of these kernel execution vehicles is determined by the
     scheduling policy of the process. These execution vehicles share a single
     set of kernel scheduling characteristics.

     Scheduling scope makes a big difference to the effect of thread
     scheduling, particularly with respect to priority.  For example, a
     process scope thread with maximum priority merely executes in preference
     to other threads within its process.  However a thread with the same
     scheduling policy and priority running with system scope runs in
     preference to other threads and processes on the machine; such a thread
     may run instead of system threads and daemons and seriously affect the
     operation of the host.

DIAGNOSTICS
     On success pthread_attr_setscope() returns zero; otherwise an error
     number is returned:

     [EINVAL]       The value of scope is not PTHREAD_SCOPE_SYSTEM,
                    PTHREAD_SCOPE_BOUND_NP or PTHREAD_SCOPE_PROCESS.

     [EPERM]        The value of scope is PTHREAD_SCOPE_SYSTEM and the process
                    lacks the CAP_SCHED_MGT capability.

     pthread_attr_getscope() always returns zero.

SEE ALSO
     capability(4), pthread_attr_init(3P), pthread_attr_setschedparam(3P),
     pthread_attr_setschedpolicy(3P), pthread_create(3P),
     pthread_setconcurrency(3P), realtime(5), sched_setparam(2),
     sched_setscheduler(2).