Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
hwlocality_cpubinding(3)   Library Functions Manual   hwlocality_cpubinding(3)

NAME
       hwlocality_cpubinding - CPU binding

SYNOPSIS
   Enumerations
       enum hwloc_cpubind_flags_t { HWLOC_CPUBIND_PROCESS,
	   HWLOC_CPUBIND_THREAD, HWLOC_CPUBIND_STRICT, HWLOC_CPUBIND_NOMEMBIND
	   }

   Functions
       int hwloc_set_cpubind (hwloc_topology_t topology, hwloc_const_cpuset_t
	   set,	int flags)
       int hwloc_get_cpubind (hwloc_topology_t topology, hwloc_cpuset_t	set,
	   int flags)
       int hwloc_set_proc_cpubind (hwloc_topology_t topology, hwloc_pid_t pid,
	   hwloc_const_cpuset_t	set, int flags)
       int hwloc_get_proc_cpubind (hwloc_topology_t topology, hwloc_pid_t pid,
	   hwloc_cpuset_t set, int flags)
       int hwloc_set_thread_cpubind (hwloc_topology_t topology,	hwloc_thread_t
	   thread, hwloc_const_cpuset_t	set, int flags)
       int hwloc_get_thread_cpubind (hwloc_topology_t topology,	hwloc_thread_t
	   thread, hwloc_cpuset_t set, int flags)
       int hwloc_get_last_cpu_location (hwloc_topology_t topology,
	   hwloc_cpuset_t set, int flags)
       int hwloc_get_proc_last_cpu_location (hwloc_topology_t topology,
	   hwloc_pid_t pid, hwloc_cpuset_t set,	int flags)

Detailed Description
       Some operating systems only support binding threads or processes	to a
       single PU. Others allow binding to larger sets such as entire Cores or
       Packages	or even	random sets of individual PUs. In such operating
       system, the scheduler is	free to	run the	task on	one of these PU, then
       migrate it to another PU, etc. It is often useful to call
       hwloc_bitmap_singlify() on the target CPU set before passing it to the
       binding function	to avoid these expensive migrations. See the
       documentation of	hwloc_bitmap_singlify()	for details.

       Some operating systems do not provide all hwloc-supported mechanisms to
       bind processes, threads,	etc. hwloc_topology_get_support() may be used
       to query	about the actual CPU binding support in	the currently used
       operating system.

       When the	requested binding operation is not available and the
       HWLOC_CPUBIND_STRICT flag was passed, the function returns -1. errno is
       set to ENOSYS when it is	not possible to	bind the requested kind	of
       object processes/threads. errno is set to EXDEV when the	requested
       cpuset can not be enforced (e.g.	some systems only allow	one CPU, and
       some other systems only allow one NUMA node).

       If HWLOC_CPUBIND_STRICT was not passed, the function may	fail as	well,
       or the operating	system may use a slightly different operation (with
       side-effects, smaller binding set, etc.)	when the requested operation
       is not exactly supported.

       The most	portable version that should be	preferred over the others,
       whenever	possible, is the following one which just binds	the current
       program,	assuming it is single-threaded:

       hwloc_set_cpubind(topology, set,	0),

       If the program may be multithreaded, the	following one should be
       preferred to only bind the current thread:

       hwloc_set_cpubind(topology, set,	HWLOC_CPUBIND_THREAD),

       See also
	   Some	example	codes are available under doc/examples/	in the source
	   tree.

       Note
	   To unbind, just call	the binding function with either a full	cpuset
	   or a	cpuset equal to	the system cpuset.

	   On some operating systems, CPU binding may have effects on memory
	   binding, see	HWLOC_CPUBIND_NOMEMBIND

	   Running lstopo --top	or hwloc-ps can	be a very convenient tool to
	   check how binding actually happened.

