Index Index for
Section 3
Index Alphabetical
listing for P
Bottom of page Bottom of
page		 

pthread_use_only_cpu(3)


NAME

  pthread_use_only_cpu - Restricts a thread to running only on the specified
  CPU. If that CPU is unavailable for any reason, the thread will not run


SYNOPSIS

  #include <cpuset.h>
  #include <sys/types.h>

  int pthread_use_only_cpu(
	  pthread_t thread,
	  cpuid_t cpu_id,
	  long flag );


LIBRARY

  DECthreads POSIX 1003.1c Library (libpthread.so)


PARAMETERS

  thread
      Thread to be restricted to use only the specified CPU.

  flag
      Currently only PTHREAD_BINDCPU_INFLEXIBLE is defined, and must be
      specified.


DESCRIPTION

  This routine restricts thread to cpu_id, preventing the thread from
  utilizing any other available processor resources even when cpu_id may be
  busy for an extended time with other work or is otherwise unavailable.

  This function can be used only with System Contention Scope (SCS) threads,
  that is, threads that were created using an attributes object with the
  scope attribute set to PTHREAD_SCOPE_SYSTEM.

  Specifying a cpu_id value of CPU_NONE removes the restriction from the
  thread, allowing it to again take advantage of any available CPU when the
  CPU on which it last ran is busy.

  cpu_id will become unavailable if the corresponding CPU is removed from the
  processor set in which the process is running or if it is taken off-line.
  In this event, any thread that is restricted to cpu_id will not run until
  pthread_use_only_cpu is called from another thread to change or remove the
  thread's restriction.

  Threads that have not been restricted to a specific CPU using this function
  are typically scheduled to run on the CPU they last used, in order to take
  advantage of valid cache and translation buffer (TB) entries. However, if
  that CPU remains busy with other work, the threads may instead be run on
  another CPU if available. This default behavior is the most effective
  except in extremely unusual circumstances, so this function should be used
  only with great caution.  Improper use of this function can substantially
  degrade application performance; proper use will rarely improve performance
  measurably (if at all).

  This routine does not prevent cpu_id from performing other work.
  Restricting a thread to a CPU is rarely beneficial to an application since
  other threads of equal or higher priority may be run by cpu_id, and, in
  addition to preventing thread from executing, this activity will likely
  invalidate cache and TB entries used by thread, thereby removing the
  principal advantages of having restricted the thread. Furthermore, giving a
  thread a very high priority is not sufficient to guarantee exclusive use of
  a CPU since page faults, interrupts, or blocking system calls of even very
  short duration can permit other threads to obtain the CPU. To obtain
  exclusive use of a CPU, see the processor_sets(4) reference page.


RETURN VALUES

  If an error condition occurs, the target thread's scheduling restrictions
  remain unchanged, and this routine returns an integer value indicating the
  type of error. Possible return values are as follows:

  0   Successful completion.

  [EINVAL]
      The value specified by cpu_id is invalid, or the flag is invalid.

  [ENOTSUP]
      The specified thread is a Process Contention Scope thread.

  [ESRCH]
      The specified thread does not exist.


ERRORS

  None


SEE ALSO

  Functions: pthread_create(3), pthread_attr_init(3),
  pthread_attr_setscope(3), pthread_rad_bind(3) pthread_rad_attach(3),
  processor_sets(3)

  Manuals: Guide to DECthreads and Programmer's Guide

Index Index for
Section 3
Index Alphabetical
listing for P
Top of page Top of
page