The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Sys::Hwloc::Bitmap - Class representing a hwloc bitmap object

SYNOPSIS

       use Sys::Hwloc;

       $map  = Sys::Hwloc::Bitmap->alloc;
       $omap = $map->dup;
       $map->copy( $omap );
       $map->free;

       $map->zero;
       $map->fill;
       $map->only( $id );
       $map->allbut( $id );
       $map->from_ulong( $mask );
       $map->from_ith_ulong( $i, $mask );
       $rc   = $map->sscanf( $string );
       $rc   = $map->sscanf_list( $string );
       $rc   = $map->sscanf_taskset( $string );
       $map->set( $id );
       $map->set_range( $ida, $ide );
       $map->set_ith_ulong( $i, $mask );
       $map->clr( $id );
       $map->clr_range( $ida, $ide );
       $map->singlify;

       $val  = $map->ulong;
       $val  = $map->to_ith_ulong( $i );
       $val  = $map->sprintf;
       $val  = $map->sprintf_list;
       $val  = $map->sprintf_taskset;
       @ids  = $map->ids;

       $rc   = $map->isset( $id );
       $rc   = $map->iszero;
       $rc   = $map->isfull;

       $id   = $map->first;
       $id   = $map->next( $previd );
       $id   = $map->last;

       $val  = $map->weight;

       $map->or( $omap );
       $map->and( $omap );
       $map->andnot( $omap );
       $map->xor( $omap );
       $map->not;

       $rc   = $map->intersects( $omap );
       $rc   = $map->includes( $omap );
       $rc   = $map->isincluded( $omap );
       $rc   = $map->isequal( $omap );
       $rc   = $map->compare( $omap );
       $rc   = $map->compare_first( $omap );

DESCRIPTION

Sys::Hwloc::Bitmap is the Perl namespace used for struct hwloc_cpuset and struct hwloc_nodeset data since hwloc-1.1.

Before hwloc-1.1, similar functionality was provided by Sys::Hwloc::Cpuset.

The Sys::Hwloc::Bitmap class provides an object-oriented interface for hwloc C functions that act on bitmap objects. In particular, every hwloc C function that gets a hwloc_bitmap pointer as first argument has an OO-ish counterpart in Sys::Hwloc::Bitmap.

A Sys::Hwloc::Bitmap instance is created with hwloc_bitmap_alloc() or Sys::Hwloc::Bitmap->alloc().

The underlying C data must become freed with hwloc_bitmap_free() or $bitmap->free().

METHODS

Refer to http://www.open-mpi.org/projects/hwloc for the full specification.

This section lists only methods that are specific to Sys::Hwloc. These are methods, which have no pendants in the hwloc C API, or which behave differently compared to their hwloc C API counterparts.

alloc
  $map = Sys::Hwloc::Bitmap->alloc();

Allocates and returns a bitmap. Returns a new Sys::Hwloc::Bitmap instance on success, returns undef on error.

free
  $set->free();

Frees an allocated bitmap.

There is no automatic Perl destructor Sys::Hwloc::Bitmap::DESTROY. That means, if an initialized bitmap variable goes out of scope or gets another value assigned, the C bitmap is not freed. This conforms to the usage of the hwloc C API, but unfortunately not to the rules of OO in Perl.

ids
  @ids = $map->ids;

Returns the bits that are set in a bitmap as an array of unsigned numbers.

The method is a replacement of the hwloc C API macro pair hwloc_bitmap_foreach_begin and hwloc_bitmap_foreach_end.

The following example shows the use of the hwloc C API macros, and what the Perl ids method does:

  /* This is C */
  unsigned id;
  hwloc_bitmap_foreach_begin(id, map) {
    printf("id = %u\n", id);
  }
  hwloc_bitmap_foreach_end();

  # This is Perl
  foreach $id ($map->ids) {
    printf "id = %u\n", $id;
  }
sprintf_list
  $string = $map->sprintf_list

Returns a string containing the bits set in a bitmap as a comma-separated list of decimal numbers and ranges of numbers. The format conforms to the List Format of Linux cpusets, see cpuset(7).

This method is currently not part of the hwloc C API.

The following example script will print "0-7,16,17,24-27".

  $map = Sys::Hwloc::Bitmap->alloc;
  $map->set_range(0,7);
  $map->set_range(16,17);
  $map->set_range(24,27);
  printf "%s\n", $map->sprintf_list;
  $map->free;
sscanf_list
  $rc = $map->sscanf_list( $string );

Parses a Linux cpuset(7) list format ASCII string and stores it in bitmap $map.

Returns 0 on success, -1 on error. If error, the content of $map is undefined.

This method is currently not part of the hwloc C API. It is the reverse of $string = $map->sprintf_list.

includes
  $rc = $map->includes( $omap );

Tests wether $omap is part of $map.

This method is not part of the hwloc C API. It is equivalent to $omap->isincluded($map).

or
  $map->or( $omap );

ORes $map with $omap, similar to |=.

The long version of this in pure hwloc is:

  $tempmap = hwloc_bitmap_alloc;
  hwloc_bitmap_or($tempmap, $map, $omap);
  hwloc_bitmap_free($map);
  $map = $tempmap;
and
  $map->and( $omap );

ANDs $map with $omap, similar to &=.

The long version of this in pure hwloc is:

  $tempmap = hwloc_bitmap_alloc;
  hwloc_bitmap_and($tempmap, $map, $omap);
  hwloc_bitmap_free($map);
  $map = $tempmap;
andnot
  $map->andnot( $omap );

ANDs $map with the negation of $omap.

The long version of this in pure hwloc is:

  $tempmap = hwloc_bitmap_alloc;
  hwloc_bitmap_andnot($tempmap, $map, $omap);
  hwloc_bitmap_free($map);
  $map = $tempmap;
xor
  $map->xor( $omap );

XORes $map with $omap, similar to ^=.

The long version of this in pure hwloc is:

  $tempmap = hwloc_bitmap_alloc;
  hwloc_bitmap_xor($tempmap, $map, $omap);
  hwloc_bitmap_free($map);
  $map = $tempmap;
not
  $map->not;

Negates $map.

The long version of this in pure hwloc is:

  $tempmap = hwloc_bitmap_alloc;
  hwloc_bitmap_not($tempmap, $map);
  hwloc_bitmap_free($map);
  $map = $tempmap;

SEE ALSO

hwloc(7), Sys::Hwloc::Topology(3pm), Sys::Hwloc::Obj(3pm), Sys::Hwloc::Cpuset(3pm)

AUTHOR

Bernd Kallies, <kallies@zib.de>

COPYRIGHT AND LICENSE

Copyright (C) 2011 Zuse Institute Berlin

This package and its accompanying libraries is free software; you can redistribute it and/or modify it under the terms of the GPL version 2.0, or the Artistic License 2.0. Refer to LICENSE for the full license text.