Defines | Typedefs | Functions

The bitmap API

Defines

#define hwloc_bitmap_foreach_begin(id, bitmap)
 Loop macro iterating on bitmap bitmap.
#define hwloc_bitmap_foreach_end()
 End of loop. Needs a terminating ';'.

Typedefs

typedef struct hwloc_bitmap_s * hwloc_bitmap_t
 Set of bits represented as an opaque pointer to an internal bitmap.
typedef struct hwloc_bitmap_s * hwloc_const_bitmap_t

Functions

HWLOC_DECLSPEC hwloc_bitmap_t hwloc_bitmap_alloc (void) __hwloc_attribute_malloc
 Allocate a new empty bitmap.
HWLOC_DECLSPEC hwloc_bitmap_t hwloc_bitmap_alloc_full (void) __hwloc_attribute_malloc
 Allocate a new full bitmap.
HWLOC_DECLSPEC void hwloc_bitmap_free (hwloc_bitmap_t bitmap)
 Free bitmap bitmap.
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.
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.
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_taskset_snprintf (char *__hwloc_restrict buf, size_t buflen, hwloc_const_bitmap_t bitmap)
 Stringify a bitmap in the taskset-specific format.
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, unsigned end)
 Add indexess from begin to end in bitmap bitmap.
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, unsigned end)
 Remove index from begin to end in bitmap bitmap.
HWLOC_DECLSPEC void hwloc_bitmap_singlify (hwloc_bitmap_t bitmap)
 Keep a single index among those set in bitmap bitmap.
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.
HWLOC_DECLSPEC int hwloc_bitmap_next (hwloc_const_bitmap_t bitmap, unsigned prev) __hwloc_attribute_pure
 Compute the next index in bitmap bitmap which is after index prev.
HWLOC_DECLSPEC int hwloc_bitmap_last (hwloc_const_bitmap_t bitmap) __hwloc_attribute_pure
 Compute the last index (most significant bit) in bitmap bitmap.
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).
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.
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.

Detailed Description

For use in hwloc itself, a hwloc_bitmap_t usually represents a set of objects, typically logical processors or memory nodes, indexed by OS physical number.

A bitmap may be infinite.


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

End of loop. Needs a terminating ';'.

See also:
hwloc_bitmap_foreach_begin

Typedef Documentation

typedef struct hwloc_bitmap_s* hwloc_bitmap_t

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

typedef struct hwloc_bitmap_s* hwloc_const_bitmap_t

Function Documentation

HWLOC_DECLSPEC void hwloc_bitmap_allbut ( hwloc_bitmap_t  bitmap,
unsigned  id 
)

Fill the bitmap and clear the index id.

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

HWLOC_DECLSPEC hwloc_bitmap_t hwloc_bitmap_alloc_full ( void   ) 

Allocate a new full bitmap.

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 int hwloc_bitmap_asprintf ( char **  strp,
hwloc_const_bitmap_t  bitmap 
)

Stringify a bitmap into a newly allocated string.

Returns:
the number of character that were actually written (not including the ending \0).
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,
unsigned  end 
)

Remove index from begin to end in bitmap bitmap.

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.

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 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 hwloc_bitmap_t hwloc_bitmap_dup ( hwloc_const_bitmap_t  bitmap  ) 

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

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

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_from_ulong ( hwloc_bitmap_t  bitmap,
unsigned long  mask 
)

Setup bitmap bitmap from unsigned long mask.

HWLOC_DECLSPEC int hwloc_bitmap_intersects ( hwloc_const_bitmap_t  bitmap1,
hwloc_const_bitmap_t  bitmap2 
)

Test whether bitmaps bitmap1 and bitmap2 intersects.

HWLOC_DECLSPEC int hwloc_bitmap_isequal ( hwloc_const_bitmap_t  bitmap1,
hwloc_const_bitmap_t  bitmap2 
)

Test whether bitmap bitmap1 is equal to bitmap bitmap2.

HWLOC_DECLSPEC int hwloc_bitmap_isfull ( hwloc_const_bitmap_t  bitmap  ) 

Test whether bitmap bitmap is completely full.

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

HWLOC_DECLSPEC int hwloc_bitmap_isset ( hwloc_const_bitmap_t  bitmap,
unsigned  id 
)

Test whether index id is part of bitmap bitmap.

HWLOC_DECLSPEC int hwloc_bitmap_iszero ( hwloc_const_bitmap_t  bitmap  ) 

Test whether bitmap bitmap is empty.

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_next ( hwloc_const_bitmap_t  bitmap,
unsigned  prev 
)

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

Returns:
-1 if no index with higher index is bitmap.
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 void hwloc_bitmap_only ( hwloc_bitmap_t  bitmap,
unsigned  id 
)

Empty the bitmap bitmap and add bit id.

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_set ( hwloc_bitmap_t  bitmap,
unsigned  id 
)

Add index id in bitmap bitmap.

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_set_range ( hwloc_bitmap_t  bitmap,
unsigned  begin,
unsigned  end 
)

Add indexess from begin to end in bitmap bitmap.

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.

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_sscanf ( hwloc_bitmap_t  bitmap,
const char *__hwloc_restrict  string 
)

Parse a bitmap string and stores it in bitmap bitmap.

Must start and end with a digit.

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

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 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_DECLSPEC unsigned long hwloc_bitmap_to_ulong ( hwloc_const_bitmap_t  bitmap  ) 

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

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.
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_zero ( hwloc_bitmap_t  bitmap  ) 

Empty the bitmap bitmap.