OpenMPI 0.1.1

- Main Page
- Related Pages
- Modules
- Data Structures
- Files

Macros | Typedefs | Functions
The bitmap API

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

## Macros
#define | hwloc_bitmap_foreach_begin(id, bitmap)
| Loop macro iterating on bitmap `bitmap`. More...
#define | hwloc_bitmap_foreach_end()

## Typedefs
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

## Functions
HWLOC_DECLSPEC hwloc_bitmap_t | hwloc_bitmap_alloc (void) __hwloc_attribute_malloc
| Allocate a new empty bitmap. More...
HWLOC_DECLSPEC hwloc_bitmap_t | hwloc_bitmap_alloc_full (void) __hwloc_attribute_malloc
| Allocate a new full bitmap. More...
HWLOC_DECLSPEC void | hwloc_bitmap_free (hwloc_bitmap_t bitmap)
| Free bitmap `bitmap`. More...
HWLOC_DECLSPEC hwloc_bitmap_t | hwloc_bitmap_dup (hwloc_const_bitmap_t bitmap) __hwloc_attribute_malloc
| Duplicate bitmap `bitmap` by allocating a new bitmap and copying `bitmap` contents. More...
HWLOC_DECLSPEC 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_DECLSPEC int | hwloc_bitmap_snprintf (char *__hwloc_restrict buf, size_t buflen, hwloc_const_bitmap_t bitmap)
| Stringify a bitmap. More...
HWLOC_DECLSPEC int | hwloc_bitmap_asprintf (char **strp, hwloc_const_bitmap_t bitmap)
| Stringify a bitmap into a newly allocated string.
HWLOC_DECLSPEC int | hwloc_bitmap_sscanf (hwloc_bitmap_t bitmap, const char *__hwloc_restrict string)
| Parse a bitmap string and stores it in bitmap `bitmap`.
HWLOC_DECLSPEC int | hwloc_bitmap_list_snprintf (char *__hwloc_restrict buf, size_t buflen, hwloc_const_bitmap_t bitmap)
| Stringify a bitmap in the list format. More...
HWLOC_DECLSPEC int | hwloc_bitmap_list_asprintf (char **strp, hwloc_const_bitmap_t bitmap)
| Stringify a bitmap into a newly allocated list string.
HWLOC_DECLSPEC int | hwloc_bitmap_list_sscanf (hwloc_bitmap_t bitmap, const char *__hwloc_restrict string)
| Parse a list string and stores it in bitmap `bitmap`.
HWLOC_DECLSPEC int | hwloc_bitmap_taskset_snprintf (char *__hwloc_restrict buf, size_t buflen, hwloc_const_bitmap_t bitmap)
| Stringify a bitmap in the taskset-specific format. More...
HWLOC_DECLSPEC int | hwloc_bitmap_taskset_asprintf (char **strp, hwloc_const_bitmap_t bitmap)
| Stringify a bitmap into a newly allocated taskset-specific string.
HWLOC_DECLSPEC int | hwloc_bitmap_taskset_sscanf (hwloc_bitmap_t bitmap, const char *__hwloc_restrict string)
| Parse a taskset-specific bitmap string and stores it in bitmap `bitmap`.
HWLOC_DECLSPEC void | hwloc_bitmap_zero (hwloc_bitmap_t bitmap)
| Empty the bitmap `bitmap`.
HWLOC_DECLSPEC 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)
HWLOC_DECLSPEC void | hwloc_bitmap_only (hwloc_bitmap_t bitmap, unsigned id)
| Empty the bitmap `bitmap` and add bit `id`.
HWLOC_DECLSPEC void | hwloc_bitmap_allbut (hwloc_bitmap_t bitmap, unsigned id)
| Fill the bitmap `and` clear the index `id`.
HWLOC_DECLSPEC void | hwloc_bitmap_from_ulong (hwloc_bitmap_t bitmap, unsigned long mask)
| Setup bitmap `bitmap` from unsigned long `mask`.
HWLOC_DECLSPEC 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.
HWLOC_DECLSPEC void | hwloc_bitmap_set (hwloc_bitmap_t bitmap, unsigned id)
| Add index `id` in bitmap `bitmap`.
HWLOC_DECLSPEC void | hwloc_bitmap_set_range (hwloc_bitmap_t bitmap, unsigned begin, int end)
| Add indexes from `begin` to `end` in bitmap `bitmap`. More...
HWLOC_DECLSPEC 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`.
HWLOC_DECLSPEC void | hwloc_bitmap_clr (hwloc_bitmap_t bitmap, unsigned id)
| Remove index `id` from bitmap `bitmap`.
HWLOC_DECLSPEC void | hwloc_bitmap_clr_range (hwloc_bitmap_t bitmap, unsigned begin, int end)
| Remove indexes from `begin` to `end` in bitmap `bitmap`. More...
HWLOC_DECLSPEC void | hwloc_bitmap_singlify (hwloc_bitmap_t bitmap)
| Keep a single index among those set in bitmap `bitmap`. More...
HWLOC_DECLSPEC unsigned long | hwloc_bitmap_to_ulong (hwloc_const_bitmap_t bitmap) __hwloc_attribute_pure
| Convert the beginning part of bitmap `bitmap` into unsigned long `mask`.
HWLOC_DECLSPEC unsigned long | hwloc_bitmap_to_ith_ulong (hwloc_const_bitmap_t bitmap, unsigned i) __hwloc_attribute_pure
| Convert the `i` -th subset of bitmap `bitmap` into unsigned long mask.
HWLOC_DECLSPEC int | hwloc_bitmap_isset (hwloc_const_bitmap_t bitmap, unsigned id) __hwloc_attribute_pure
| Test whether index `id` is part of bitmap `bitmap`.
HWLOC_DECLSPEC int | hwloc_bitmap_iszero (hwloc_const_bitmap_t bitmap) __hwloc_attribute_pure
| Test whether bitmap `bitmap` is empty.
HWLOC_DECLSPEC int | hwloc_bitmap_isfull (hwloc_const_bitmap_t bitmap) __hwloc_attribute_pure
| Test whether bitmap `bitmap` is completely full.
HWLOC_DECLSPEC int | hwloc_bitmap_first (hwloc_const_bitmap_t bitmap) __hwloc_attribute_pure
| Compute the first index (least significant bit) in bitmap `bitmap`. More...
HWLOC_DECLSPEC int | hwloc_bitmap_next (hwloc_const_bitmap_t bitmap, int prev) __hwloc_attribute_pure
| Compute the next index in bitmap `bitmap` which is after index `prev`. More...
HWLOC_DECLSPEC int | hwloc_bitmap_last (hwloc_const_bitmap_t bitmap) __hwloc_attribute_pure
| Compute the last index (most significant bit) in bitmap `bitmap`. More...
HWLOC_DECLSPEC int | hwloc_bitmap_weight (hwloc_const_bitmap_t bitmap) __hwloc_attribute_pure
| Compute the "weight" of bitmap `bitmap` (i.e., number of indexes that are in the bitmap). More...
HWLOC_DECLSPEC 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`.
HWLOC_DECLSPEC 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`.
HWLOC_DECLSPEC 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`.
HWLOC_DECLSPEC 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`.
HWLOC_DECLSPEC void | hwloc_bitmap_not (hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap)
| Negate bitmap `bitmap` and store the result in bitmap `res`.
HWLOC_DECLSPEC int | hwloc_bitmap_intersects (hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2) __hwloc_attribute_pure
| Test whether bitmaps `bitmap1` and `bitmap2` intersects.
HWLOC_DECLSPEC int | hwloc_bitmap_isincluded (hwloc_const_bitmap_t sub_bitmap, hwloc_const_bitmap_t super_bitmap) __hwloc_attribute_pure
| Test whether bitmap `sub_bitmap` is part of bitmap `super_bitmap`.
HWLOC_DECLSPEC int | hwloc_bitmap_isequal (hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2) __hwloc_attribute_pure
| Test whether bitmap `bitmap1` is equal to bitmap `bitmap2`.
HWLOC_DECLSPEC int | hwloc_bitmap_compare_first (hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2) __hwloc_attribute_pure
| Compare bitmaps `bitmap1` and `bitmap2` using their lowest index. More...
HWLOC_DECLSPEC int | hwloc_bitmap_compare (hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2) __hwloc_attribute_pure
| Compare bitmaps `bitmap1` and `bitmap2` using their highest index. More...

## 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)

## Function Documentation

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

Referenced by hwloc_alloc_membind(), hwloc_bitmap_alloc_full(), hwloc_get_area_membind(), hwloc_get_membind(), hwloc_get_proc_membind(), hwloc_set_area_membind(), hwloc_set_membind(), hwloc_set_proc_membind(), and ompi_mpi_init().

HWLOC_DECLSPEC hwloc_bitmap_t hwloc_bitmap_alloc_full | ( | void |  | ) |

Allocate a new full bitmap.

References hwloc_bitmap_alloc().

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

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

Referenced by ompi_mpi_init().

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

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

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

HWLOC_DECLSPEC void hwloc_bitmap_free | ( | hwloc_bitmap_t | bitmap | ) |

Free bitmap `bitmap`.

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

Referenced by hwloc_alloc_membind(), hwloc_get_area_membind(), hwloc_get_membind(), hwloc_get_proc_membind(), hwloc_set_area_membind(), hwloc_set_membind(), hwloc_set_proc_membind(), and ompi_mpi_init().

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

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

Referenced by ompi_mpi_init().

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

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

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

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

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

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

Referenced by hwloc_distributev().