The bitmap API

## Macros

#define | hwloc_bitmap_foreach_begin(id, bitmap)
#define | hwloc_bitmap_foreach_end()

## Typedefs

typedef struct hwloc_bitmap_s * | hwloc_bitmap_t
typedef const struct hwloc_bitmap_s * | hwloc_const_bitmap_t

## Functions

hwloc_bitmap_t | hwloc_bitmap_alloc (void)
hwloc_bitmap_t | hwloc_bitmap_alloc_full (void)
void | hwloc_bitmap_free (hwloc_bitmap_t bitmap)
hwloc_bitmap_t | hwloc_bitmap_dup (hwloc_const_bitmap_t bitmap)
void | hwloc_bitmap_copy (hwloc_bitmap_t dst, hwloc_const_bitmap_t src)
int | hwloc_bitmap_snprintf (char *restrict buf, size_t buflen, hwloc_const_bitmap_t bitmap)
int | hwloc_bitmap_asprintf (char **strp, hwloc_const_bitmap_t bitmap)
int | hwloc_bitmap_sscanf (hwloc_bitmap_t bitmap, const char *restrict string)
int | hwloc_bitmap_list_snprintf (char *restrict buf, size_t buflen, hwloc_const_bitmap_t bitmap)
int | hwloc_bitmap_list_asprintf (char **strp, hwloc_const_bitmap_t bitmap)
int | hwloc_bitmap_list_sscanf (hwloc_bitmap_t bitmap, const char *restrict string)
int | hwloc_bitmap_taskset_snprintf (char *restrict buf, size_t buflen, hwloc_const_bitmap_t bitmap)
int | hwloc_bitmap_taskset_asprintf (char **strp, hwloc_const_bitmap_t bitmap)
int | hwloc_bitmap_taskset_sscanf (hwloc_bitmap_t bitmap, const char *restrict string)
void | hwloc_bitmap_zero (hwloc_bitmap_t bitmap)
void | hwloc_bitmap_fill (hwloc_bitmap_t bitmap)
void | hwloc_bitmap_only (hwloc_bitmap_t bitmap, unsigned id)
void | hwloc_bitmap_allbut (hwloc_bitmap_t bitmap, unsigned id)
void | hwloc_bitmap_from_ulong (hwloc_bitmap_t bitmap, unsigned long mask)
void | hwloc_bitmap_from_ith_ulong (hwloc_bitmap_t bitmap, unsigned i, unsigned long mask)
void | hwloc_bitmap_set (hwloc_bitmap_t bitmap, unsigned id)
void | hwloc_bitmap_set_range (hwloc_bitmap_t bitmap, unsigned begin, int end)
void | hwloc_bitmap_set_ith_ulong (hwloc_bitmap_t bitmap, unsigned i, unsigned long mask)
void | hwloc_bitmap_clr (hwloc_bitmap_t bitmap, unsigned id)
void | hwloc_bitmap_clr_range (hwloc_bitmap_t bitmap, unsigned begin, int end)
void | hwloc_bitmap_singlify (hwloc_bitmap_t bitmap)
unsigned long | hwloc_bitmap_to_ulong (hwloc_const_bitmap_t bitmap)
unsigned long | hwloc_bitmap_to_ith_ulong (hwloc_const_bitmap_t bitmap, unsigned i)
int | hwloc_bitmap_isset (hwloc_const_bitmap_t bitmap, unsigned id)
int | hwloc_bitmap_iszero (hwloc_const_bitmap_t bitmap)
int | hwloc_bitmap_isfull (hwloc_const_bitmap_t bitmap)
int | hwloc_bitmap_first (hwloc_const_bitmap_t bitmap)
int | hwloc_bitmap_next (hwloc_const_bitmap_t bitmap, int prev)
int | hwloc_bitmap_last (hwloc_const_bitmap_t bitmap)
int | hwloc_bitmap_weight (hwloc_const_bitmap_t bitmap)
void | hwloc_bitmap_or (hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
void | hwloc_bitmap_and (hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
void | hwloc_bitmap_andnot (hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
void | hwloc_bitmap_xor (hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
void | hwloc_bitmap_not (hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap)
int | hwloc_bitmap_intersects (hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
int | hwloc_bitmap_isincluded (hwloc_const_bitmap_t sub_bitmap, hwloc_const_bitmap_t super_bitmap)
int | hwloc_bitmap_isequal (hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
int | hwloc_bitmap_compare_first (hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
int | hwloc_bitmap_compare (hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)

## Detailed Description

The hwloc_bitmap_t type represents a set of objects, typically OS processors – which may actually be hardware threads (represented by hwloc_cpuset_t, which is a typedef for hwloc_bitmap_t) – or memory nodes (represented by hwloc_nodeset_t, which is also a typedef for hwloc_bitmap_t).

Both CPU and node sets are always indexed by OS physical number.

Note
  CPU sets and nodesets are described in Object Sets (hwloc_cpuset_t and hwloc_nodeset_t).

A bitmap may be of infinite size.

Note
  Several examples of using the bitmap API are available under the doc/examples/ directory in the source tree. Regression tests such as tests/hwloc_bitmap*.c also make intensive use of this API.

## Macro Definition Documentation

#define hwloc_bitmap_foreach_begin | ( |  | id,
|  |  | bitmap
| ) |  |

Loop macro iterating on bitmap `bitmap`.

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

The assert prevents the loop from being infinite if the bitmap is infinite.

#define hwloc_bitmap_foreach_end | ( |  | ) |

Value:
} \
} while (0)

## Typedef Documentation

typedef struct hwloc_bitmap_s* hwloc_bitmap_t

Set of bits represented as an opaque pointer to an internal bitmap.

typedef const struct hwloc_bitmap_s* hwloc_const_bitmap_t

a non-modifiable hwloc_bitmap_t

## Function Documentation

void hwloc_bitmap_allbut | ( | hwloc_bitmap_t | bitmap,
|  | unsigned | id
| ) |  |

Fill the bitmap `and` clear the index `id`.

hwloc_bitmap_t hwloc_bitmap_alloc | ( | void |  | ) |

Allocate a new empty bitmap.

Returns
  A valid bitmap or `NULL`.

The bitmap should be freed by a corresponding call to hwloc_bitmap_free().

hwloc_bitmap_t hwloc_bitmap_alloc_full | ( | void |  | ) |

Allocate a new full bitmap.

void hwloc_bitmap_and | ( | hwloc_bitmap_t | res,
|  | hwloc_const_bitmap_t | bitmap1,
|  | hwloc_const_bitmap_t | bitmap2
| ) |  |

And bitmaps `bitmap1` and `bitmap2` and store the result in bitmap `res`.

`res` can be the same as `bitmap1` or `bitmap2`

void hwloc_bitmap_andnot | ( | hwloc_bitmap_t | res,
|  | hwloc_const_bitmap_t | bitmap1,
|  | hwloc_const_bitmap_t | bitmap2
| ) |  |

And bitmap `bitmap1` and the negation of `bitmap2` and store the result in bitmap `res`.

`res` can be the same as `bitmap1` or `bitmap2`

int hwloc_bitmap_asprintf | ( | char ** | strp,
|  | hwloc_const_bitmap_t | bitmap
| ) |  |

Stringify a bitmap into a newly allocated string.

void hwloc_bitmap_clr | ( | hwloc_bitmap_t | bitmap,
|  | unsigned | id
| ) |  |

Remove index `id` from bitmap `bitmap`.

void hwloc_bitmap_clr_range | ( | hwloc_bitmap_t | bitmap,
|  | unsigned | begin,
|  | int | end
| ) |  |

Remove indexes from `begin` to `end` in bitmap `bitmap`.

If `end` is `-1`, the range is infinite.

int hwloc_bitmap_compare | ( | hwloc_const_bitmap_t | bitmap1,
|  | hwloc_const_bitmap_t | bitmap2
| ) |  |

Compare bitmaps `bitmap1` and `bitmap2` in lexicographic order.

Lexicographic comparison of bitmaps, starting for their highest indexes. Compare last indexes first, then second, etc. The empty bitmap is considered lower than anything.

Note
  This is different from the non-existing hwloc_bitmap_compare_last() which would only compare the highest index of each bitmap.

int hwloc_bitmap_compare_first | ( | hwloc_const_bitmap_t | bitmap1,
|  | hwloc_const_bitmap_t | bitmap2
| ) |  |

Compare bitmaps `bitmap1` and `bitmap2` using their lowest index.

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

void hwloc_bitmap_copy | ( | hwloc_bitmap_t | dst,
|  | hwloc_const_bitmap_t | src
| ) |  |

Copy the contents of bitmap `src` into the already allocated bitmap `dst`.

hwloc_bitmap_t hwloc_bitmap_dup | ( | hwloc_const_bitmap_t | bitmap | ) |

Duplicate bitmap `bitmap` by allocating a new bitmap and copying `bitmap` contents.

If `bitmap` is `NULL`, `NULL` is returned.

void hwloc_bitmap_fill | ( | hwloc_bitmap_t | bitmap | ) |

Fill bitmap `bitmap` with all possible indexes (even if those objects don't exist or are otherwise unavailable)

int hwloc_bitmap_first | ( | hwloc_const_bitmap_t | bitmap | ) |

Compute the first index (least significant bit) in bitmap `bitmap`.

Returns
  -1 if no index is set.

void hwloc_bitmap_free | ( | hwloc_bitmap_t | bitmap | ) |

Free bitmap `bitmap`.

If `bitmap` is `NULL`, no operation is performed.

void hwloc_bitmap_from_ith_ulong | ( | hwloc_bitmap_t | bitmap,
|  | unsigned | i,
|  | unsigned long | mask
| ) |  |

Setup bitmap `bitmap` from unsigned long `mask` used as `i` -th subset.

void hwloc_bitmap_from_ulong | ( | hwloc_bitmap_t | bitmap,
|  | unsigned long | mask
| ) |  |

Setup bitmap `bitmap` from unsigned long `mask`.

int hwloc_bitmap_intersects | ( | hwloc_const_bitmap_t | bitmap1,
|  | hwloc_const_bitmap_t | bitmap2
| ) |  |

Test whether bitmaps `bitmap1` and `bitmap2` intersects.

int hwloc_bitmap_isequal | ( | hwloc_const_bitmap_t | bitmap1,
|  | hwloc_const_bitmap_t | bitmap2
| ) |  |

Test whether bitmap `bitmap1` is equal to bitmap `bitmap2`.

int hwloc_bitmap_isfull | ( | hwloc_const_bitmap_t | bitmap | ) |

Test whether bitmap `bitmap` is completely full.

int hwloc_bitmap_isincluded | ( | hwloc_const_bitmap_t | sub_bitmap,
|  | hwloc_const_bitmap_t | super_bitmap
| ) |  |

Test whether bitmap `sub_bitmap` is part of bitmap `super_bitmap`.

int hwloc_bitmap_isset | ( | hwloc_const_bitmap_t | bitmap,
|  | unsigned | id
| ) |  |

Test whether index `id` is part of bitmap `bitmap`.

int hwloc_bitmap_iszero | ( | hwloc_const_bitmap_t | bitmap | ) |

Test whether bitmap `bitmap` is empty.

int hwloc_bitmap_last | ( | hwloc_const_bitmap_t | bitmap | ) |

Compute the last index (most significant bit) in bitmap `bitmap`.

Returns
  -1 if no index is bitmap, or if the index bitmap is infinite.

int hwloc_bitmap_list_asprintf | ( | char ** | strp,
|  | hwloc_const_bitmap_t | bitmap
| ) |  |

Stringify a bitmap into a newly allocated list string.

int hwloc_bitmap_list_snprintf | ( | char *restrict | buf,
|  | size_t | buflen,
|  | hwloc_const_bitmap_t | bitmap
| ) |  |

Stringify a bitmap in the list format.

Lists are comma-separated indexes or ranges. Ranges are dash separated indexes. The last range may not have a ending indexes if the bitmap is infinite.

Up to `buflen` characters may be written in buffer `buf`.

If `buflen` is 0, `buf` may safely be `NULL`.

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

int hwloc_bitmap_list_sscanf | ( | hwloc_bitmap_t | bitmap,
|  | const char *restrict | string
| ) |  |

Parse a list string and stores it in bitmap `bitmap`.

int hwloc_bitmap_next | ( | hwloc_const_bitmap_t | bitmap,
|  | int | prev
| ) |  |

Compute the next index in bitmap `bitmap` which is after index `prev`.

If `prev` is -1, the first index is returned.

Returns
  -1 if no index with higher index is bitmap.

void hwloc_bitmap_not | ( | hwloc_bitmap_t | res,
|  | hwloc_const_bitmap_t | bitmap
| ) |  |

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

`res` can be the same as `bitmap`

void hwloc_bitmap_only | ( | hwloc_bitmap_t | bitmap,
|  | unsigned | id
| ) |  |

Empty the bitmap `bitmap` and add bit `id`.

void hwloc_bitmap_or | ( | hwloc_bitmap_t | res,
|  | hwloc_const_bitmap_t | bitmap1,
|  | hwloc_const_bitmap_t | bitmap2
| ) |  |

Or bitmaps `bitmap1` and `bitmap2` and store the result in bitmap `res`.

`res` can be the same as `bitmap1` or `bitmap2`

void hwloc_bitmap_set | ( | hwloc_bitmap_t | bitmap,
|  | unsigned | id
| ) |  |

Add index `id` in bitmap `bitmap`.

void hwloc_bitmap_set_ith_ulong | ( | hwloc_bitmap_t | bitmap,
|  | unsigned | i,
|  | unsigned long | mask
| ) |  |

Replace `i` -th subset of bitmap `bitmap` with unsigned long `mask`.

void hwloc_bitmap_set_range | ( | hwloc_bitmap_t | bitmap,
|  | unsigned | begin,
|  | int | end
| ) |  |

Add indexes from `begin` to `end` in bitmap `bitmap`.

If `end` is `-1`, the range is infinite.

void hwloc_bitmap_singlify | ( | hwloc_bitmap_t | bitmap | ) |

Keep a single index among those set in bitmap `bitmap`.

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_bitmap_snprintf | ( | char *restrict | buf,
|  | size_t | buflen,
|  | hwloc_const_bitmap_t | bitmap
| ) |  |

Stringify a bitmap.

Up to `buflen` characters may be written in buffer `buf`.

If `buflen` is 0, `buf` may safely be `NULL`.

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

int hwloc_bitmap_sscanf | ( | hwloc_bitmap_t | bitmap,
|  | const char *restrict | string
| ) |  |

Parse a bitmap string and stores it in bitmap `bitmap`.

int hwloc_bitmap_taskset_asprintf | ( | char ** | strp,
|  | hwloc_const_bitmap_t | bitmap
| ) |  |

Stringify a bitmap into a newly allocated taskset-specific string.

int hwloc_bitmap_taskset_snprintf | ( | char *restrict | buf,
|  | size_t | buflen,
|  | hwloc_const_bitmap_t | bitmap
| ) |  |

Stringify a bitmap in the taskset-specific format.

The taskset command manipulates bitmap strings that contain a single (possible very long) hexadecimal number starting with 0x.

Up to `buflen` characters may be written in buffer `buf`.

If `buflen` is 0, `buf` may safely be `NULL`.

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

int hwloc_bitmap_taskset_sscanf | ( | hwloc_bitmap_t | bitmap,
|  | const char *restrict | string
| ) |  |

Parse a taskset-specific bitmap string and stores it in bitmap `bitmap`.

unsigned long hwloc_bitmap_to_ith_ulong | ( | hwloc_const_bitmap_t | bitmap,
|  | unsigned | i
| ) |  |

Convert the `i` -th subset of bitmap `bitmap` into unsigned long mask.

unsigned long hwloc_bitmap_to_ulong | ( | hwloc_const_bitmap_t | bitmap | ) |

Convert the beginning part of bitmap `bitmap` into unsigned long `mask`.

int hwloc_bitmap_weight | ( | hwloc_const_bitmap_t | bitmap | ) |

Compute the "weight" of bitmap `bitmap` (i.e., number of indexes that are in the bitmap).

Returns
  the number of indexes that are in the bitmap.

void hwloc_bitmap_xor | ( | hwloc_bitmap_t | res,
|  | hwloc_const_bitmap_t | bitmap1,
|  | hwloc_const_bitmap_t | bitmap2
| ) |  |

Xor bitmaps `bitmap1` and `bitmap2` and store the result in bitmap `res`.

`res` can be the same as `bitmap1` or `bitmap2`

void hwloc_bitmap_zero | ( | hwloc_bitmap_t | bitmap | ) |

Empty the bitmap `bitmap`.