The Cpuset API

Defines
#define	hwloc_cpuset_foreach_begin(cpu, set)
	Loop macro iterating on CPU set set.
#define	hwloc_cpuset_foreach_end()
	End of loop. Needs a terminating ';'.
Typedefs
typedef struct hwloc_cpuset_s *	hwloc_cpuset_t
	Set of CPUs represented as an opaque pointer to an internal bitmask.
typedef struct hwloc_cpuset_s *	hwloc_const_cpuset_t
Functions
hwloc_cpuset_t	hwloc_cpuset_alloc (void)
	Allocate a new empty CPU set.
void	hwloc_cpuset_free (hwloc_cpuset_t set)
	Free CPU set set.
hwloc_cpuset_t	hwloc_cpuset_dup (hwloc_const_cpuset_t set)
	Duplicate CPU set set by allocating a new CPU set and copying set's contents.
void	hwloc_cpuset_copy (hwloc_cpuset_t dst, hwloc_const_cpuset_t src)
	Copy the contents of CPU set src into the already allocated CPU set dst.
int	hwloc_cpuset_snprintf (char *restrict buf, size_t buflen, hwloc_const_cpuset_t set)
	Stringify a cpuset.
int	hwloc_cpuset_asprintf (char **strp, hwloc_const_cpuset_t set)
	Stringify a cpuset into a newly allocated string.
int	hwloc_cpuset_from_string (hwloc_cpuset_t set, const char *restrict string)
	Parse a cpuset string and stores it in CPU set set.
void	hwloc_cpuset_zero (hwloc_cpuset_t set)
	Empty the CPU set set.
void	hwloc_cpuset_fill (hwloc_cpuset_t set)
	Fill CPU set set with all possible CPUs (even if those CPUs don't exist or are otherwise unavailable).
void	hwloc_cpuset_from_ulong (hwloc_cpuset_t set, unsigned long mask)
	Setup CPU set set from unsigned long mask.
void	hwloc_cpuset_from_ith_ulong (hwloc_cpuset_t set, unsigned i, unsigned long mask)
	Setup CPU set set from unsigned long mask used as i -th subset.
unsigned long	hwloc_cpuset_to_ulong (hwloc_const_cpuset_t set)
	Convert the beginning part of CPU set set into unsigned long mask.
unsigned long	hwloc_cpuset_to_ith_ulong (hwloc_const_cpuset_t set, unsigned i)
	Convert the i -th subset of CPU set set into unsigned long mask.
void	hwloc_cpuset_cpu (hwloc_cpuset_t set, unsigned cpu)
	Empty the CPU set set and add CPU cpu.
void	hwloc_cpuset_all_but_cpu (hwloc_cpuset_t set, unsigned cpu)
	Empty the CPU set set and add all but the CPU cpu.
void	hwloc_cpuset_set (hwloc_cpuset_t set, unsigned cpu)
	Add CPU cpu in CPU set set.
void	hwloc_cpuset_set_range (hwloc_cpuset_t set, unsigned begincpu, unsigned endcpu)
	Add CPUs from begincpu to endcpu in CPU set set.
void	hwloc_cpuset_clr (hwloc_cpuset_t set, unsigned cpu)
	Remove CPU cpu from CPU set set.
void	hwloc_cpuset_clr_range (hwloc_cpuset_t set, unsigned begincpu, unsigned endcpu)
	Remove CPUs from begincpu to endcpu in CPU set set.
int	hwloc_cpuset_isset (hwloc_const_cpuset_t set, unsigned cpu)
	Test whether CPU cpu is part of set set.
int	hwloc_cpuset_iszero (hwloc_const_cpuset_t set)
	Test whether set set is empty.
int	hwloc_cpuset_isfull (hwloc_const_cpuset_t set)
	Test whether set set is completely full.
int	hwloc_cpuset_isequal (hwloc_const_cpuset_t set1, hwloc_const_cpuset_t set2)
	Test whether set set1 is equal to set set2.
int	hwloc_cpuset_intersects (hwloc_const_cpuset_t set1, hwloc_const_cpuset_t set2)
	Test whether sets set1 and set2 intersects.
int	hwloc_cpuset_isincluded (hwloc_const_cpuset_t sub_set, hwloc_const_cpuset_t super_set)
	Test whether set sub_set is part of set super_set.
void	hwloc_cpuset_or (hwloc_cpuset_t res, hwloc_const_cpuset_t set1, hwloc_const_cpuset_t set2)
	Or sets set1 and set2 and store the result in set res.
void	hwloc_cpuset_and (hwloc_cpuset_t res, hwloc_const_cpuset_t set1, hwloc_const_cpuset_t set2)
	And sets set1 and set2 and store the result in set res.
void	hwloc_cpuset_andnot (hwloc_cpuset_t res, hwloc_const_cpuset_t set1, hwloc_const_cpuset_t set2)
	And set set1 and the negation of set2 and store the result in set res.
void	hwloc_cpuset_xor (hwloc_cpuset_t res, hwloc_const_cpuset_t set1, hwloc_const_cpuset_t set2)
	Xor sets set1 and set2 and store the result in set res.
void	hwloc_cpuset_not (hwloc_cpuset_t res, hwloc_const_cpuset_t set)
	Negate set set and store the result in set res.
int	hwloc_cpuset_first (hwloc_const_cpuset_t set)
	Compute the first CPU (least significant bit) in CPU set set.
int	hwloc_cpuset_last (hwloc_const_cpuset_t set)
	Compute the last CPU (most significant bit) in CPU set set.
int	hwloc_cpuset_next (hwloc_const_cpuset_t set, unsigned prev_cpu)
	Compute the next CPU in CPU set set which is after CPU prev_cpu.
void	hwloc_cpuset_singlify (hwloc_cpuset_t set)
	Keep a single CPU among those set in CPU set set.
int	hwloc_cpuset_compare_first (hwloc_const_cpuset_t set1, hwloc_const_cpuset_t set2)
	Compare CPU sets set1 and set2 using their lowest index CPU.
int	hwloc_cpuset_compare (hwloc_const_cpuset_t set1, hwloc_const_cpuset_t set2)
	Compare CPU sets set1 and set2 using their highest index CPU.
int	hwloc_cpuset_weight (hwloc_const_cpuset_t set)
	Compute the "weight" of CPU set set (i.e., number of CPUs that are in the set).

---

Detailed Description

For use in hwloc itself, a hwloc_cpuset_t represents a set of logical processors.

Note:

cpusets are indexed by OS logical processor physical number.

---

Define Documentation

#define hwloc_cpuset_foreach_begin	(		cpu,
			set
	)

