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 (all bits are set after some point). A bitmap may even be full if all bits are set.

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/hwloc_bitmap*.c also make intensive use of this API.

Macro Definition Documentation

hwloc_bitmap_foreach_begin

#define hwloc_bitmap_foreach_begin	(		id,
			bitmap
	)

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.

hwloc_bitmap_foreach_end

#define hwloc_bitmap_foreach_end

(

)

End of loop macro iterating on a bitmap.

Needs a terminating ';'.

See also

hwloc_bitmap_foreach_begin()

Typedef Documentation

hwloc_bitmap_t

typedef struct hwloc_bitmap_s* hwloc_bitmap_t

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

hwloc_const_bitmap_t

typedef const struct hwloc_bitmap_s* hwloc_const_bitmap_t

a non-modifiable hwloc_bitmap_t

Function Documentation

hwloc_bitmap_allbut()

void hwloc_bitmap_allbut	(	hwloc_bitmap_t	bitmap,
		unsigned	id
	)

Fill the bitmap and clear the index id.

hwloc_bitmap_alloc()

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_alloc_full()

hwloc_bitmap_t hwloc_bitmap_alloc_full

(

void

)

Allocate a new full bitmap.

hwloc_bitmap_and()

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

hwloc_bitmap_andnot()

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

hwloc_bitmap_asprintf()

int hwloc_bitmap_asprintf	(	char **	strp,
		hwloc_const_bitmap_t	bitmap
	)

Stringify a bitmap into a newly allocated string.

Returns

-1 on error.

hwloc_bitmap_clr()

void hwloc_bitmap_clr	(	hwloc_bitmap_t	bitmap,
		unsigned	id
	)

Remove index id from bitmap bitmap.

hwloc_bitmap_clr_range()

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_bitmap_compare()

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.

hwloc_bitmap_compare_first()

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_bitmap_copy()

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_dup()

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_bitmap_fill()

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_bitmap_first()

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

hwloc_bitmap_free()

void hwloc_bitmap_free

(

hwloc_bitmap_t

bitmap

)

Free bitmap bitmap.

If bitmap is NULL, no operation is performed.

hwloc_bitmap_from_ith_ulong()

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_bitmap_from_ulong()

void hwloc_bitmap_from_ulong	(	hwloc_bitmap_t	bitmap,
		unsigned long	mask
	)

Setup bitmap bitmap from unsigned long mask.

hwloc_bitmap_intersects()

int hwloc_bitmap_intersects	(	hwloc_const_bitmap_t	bitmap1,
		hwloc_const_bitmap_t	bitmap2
	)

Test whether bitmaps bitmap1 and bitmap2 intersects.

hwloc_bitmap_isequal()

int hwloc_bitmap_isequal	(	hwloc_const_bitmap_t	bitmap1,
		hwloc_const_bitmap_t	bitmap2
	)

Test whether bitmap bitmap1 is equal to bitmap bitmap2.

hwloc_bitmap_isfull()

int hwloc_bitmap_isfull

(

hwloc_const_bitmap_t

bitmap

)

Test whether bitmap bitmap is completely full.

Note

A full bitmap is always infinitely set.

hwloc_bitmap_isincluded()

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.

Note

The empty bitmap is considered included in any other bitmap.

hwloc_bitmap_isset()

int hwloc_bitmap_isset	(	hwloc_const_bitmap_t	bitmap,
		unsigned	id
	)

Test whether index id is part of bitmap bitmap.

hwloc_bitmap_iszero()

int hwloc_bitmap_iszero

(

hwloc_const_bitmap_t

bitmap

)

Test whether bitmap bitmap is empty.

hwloc_bitmap_last()

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 set in bitmap, or if bitmap is infinitely set.

hwloc_bitmap_list_asprintf()

int hwloc_bitmap_list_asprintf	(	char **	strp,
		hwloc_const_bitmap_t	bitmap
	)

Stringify a bitmap into a newly allocated list string.

Returns

-1 on error.

hwloc_bitmap_list_snprintf()

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

hwloc_bitmap_list_sscanf()

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

Parse a list string and stores it in bitmap bitmap.

hwloc_bitmap_next()

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

hwloc_bitmap_not()

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

hwloc_bitmap_only()

void hwloc_bitmap_only	(	hwloc_bitmap_t	bitmap,
		unsigned	id
	)

Empty the bitmap bitmap and add bit id.

hwloc_bitmap_or()

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

hwloc_bitmap_set()

void hwloc_bitmap_set	(	hwloc_bitmap_t	bitmap,
		unsigned	id
	)

Add index id in bitmap bitmap.

hwloc_bitmap_set_ith_ulong()

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_bitmap_set_range()

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_bitmap_singlify()

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_bitmap_snprintf()

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

hwloc_bitmap_sscanf()

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

Parse a bitmap string and stores it in bitmap bitmap.

hwloc_bitmap_taskset_asprintf()

int hwloc_bitmap_taskset_asprintf	(	char **	strp,
		hwloc_const_bitmap_t	bitmap
	)

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

Returns

-1 on error.

hwloc_bitmap_taskset_snprintf()

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

hwloc_bitmap_taskset_sscanf()

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.

hwloc_bitmap_to_ith_ulong()

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.

hwloc_bitmap_to_ulong()

unsigned long hwloc_bitmap_to_ulong

(

hwloc_const_bitmap_t

bitmap

)

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

hwloc_bitmap_weight()

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.

-1 if bitmap is infinitely set.

hwloc_bitmap_xor()

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

hwloc_bitmap_zero()

void hwloc_bitmap_zero

(

hwloc_bitmap_t

bitmap

)

Empty the bitmap bitmap.