Manpages - hwlocality_bitmap.3

#define *hwloc_bitmap_foreach_begin*(id, bitmap)

#define *hwloc_bitmap_foreach_end*()

typedef struct hwloc_bitmap_s * hwloc_bitmap_t

typedef const struct hwloc_bitmap_s * hwloc_const_bitmap_t

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)

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

int hwloc_bitmap_only (hwloc_bitmap_t bitmap, unsigned id)

int hwloc_bitmap_allbut (hwloc_bitmap_t bitmap, unsigned id)

int hwloc_bitmap_from_ulong (hwloc_bitmap_t bitmap, unsigned long mask)

int hwloc_bitmap_from_ith_ulong (hwloc_bitmap_t bitmap, unsigned i, unsigned long mask)

int hwloc_bitmap_from_ulongs (hwloc_bitmap_t bitmap, unsigned nr, const unsigned long *masks)

int hwloc_bitmap_set (hwloc_bitmap_t bitmap, unsigned id)

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

int hwloc_bitmap_set_ith_ulong (hwloc_bitmap_t bitmap, unsigned i, unsigned long mask)

int hwloc_bitmap_clr (hwloc_bitmap_t bitmap, unsigned id)

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

int 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_to_ulongs (hwloc_const_bitmap_t bitmap, unsigned nr, unsigned long *masks)

int hwloc_bitmap_nr_ulongs (hwloc_const_bitmap_t bitmap)

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)

int hwloc_bitmap_first_unset (hwloc_const_bitmap_t bitmap)

int hwloc_bitmap_next_unset (hwloc_const_bitmap_t bitmap, int prev)

int hwloc_bitmap_last_unset (hwloc_const_bitmap_t bitmap)

int hwloc_bitmap_or (hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)

int hwloc_bitmap_and (hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)

int hwloc_bitmap_andnot (hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)

int hwloc_bitmap_xor (hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)

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

Loop macro iterating on bitmap bitmap. The loop must start with hwloc_bitmap_foreach_begin() and end with hwloc_bitmap_foreach_end() followed by a terminating ’;’.

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 set 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 infinitely set.

End of loop macro iterating on a bitmap. Needs a terminating ’;’.

See also

hwloc_bitmap_foreach_begin()

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

a non-modifiable hwloc_bitmap_t

Fill the bitmap and clear the index id.

Allocate a new empty bitmap.

Returns

A valid bitmap or NULL.

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

Allocate a new full bitmap.

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

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

bitmap) Stringify a bitmap into a newly allocated string.

Returns

-1 on error.

Remove index id from bitmap bitmap.

int end) Remove indexes from begin to end in bitmap bitmap. If end is -1, the range is infinite.

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.

Returns

-1 if bitmap1 is considered smaller than bitmap2.

1 if bitmap1 is considered larger than bitmap2.

0 if bitmaps are equal (contrary to hwloc_bitmap_compare_first()).

For instance comparing binary bitmaps 0011 and 0110 returns -1 (hence 0011 is considered smaller than 0110). Comparing 00101 and 01010 returns -1 too.

Note

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

hwloc_const_bitmap_t bitmap2) Compare bitmaps bitmap1 and bitmap2 using their lowest index. A bitmap is considered smaller if its least significant bit is smaller. The empty bitmap is considered higher than anything (because its least significant bit does not exist).

Returns

-1 if bitmap1 is considered smaller than bitmap2.

1 if bitmap1 is considered larger than bitmap2.

For instance comparing binary bitmaps 0011 and 0110 returns -1 (hence 0011 is considered smaller than 0110) because least significant bit of 0011 (0001) is smaller than least significant bit of 0110 (0010). Comparing 01001 and 00110 would also return -1 for the same reason.

Returns

0 if bitmaps are considered equal, even if they are not strictly equal. They just need to have the same least significant bit. For instance, comparing binary bitmaps 0010 and 0110 returns 0 because they have the same least significant bit.

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