Loop macro iterating on CPU set set.

cpu is the loop variable; it should be an unsigned int. The first iteration will set cpu to the lowest index CPU in the set. Successive iterations will iterate through, in order, all remaining CPUs that in the set. To be specific: each iteration will return a value for cpu such that hwloc_cpuset_isset(set, cpu) is true.

#define hwloc_cpuset_foreach_end

(

)

End of loop. Needs a terminating ';'.

See also:

hwloc_cpuset_foreach_begin

---

Typedef Documentation

typedef struct hwloc_cpuset_s* hwloc_const_cpuset_t

typedef struct hwloc_cpuset_s* hwloc_cpuset_t

Set of CPUs represented as an opaque pointer to an internal bitmask.

---

Function Documentation

void hwloc_cpuset_all_but_cpu	(	hwloc_cpuset_t	set,
		unsigned	cpu
	)

Empty the CPU set set and add all but the CPU cpu.

hwloc_cpuset_t hwloc_cpuset_alloc

(

void

)

Allocate a new empty CPU set.

Returns:

A valid CPU set or NULL.

The CPU set should be freed by a corresponding call to hwloc_cpuset_free().

void hwloc_cpuset_and	(	hwloc_cpuset_t	res,
		hwloc_const_cpuset_t	set1,
		hwloc_const_cpuset_t	set2
	)

And sets set1 and set2 and store the result in set res.

void hwloc_cpuset_andnot	(	hwloc_cpuset_t	res,
		hwloc_const_cpuset_t	set1,
		hwloc_const_cpuset_t	set2
	)

And set set1 and the negation of set2 and store the result in set res.

int hwloc_cpuset_asprintf	(	char **	strp,
		hwloc_const_cpuset_t	set
	)

Stringify a cpuset into a newly allocated string.

Returns:

the number of character that were actually written (not including the ending \0).

void hwloc_cpuset_clr	(	hwloc_cpuset_t	set,
		unsigned	cpu
	)

Remove CPU cpu from CPU set set.

void hwloc_cpuset_clr_range	(	hwloc_cpuset_t	set,
		unsigned	begincpu,
		unsigned	endcpu
	)

Remove CPUs from begincpu to endcpu in CPU set set.

int hwloc_cpuset_compare	(	hwloc_const_cpuset_t	set1,
		hwloc_const_cpuset_t	set2
	)

Compare CPU sets set1 and set2 using their highest index CPU.

Higher most significant bit is higher. The empty CPU set is considered lower than anything.

int hwloc_cpuset_compare_first	(	hwloc_const_cpuset_t	set1,
		hwloc_const_cpuset_t	set2
	)

Compare CPU sets set1 and set2 using their lowest index CPU.

Smaller least significant bit is smaller. The empty CPU set is considered higher than anything.

void hwloc_cpuset_copy	(	hwloc_cpuset_t	dst,
		hwloc_const_cpuset_t	src
	)

Copy the contents of CPU set src into the already allocated CPU set dst.

void hwloc_cpuset_cpu	(	hwloc_cpuset_t	set,
		unsigned	cpu
	)