Enumeration Type Documentation
   enum	hwloc_cpubind_flags_t
       Process/Thread binding flags. These bit flags can be used to refine the
       binding policy.

       The default (0) is to bind the current process, assumed to be single-
       threaded, in a non-strict way. This is the most portable	way to bind as
       all operating systems usually provide it.

       Note
	   Not all systems support all kinds of	binding. See the 'Detailed
	   Description'	section	of CPU binding for a description of errors
	   that	can occur.

       Enumerator

       HWLOC_CPUBIND_PROCESS
	      Bind   all  threads  of  the  current  (possibly)	 multithreaded
	      process.

       HWLOC_CPUBIND_THREAD
	      Bind current thread of current process.

       HWLOC_CPUBIND_STRICT
	      Request for strict binding from the OS.  By  default,  when  the
	      designated  CPUs	are  all  busy	while  other  CPUs  are	 idle,
	      operating	systems	may execute the	thread/process on those	 other
	      CPUs  instead  of	 the  designated  CPUs,	 to  let them progress
	      anyway.  Strict  binding	means  that  the  thread/process  will
	      _never_  execute	on  other  CPUs	than the designated CPUs, even
	      when those are busy with other tasks and other CPUs are idle.

       Note
	   Depending on	the  operating	system,	 strict	 binding  may  not  be
	   possible (e.g., the OS does not implement it) or not	allowed	(e.g.,
	   for	an administrative reasons), and	the function will fail in that
	   case.

       When retrieving the binding of a	process, this flag checks whether  all
       its  threads  actually have the same binding. If	the flag is not	given,
       the binding of each thread will be accumulated.

       Note
	   This	flag is	meaningless when retrieving the	binding	of a thread.

       HWLOC_CPUBIND_NOMEMBIND
	      Avoid any	effect on memory binding. On some  operating  systems,
	      some  CPU	 binding  function  would  also	bind the memory	on the
	      corresponding NUMA node. It is  often  not  a  problem  for  the
	      application,  but	 if  it	 is, setting this flag will make hwloc
	      avoid using OS functions that would also bind memory. This  will
	      however  reduce  the  support  of	CPU bindings, i.e. potentially
	      return -1	with errno set to ENOSYS in some cases.

       This flag is only meaningful when used with functions that set the  CPU
       binding.	 It  is	 ignored when used with	functions that get CPU binding
       information.