Duplicate bitmap bitmap by allocating a new bitmap and copying bitmap contents. If bitmap is NULL, NULL is returned.

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

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

Returns

-1 if no index is set in bitmap.

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

Returns

-1 if no index is unset in bitmap.

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

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

mask) Setup bitmap bitmap from unsigned long mask.

const unsigned long * masks) Setup bitmap bitmap from unsigned longs masks used as first nr subsets.

hwloc_const_bitmap_t bitmap2) Test whether bitmaps bitmap1 and bitmap2 intersects.

Returns

1 if bitmaps intersect, 0 otherwise.

hwloc_const_bitmap_t bitmap2) Test whether bitmap bitmap1 is equal to bitmap bitmap2.

Returns

1 if bitmaps are equal, 0 otherwise.

Test whether bitmap bitmap is completely full.

Returns

1 if bitmap is full, 0 otherwise.

Note

A full bitmap is always infinitely set.

hwloc_const_bitmap_t super_bitmap) Test whether bitmap sub_bitmap is part of bitmap super_bitmap.

Returns

1 if sub_bitmap is included in super_bitmap, 0 otherwise.

Note

The empty bitmap is considered included in any other bitmap.

Test whether index id is part of bitmap bitmap.

Returns

1 if the bit at index id is set in bitmap bitmap, 0 otherwise.

Test whether bitmap bitmap is empty.

Returns

1 if bitmap is empty, 0 otherwise.

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

Returns

-1 if no index is set in bitmap, or if bitmap is infinitely set.

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

Returns

-1 if no index is unset in bitmap, or if bitmap is infinitely set.

bitmap) Stringify a bitmap into a newly allocated list string.

Returns

-1 on error.

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 an ending indexes if the bitmap is infinitely set.

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

*restrict string) Parse a list string and stores it in bitmap bitmap.

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 set in bitmap.

Compute the next unset index in bitmap bitmap which is after index prev. If prev is -1, the first unset index is returned.

Returns

-1 if no index with higher index is unset in bitmap.

bitmap) Negate bitmap bitmap and store the result in bitmap res. res can be the same as bitmap

Return the number of unsigned longs required for storing bitmap bitmap entirely. This is the number of contiguous unsigned longs from the very first bit of the bitmap (even if unset) up to the last set bit. This is useful for knowing the nr parameter to pass to hwloc_bitmap_to_ulongs() (or which calls to hwloc_bitmap_to_ith_ulong() are needed) to entirely convert a bitmap into multiple unsigned longs.

When called on the output of hwloc_topology_get_topology_cpuset(), the returned number is large enough for all cpusets of the topology.

Returns

-1 if bitmap is infinite.

Empty the bitmap bitmap and add bit id.

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

Add index id in bitmap bitmap.

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

int end) Add indexes from begin to end in bitmap bitmap. If end is -1, the range is infinite.

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 processors in the original mask. Instead of running the task on any PU inside the given CPU set, the operating system scheduler will be forced to run it on a single of these PUs. It avoids a migration overhead and cache-line ping-pongs between PUs.

Note

This function is NOT meant to distribute multiple processes within a single CPU set. It always return the same single bit when called multiple times on the same input set. hwloc_distrib() may be used for generating CPU sets to distribute multiple tasks below a single multi-PU object.

This function cannot be applied to an object set directly. It should be applied to a copy (which may be obtained with hwloc_bitmap_dup()).

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

*restrict string) Parse a bitmap string and stores it in bitmap bitmap.

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

Returns

-1 on error.

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

*restrict string) Parse a taskset-specific bitmap string and stores it in bitmap bitmap.

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

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

nr, unsigned long * masks) Convert the first nr subsets of bitmap bitmap into the array of nr unsigned long masks. nr may be determined earlier with hwloc_bitmap_nr_ulongs().

Returns

0

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.

-1 if bitmap is infinitely set.

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

Empty the bitmap bitmap.