# 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_DECLSPEC hwloc_cpuset_t | hwloc_cpuset_alloc (void) __hwloc_attribute_malloc
| Allocate a new empty CPU set.
HWLOC_DECLSPEC void | hwloc_cpuset_free (hwloc_cpuset_t set)
| Free CPU set `set`.
HWLOC_DECLSPEC hwloc_cpuset_t | hwloc_cpuset_dup (hwloc_const_cpuset_t set) __hwloc_attribute_malloc
| Duplicate CPU set `set` by allocating a new CPU set and copying `set's` contents.
HWLOC_DECLSPEC 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`.
HWLOC_DECLSPEC int | hwloc_cpuset_snprintf (char *__hwloc_restrict buf, size_t buflen, hwloc_const_cpuset_t set)
| Stringify a cpuset.
HWLOC_DECLSPEC int | hwloc_cpuset_asprintf (char **strp, hwloc_const_cpuset_t set)
| Stringify a cpuset into a newly allocated string.
HWLOC_DECLSPEC int | hwloc_cpuset_from_string (hwloc_cpuset_t set, const char *__hwloc_restrict string)
| Parse a cpuset string and stores it in CPU set `set`.
HWLOC_DECLSPEC void | hwloc_cpuset_zero (hwloc_cpuset_t set)
| Empty the CPU set `set`.
HWLOC_DECLSPEC 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).
HWLOC_DECLSPEC void | hwloc_cpuset_from_ulong (hwloc_cpuset_t set, unsigned long mask)
| Setup CPU set `set` from unsigned long `mask`.
HWLOC_DECLSPEC 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.
HWLOC_DECLSPEC unsigned long | hwloc_cpuset_to_ulong (hwloc_const_cpuset_t set) __hwloc_attribute_pure
| Convert the beginning part of CPU set `set` into unsigned long `mask`.
HWLOC_DECLSPEC unsigned long | hwloc_cpuset_to_ith_ulong (hwloc_const_cpuset_t set, unsigned i) __hwloc_attribute_pure
| Convert the `i` -th subset of CPU set `set` into unsigned long mask.
HWLOC_DECLSPEC void | hwloc_cpuset_cpu (hwloc_cpuset_t set, unsigned cpu)
| Empty the CPU set `set` and add CPU `cpu`.
HWLOC_DECLSPEC 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_DECLSPEC void | hwloc_cpuset_set (hwloc_cpuset_t set, unsigned cpu)
| Add CPU `cpu` in CPU set `set`.
HWLOC_DECLSPEC void | hwloc_cpuset_set_range (hwloc_cpuset_t set, unsigned begincpu, unsigned endcpu)
| Add CPUs from `begincpu` to `endcpu` in CPU set `set`.
HWLOC_DECLSPEC void | hwloc_cpuset_clr (hwloc_cpuset_t set, unsigned cpu)
| Remove CPU `cpu` from CPU set `set`.
HWLOC_DECLSPEC void | hwloc_cpuset_clr_range (hwloc_cpuset_t set, unsigned begincpu, unsigned endcpu)
| Remove CPUs from `begincpu` to `endcpu` in CPU set `set`.
HWLOC_DECLSPEC int | hwloc_cpuset_isset (hwloc_const_cpuset_t set, unsigned cpu) __hwloc_attribute_pure
| Test whether CPU `cpu` is part of set `set`.
HWLOC_DECLSPEC int | hwloc_cpuset_iszero (hwloc_const_cpuset_t set) __hwloc_attribute_pure
| Test whether set `set` is empty.
HWLOC_DECLSPEC int | hwloc_cpuset_isfull (hwloc_const_cpuset_t set) __hwloc_attribute_pure
| Test whether set `set` is completely full.
HWLOC_DECLSPEC int | hwloc_cpuset_isequal (hwloc_const_cpuset_t set1, hwloc_const_cpuset_t set2) __hwloc_attribute_pure
| Test whether set `set1` is equal to set `set2`.
HWLOC_DECLSPEC int | hwloc_cpuset_intersects (hwloc_const_cpuset_t set1, hwloc_const_cpuset_t set2) __hwloc_attribute_pure
| Test whether sets `set1` and `set2` intersects.
HWLOC_DECLSPEC int | hwloc_cpuset_isincluded (hwloc_const_cpuset_t sub_set, hwloc_const_cpuset_t super_set) __hwloc_attribute_pure
| Test whether set `sub_set` is part of set `super_set`.
HWLOC_DECLSPEC 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`.
HWLOC_DECLSPEC 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`.
HWLOC_DECLSPEC 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`.
HWLOC_DECLSPEC 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`.
HWLOC_DECLSPEC void | hwloc_cpuset_not (hwloc_cpuset_t res, hwloc_const_cpuset_t set)
| Negate set `set` and store the result in set `res`.
HWLOC_DECLSPEC int | hwloc_cpuset_first (hwloc_const_cpuset_t set) __hwloc_attribute_pure
| Compute the first CPU (least significant bit) in CPU set `set`.
HWLOC_DECLSPEC int | hwloc_cpuset_last (hwloc_const_cpuset_t set) __hwloc_attribute_pure
| Compute the last CPU (most significant bit) in CPU set `set`.
HWLOC_DECLSPEC int | hwloc_cpuset_next (hwloc_const_cpuset_t set, unsigned prev_cpu) __hwloc_attribute_pure
| Compute the next CPU in CPU set `set` which is after CPU `prev_cpu`.
HWLOC_DECLSPEC void | hwloc_cpuset_singlify (hwloc_cpuset_t set)
| Keep a single CPU among those set in CPU set `set`.
HWLOC_DECLSPEC int | hwloc_cpuset_compare_first (hwloc_const_cpuset_t set1, hwloc_const_cpuset_t set2) __hwloc_attribute_pure
| Compare CPU sets `set1` and `set2` using their lowest index CPU.
HWLOC_DECLSPEC int | hwloc_cpuset_compare (hwloc_const_cpuset_t set1, hwloc_const_cpuset_t set2) __hwloc_attribute_pure
| Compare CPU sets `set1` and `set2` using their highest index CPU.
HWLOC_DECLSPEC int | hwloc_cpuset_weight (hwloc_const_cpuset_t set) __hwloc_attribute_pure
| 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 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

HWLOC_DECLSPEC 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_DECLSPEC 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().

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

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

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

HWLOC_DECLSPEC void hwloc_cpuset_clr | ( | hwloc_cpuset_t | set,
|  | unsigned | cpu |
| ) |  |  |

Remove CPU `cpu` from CPU set `set`.

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

Remove CPUs from `begincpu` to `endcpu` in CPU set `set`.

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

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

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

HWLOC_DECLSPEC void hwloc_cpuset_cpu | ( | hwloc_cpuset_t | set,
|  | unsigned | cpu |
| ) |  |  |

Empty the CPU set `set` and add CPU `cpu`.

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

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

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

HWLOC_DECLSPEC void hwloc_cpuset_free | ( | hwloc_cpuset_t | set | ) |

Free CPU set `set`.

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

HWLOC_DECLSPEC int hwloc_cpuset_from_string | ( | hwloc_cpuset_t | set,
|  | const char *__hwloc_restrict | string |
| ) |  |  |

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

Must start and end with a digit.

HWLOC_DECLSPEC void hwloc_cpuset_from_ulong | ( | hwloc_cpuset_t | set,
|  | unsigned long | mask |
| ) |  |  |

Setup CPU set `set` from unsigned long `mask`.

HWLOC_DECLSPEC int hwloc_cpuset_intersects | ( | hwloc_const_cpuset_t | set1,
|  | hwloc_const_cpuset_t | set2 |
| ) |  |  |

Test whether sets `set1` and `set2` intersects.

HWLOC_DECLSPEC int hwloc_cpuset_isequal | ( | hwloc_const_cpuset_t | set1,
|  | hwloc_const_cpuset_t | set2 |
| ) |  |  |

Test whether set `set1` is equal to set `set2`.

HWLOC_DECLSPEC int hwloc_cpuset_isfull | ( | hwloc_const_cpuset_t | set | ) |

Test whether set `set` is completely full.

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

HWLOC_DECLSPEC int hwloc_cpuset_isset | ( | hwloc_const_cpuset_t | set,
|  | unsigned | cpu |
| ) |  |  |

Test whether CPU `cpu` is part of set `set`.

HWLOC_DECLSPEC int hwloc_cpuset_iszero | ( | hwloc_const_cpuset_t | set | ) |

Test whether set `set` is empty.

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

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

HWLOC_DECLSPEC void hwloc_cpuset_not | ( | hwloc_cpuset_t | res,
|  | hwloc_const_cpuset_t | set |
| ) |  |  |

Negate set `set` and store the result in set `res`.

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

HWLOC_DECLSPEC void hwloc_cpuset_set | ( | hwloc_cpuset_t | set,
|  | unsigned | cpu |
| ) |  |  |

Add CPU `cpu` in CPU set `set`.

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

Add CPUs from `begincpu` to `endcpu` in CPU set `set`.

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

HWLOC_DECLSPEC int hwloc_cpuset_snprintf | ( | char *__hwloc_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).

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

HWLOC_DECLSPEC unsigned long hwloc_cpuset_to_ulong | ( | hwloc_const_cpuset_t | set | ) |

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

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

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

HWLOC_DECLSPEC void hwloc_cpuset_zero | ( | hwloc_cpuset_t | set | ) |

Empty the CPU set `set`.