Empty the CPU set set and add CPU cpu.

hwloc_cpuset_t hwloc_cpuset_dup

(

hwloc_const_cpuset_t

set

)

Duplicate CPU set set by allocating a new CPU set and copying set's contents.

void hwloc_cpuset_fill

(

hwloc_cpuset_t

set

)

Fill CPU set set with all possible CPUs (even if those CPUs don't exist or are otherwise unavailable).

int hwloc_cpuset_first

(

hwloc_const_cpuset_t

set

)

Compute the first CPU (least significant bit) in CPU set set.

Returns:

-1 if no CPU is set.

void hwloc_cpuset_free

(

hwloc_cpuset_t

set

)

Free CPU set set.

void hwloc_cpuset_from_ith_ulong	(	hwloc_cpuset_t	set,
		unsigned	i,
		unsigned long	mask
	)

Setup CPU set set from unsigned long mask used as i -th subset.

int hwloc_cpuset_from_string	(	hwloc_cpuset_t	set,
		const char *restrict	string
	)

Parse a cpuset string and stores it in CPU set set.

Must start and end with a digit.

void hwloc_cpuset_from_ulong	(	hwloc_cpuset_t	set,
		unsigned long	mask
	)

Setup CPU set set from unsigned long mask.

int hwloc_cpuset_intersects	(	hwloc_const_cpuset_t	set1,
		hwloc_const_cpuset_t	set2
	)

Test whether sets set1 and set2 intersects.

int hwloc_cpuset_isequal	(	hwloc_const_cpuset_t	set1,
		hwloc_const_cpuset_t	set2
	)

Test whether set set1 is equal to set set2.

int hwloc_cpuset_isfull

(

hwloc_const_cpuset_t

set

)

Test whether set set is completely full.

int hwloc_cpuset_isincluded	(	hwloc_const_cpuset_t	sub_set,
		hwloc_const_cpuset_t	super_set
	)

Test whether set sub_set is part of set super_set.

int hwloc_cpuset_isset	(	hwloc_const_cpuset_t	set,
		unsigned	cpu
	)

Test whether CPU cpu is part of set set.

int hwloc_cpuset_iszero

(

hwloc_const_cpuset_t

set

)

Test whether set set is empty.

int hwloc_cpuset_last

(

hwloc_const_cpuset_t

set

)

Compute the last CPU (most significant bit) in CPU set set.

Returns:

-1 if no CPU is set.

int hwloc_cpuset_next	(	hwloc_const_cpuset_t	set,
		unsigned	prev_cpu
	)

Compute the next CPU in CPU set set which is after CPU prev_cpu.

Returns:

-1 if no CPU with higher index is set.

void hwloc_cpuset_not	(	hwloc_cpuset_t	res,
		hwloc_const_cpuset_t	set
	)

Negate set set and store the result in set res.

void hwloc_cpuset_or	(	hwloc_cpuset_t	res,
		hwloc_const_cpuset_t	set1,
		hwloc_const_cpuset_t	set2
	)

Or sets set1 and set2 and store the result in set res.

void hwloc_cpuset_set	(	hwloc_cpuset_t	set,
		unsigned	cpu
	)

Add CPU cpu in CPU set set.

void hwloc_cpuset_set_range	(	hwloc_cpuset_t	set,
		unsigned	begincpu,
		unsigned	endcpu
	)

Add CPUs from begincpu to endcpu in CPU set set.

void hwloc_cpuset_singlify

(

hwloc_cpuset_t

set

)

Keep a single CPU among those set in CPU set set.

May be useful before binding so that the process does not have a chance of migrating between multiple logical CPUs in the original mask.

int hwloc_cpuset_snprintf	(	char *restrict	buf,
		size_t	buflen,
		hwloc_const_cpuset_t	set
	)

Stringify a cpuset.

Up to buflen characters may be written in buffer buf.

Returns:

the number of character that were actually written if not truncating, or that would have been written (not including the ending \0).

unsigned long hwloc_cpuset_to_ith_ulong	(	hwloc_const_cpuset_t	set,
		unsigned	i
	)

Convert the i -th subset of CPU set set into unsigned long mask.

unsigned long hwloc_cpuset_to_ulong

(

hwloc_const_cpuset_t

set

)

Convert the beginning part of CPU set set into unsigned long mask.

int hwloc_cpuset_weight

(

hwloc_const_cpuset_t

set

)

Compute the "weight" of CPU set set (i.e., number of CPUs that are in the set).

Returns:

the number of CPUs that are in the set.

void hwloc_cpuset_xor	(	hwloc_cpuset_t	res,
		hwloc_const_cpuset_t	set1,
		hwloc_const_cpuset_t	set2
	)

Xor sets set1 and set2 and store the result in set res.

void hwloc_cpuset_zero

(

hwloc_cpuset_t

set

)

Empty the CPU set set.