Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
hwlocality_bitmap(3)	   Hardware Locality (hwloc)	  hwlocality_bitmap(3)

NAME
       hwlocality_bitmap - The bitmap API

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

Detailed Description
       The hwloc_bitmap_t type represents a set	of integers (positive or
       null). 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.

       Bitmaps are used	by hwloc for sets of OS	processors (which may actually
       be hardware threads) as by hwloc_cpuset_t (a typedef for
       hwloc_bitmap_t),	or sets	of NUMA	memory nodes as	hwloc_nodeset_t	(also
       a typedef for hwloc_bitmap_t). Those are	used for cpuset	and nodeset
       fields in the hwloc_obj structure, see Object Sets (hwloc_cpuset_t and
       hwloc_nodeset_t).

       Both CPU	and node sets are always indexed by OS physical	number.
       However users should usually not	build CPU and node sets	manually (e.g.
       with hwloc_bitmap_set()). One should rather use existing	object sets
       and combine them	with hwloc_bitmap_or(),	etc. For instance, binding the
       current thread on a pair	of cores may be	performed with:

       hwloc_obj_t core1 = ... , core2 = ... ;
       hwloc_bitmap_t set = hwloc_bitmap_alloc();
       hwloc_bitmap_or(set, core1->cpuset, core2->cpuset);
       hwloc_set_cpubind(topology, set,	HWLOC_CPUBIND_THREAD);
       hwloc_bitmap_free(set);

       Note
	   Most	functions below	return an int that may be negative in case of
	   error. The usual error case would be	an internal failure to
	   realloc/extend the storage of the bitmap (errno would be set	to
	   ENOMEM).

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

   #define hwloc_bitmap_foreach_end()
       End of loop macro iterating on a	bitmap.	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 const struct	hwloc_bitmap_s*	hwloc_const_bitmap_t
       a non-modifiable	hwloc_bitmap_t

Function Documentation
   int 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.

   int 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

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

       Returns
	   -1 on error.

   int hwloc_bitmap_clr	(hwloc_bitmap_t	bitmap,	unsigned id)
       Remove index id from bitmap bitmap.

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

   int hwloc_bitmap_compare_first (hwloc_const_bitmap_t	bitmap1,
       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.

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

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

       Returns
	   -1 if no index is unset in bitmap.

   void	hwloc_bitmap_free (hwloc_bitmap_t bitmap)
       Free bitmap bitmap. If bitmap is	NULL, no operation is performed.

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

   int hwloc_bitmap_from_ulong (hwloc_bitmap_t bitmap, unsigned	long mask)
       Setup bitmap bitmap from	unsigned long mask.

   int hwloc_bitmap_from_ulongs	(hwloc_bitmap_t	bitmap,	unsigned nr, const
       unsigned	long * masks)
       Setup bitmap bitmap from	unsigned longs masks used as first nr subsets.

   int hwloc_bitmap_intersects (hwloc_const_bitmap_t bitmap1,
       hwloc_const_bitmap_t bitmap2)
       Test whether bitmaps bitmap1 and	bitmap2	intersects.

       Returns
	   1 if	bitmaps	intersect, 0 otherwise.

   int hwloc_bitmap_isequal (hwloc_const_bitmap_t bitmap1,
       hwloc_const_bitmap_t bitmap2)
       Test whether bitmap bitmap1 is equal to bitmap bitmap2.

       Returns
	   1 if	bitmaps	are equal, 0 otherwise.

   int hwloc_bitmap_isfull (hwloc_const_bitmap_t bitmap)
       Test whether bitmap bitmap is completely	full.

       Returns
	   1 if	bitmap is full,	0 otherwise.

       Note
	   A full bitmap is always infinitely set.

   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.

       Returns
	   1 if	sub_bitmap is included in super_bitmap,	0 otherwise.

       Note
	   The empty bitmap is considered included in any other	bitmap.

   int hwloc_bitmap_isset (hwloc_const_bitmap_t	bitmap,	unsigned id)
       Test whether index id is	part of	bitmap bitmap.

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

   int hwloc_bitmap_iszero (hwloc_const_bitmap_t bitmap)
       Test whether bitmap bitmap is empty.

       Returns
	   1 if	bitmap is empty, 0 otherwise.

   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.

   int hwloc_bitmap_last_unset (hwloc_const_bitmap_t bitmap)
       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.

   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.

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

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

   int hwloc_bitmap_next_unset (hwloc_const_bitmap_t bitmap, int prev)
       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.

   int 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

   int hwloc_bitmap_nr_ulongs (hwloc_const_bitmap_t 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.

   int hwloc_bitmap_only (hwloc_bitmap_t bitmap, unsigned id)
       Empty the bitmap	bitmap and add bit id.

   int 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

   int hwloc_bitmap_set	(hwloc_bitmap_t	bitmap,	unsigned id)
       Add index id in bitmap bitmap.

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

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

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

   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.

       Returns
	   -1 on error.

   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_to_ulongs (hwloc_const_bitmap_t bitmap, unsigned 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

   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.

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

Author
       Generated automatically by Doxygen for Hardware Locality	(hwloc)	from
       the source code.

Version	2.7.0			Mon Dec	6 2021		  hwlocality_bitmap(3)

NAME | SYNOPSIS | Detailed Description | Macro Definition Documentation | Typedef Documentation | Function Documentation | Author

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=hwlocality_bitmap&sektion=3&manpath=FreeBSD+13.1-RELEASE+and+Ports>

home | help