Bernd Kallies


Sys::Hwloc::Topology - Class representing a hwloc topology context


       use Sys::Hwloc;

       $topology = Sys::Hwloc::Topology->init;
       $rc = $topology->load;

       $rc     = $topology->ignore_type( $type );
       $rc     = $topology->ignore_type_keep_structure( $type );
       $rc     = $topology->ignore_all_keep_structure;
       $rc     = $topology->set_flags( $flags );
       $rc     = $topology->set_fsroot( $path );
       $rc     = $topology->set_pid( $pid );
       $rc     = $topology->set_synthetic( $string );
       $rc     = $topology->set_xml( $path );
       $href   = $topology->get_support;

       $topology->export_xml( $path );

       $depth  = $topology->depth;
       $depth  = $topology->get_type_depth( $type );
       $type   = $topology->get_depth_type( $depth );
       $type   = $topology->get_type_or_below_depth( $type );
       $type   = $topology->get_type_or_above_depth( $type );
       $nbobjs = $topology->get_nbobjs_by_depth( $depth );
       $nbobjs = $topology->get_nbobjs_by_type( $type );
       $rc     = $topology->is_thissystem;

       $obj    = $topology->root;
       $obj    = $topology->get_obj_by_depth( $depth, $idx );
       $obj    = $topology->get_obj_by_type( $type, $idx );
       $obj    = $topology->get_next_obj_by_depth( $depth, $obj );
       $obj    = $topology->get_next_obj_by_type( $type, $obj );
       $obj    = $topology->get_pu_obj_by_os_index( $idx );
       $obj    = $topology->get_common_ancestor_obj( $obj1, $obj2 );
       $rc     = $topology->obj_is_in_subtree( $obj1, $obj2 );
       @objs   = $topology->get_closest_objs( $obj );
       $obj    = $topology->get_obj_below_by_type( $type1, $idx1, $type2, $idx2 );
       $rc     = $topology->compare_objects( $obj1, $obj2 );

       $string = $topology->sprintf_obj( $obj, $prefix, $verbose );

       $rc     = $topology->set_cpubind( $set, $flags );
       $rc     = $topology->set_proc_cpubind( $pid, $set, $flags );
       $rc     = $topology->get_cpubind( $set, $flags );
       $rc     = $topology->get_proc_cpubind( $pid, $set, $flags);

       $rc     = $topology->set_membind( $set, $policy, $flags );
       $rc     = $topology->set_membind_nodeset( $set, $policy, $flags );
       $rc     = $topology->set_proc_membind( $pid, $set, $policy, $flags );
       $rc     = $topology->set_proc_membind_nodeset( $pid, $set, $policy, $flags );
       $rc     = $topology->get_membind( $set, \$policy, $flags );
       $rc     = $topology->get_membind_nodeset( $set, \$policy, $flags );
       $rc     = $topology->get_proc_membind( $pid, $set, \$policy, $flags );
       $rc     = $topology->get_proc_membind_nodeset( $pid, $set, \$policy, $flags );

       $set    = $topology->get_complete_cpuset;
       $set    = $topology->get_topology_cpuset;
       $set    = $topology->get_online_cpuset;
       $set    = $topology->get_allowed_cpuset;
       $set    = $topology->get_complete_nodeet;
       $set    = $topology->get_topology_nodeset;
       $set    = $topology->get_allowed_nodeset;

       $topology->cpuset_to_nodeset( $cpuset, $nodeset );
       $topology->cpuset_to_nodeset_strict( $cpuset, $nodeset );
       $topology->cpuset_from_nodeset( $cpuset, $nodeset );
       $topology->cpuset_from_nodeset_strict( $cpuset, $nodeset );

       $rc   = $topology->get_nbobjs_inside_cpuset_by_depth( $cpuset, $depth );
       $rc   = $topology->get_nbobjs_inside_cpuset_by_type( $cpuset, $type );
       $obj  = $topology->get_obj_inside_cpuset_by_depth( $cpuset, $depth );
       $obj  = $topology->get_obj_inside_cpuset_by_type( $cpuset, $type );
       $obj  = $topology->get_next_obj_inside_cpuset_by_depth( $cpuset, $depth, $prev );
       $obj  = $topology->get_next_obj_inside_cpuset_by_type( $cpuset, $type, $prev );
       $obj  = $topology->get_first_largest_obj_inside_cpuset( $cpuset );
       @objs = $topology->get_largest_objs_inside_cpuset( $cpuset );


Sys::Hwloc::Topology is the Perl namespace used for struct hwloc_topology data.

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

A Sys::Hwloc::Topology instance is created with hwloc_topology_init() or Sys::Hwloc::Topology->init().

The topology context is built with hwloc_topology_load($topology) or $topology->load().

The underlying C data must become freed with hwloc_topology_destroy($topology) or $topology->destroy().


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

  $topology = Sys::Hwloc::Topology->init();

Allocates and returns a topology context. Returns a new Sys::Hwloc::Topology instance on success, returns undef on error.


Terminates and frees an allocated topology context.

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

  $support = $topology->get_support;

Retrieves the topology support as reference to a hash.

The corresponding hwloc C API function returns a pointer to a struct hwloc_topology_support, instead.

As with hwloc v1.1, the topology support hashref consists of the following:

  $rc = $topology->compare_objects( $obj1, $obj2 );

Compares two Sys::Hwloc::Obj instances. Returns 1, if they are equal. Returns 0, if they are not equal.

Comparison is done by comparing the underlying raw hwloc_obj_t pointer values.

  $string = $topology->sprintf_obj( $obj, $prefix, $verbose );

This method is an alias of Sys::Hwloc::hwloc_obj_sprintf($prefix,$verbose).

It returns a string that represents a given topology object in human-readable form.

The arguments $prefix and $verbose are optional, and default to undef and 0, respectively. The handling of these defaults is done by the hwloc C API.

Note that this method is regarded as depreciated in hwloc-1.1.

  @objs = $topology->get_closest_objs( $obj );

The method returns an array of up to 1024 Sys::Hwloc::Obj objects that are closest to $obj.

  @objs = $topology->get_largest_objs_inside_cpuset( $set );

The method returns an array of up to 1024 Sys::Hwloc::Obj objects that cover exactly cpuset $set.


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


Bernd Kallies, <>


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.