Function Documentation
   int hwloc_get_cpubind (hwloc_topology_t topology, hwloc_cpuset_t  set,  int
       flags)
       Get  current  process  or  thread  binding. The CPU-set set (previously
       allocated by the	caller)	is filled with	the  list  of  PUs  which  the
       process or thread (according to flags) was last bound to.

       Returns
	   0 on	success, -1 on error.

   int	hwloc_get_last_cpu_location (hwloc_topology_t topology,	hwloc_cpuset_t
       set, int	flags)
       Get the last physical CPU where the current process or thread ran.  The
       CPU-set	set  (previously  allocated  by	the caller) is filled with the
       list of PUs which the process or	thread (according to flags)  last  ran
       on.

       The  operating system may move some tasks from one processor to another
       at any time according to	their binding, so  this	 function  may	return
       something that is already outdated.

       flags  can include either HWLOC_CPUBIND_PROCESS or HWLOC_CPUBIND_THREAD
       to specify whether the query should be for the whole process (union  of
       all CPUs	on which all threads are running), or only the current thread.
       If  the	process	 is  single-threaded,  flags can be set	to zero	to let
       hwloc use whichever method is available on the underlying OS.

       Returns
	   0 on	success, -1 on error.

   int hwloc_get_proc_cpubind  (hwloc_topology_t  topology,  hwloc_pid_t  pid,
       hwloc_cpuset_t set, int flags)
       Get  the	 current  physical  binding  of	 process  pid. The CPU-set set
       (previously allocated by	the caller) is filled with  the	 list  of  PUs
       which the process was last bound	to.

       Returns
	   0 on	success, -1 on error.

       Note
	   hwloc_pid_t	is  pid_t  on  Unix  platforms,	 and  HANDLE on	native
	   Windows platforms.

	   As a	special	case on	Linux,	if  a  tid  (thread  ID)  is  supplied
	   instead of a	pid (process ID) and HWLOC_CPUBIND_THREAD is passed in
	   flags, the binding for that specific	thread is returned.

	   On  non-Linux  systems,  HWLOC_CPUBIND_THREAD  can  not  be used in
	   flags.

   int	  hwloc_get_proc_last_cpu_location     (hwloc_topology_t     topology,
       hwloc_pid_t pid,	hwloc_cpuset_t set, int	flags)
       Get  the	 last  physical	 CPU  where  a	process	 ran.  The CPU-set set
       (previously allocated by	the caller) is filled with  the	 list  of  PUs
       which the process last ran on.

       The  operating system may move some tasks from one processor to another
       at any time according to	their binding, so  this	 function  may	return
       something that is already outdated.

       Returns
	   0 on	success, -1 on error.

       Note
	   hwloc_pid_t	is  pid_t  on  Unix  platforms,	 and  HANDLE on	native
	   Windows platforms.

	   As a	special	case on	Linux,	if  a  tid  (thread  ID)  is  supplied
	   instead of a	pid (process ID) and HWLOC_CPUBIND_THREAD is passed in
	   flags, the last CPU location	of that	specific thread	is returned.

	   On  non-Linux  systems,  HWLOC_CPUBIND_THREAD  can  not  be used in
	   flags.

   int	hwloc_get_thread_cpubind  (hwloc_topology_t  topology,	hwloc_thread_t
       thread, hwloc_cpuset_t set, int flags)
       Get  the	 current  physical  binding  of	 thread	 tid.  The CPU-set set
       (previously allocated by	the caller) is filled with  the	 list  of  PUs
       which the thread	was last bound to.

       Returns
	   0 on	success, -1 on error.

       Note
	   hwloc_thread_t is pthread_t on Unix platforms, and HANDLE on	native
	   Windows platforms.

	   HWLOC_CPUBIND_PROCESS can not be used in flags.

   int hwloc_set_cpubind (hwloc_topology_t topology, hwloc_const_cpuset_t set,
       int flags)
       Bind current process or thread on CPUs given in physical	bitmap set.

       Returns
	   0 on	success.

	   -1 with errno set to	ENOSYS if the action is	not supported.

	   -1 with errno set to	EXDEV if the binding cannot be enforced.

   int	hwloc_set_proc_cpubind	(hwloc_topology_t  topology,  hwloc_pid_t pid,
       hwloc_const_cpuset_t set, int flags)
       Bind a process pid on CPUs given	in physical bitmap set.

       Returns
	   0 on	success, -1 on error.

       Note
	   hwloc_pid_t is pid_t	 on  Unix  platforms,  and  HANDLE  on	native
	   Windows platforms.

	   As  a  special  case	 on  Linux,  if	 a tid (thread ID) is supplied
	   instead of a	pid (process ID) and HWLOC_CPUBIND_THREAD is passed in
	   flags, the binding is applied to that specific thread.

	   On non-Linux	systems,  HWLOC_CPUBIND_THREAD	can  not  be  used  in
	   flags.

   int	hwloc_set_thread_cpubind  (hwloc_topology_t  topology,	hwloc_thread_t
       thread, hwloc_const_cpuset_t set, int flags)
       Bind a thread thread on CPUs given in physical bitmap set.

       Returns
	   0 on	success, -1 on error.

       Note
	   hwloc_thread_t is pthread_t on Unix platforms, and HANDLE on	native
	   Windows platforms.

	   HWLOC_CPUBIND_PROCESS can not be used in flags.

Author
       Generated automatically by Doxygen for Hardware Locality	 (hwloc)  from
       the source code.

Hardware Locality (hwloc)	Version	2.11.2	      hwlocality_cpubinding(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=hwloc_get_proc_last_cpu_location&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help