Hardware Locality (hwloc): The bitmap API

Hardware Locality (hwloc) 1.9

- Main Page
- Related Pages
- Modules
- Data Structures

Macros | Typedefs | Functions
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.

## 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` using their highest index.

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

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