NAME

Sys::Hwloc::Obj - Class representing a hwloc topology object

SYNOPSIS

       use Sys::Hwloc;

       $obj    = $topology->get_obj_by_depth( $depth, $idx );
       $obj    = $topology->get_obj_by_type( $type, $idx );

       $type   = $obj->type;
       $idx    = $obj->os_index;
       $name   = $obj->name;
       $href   = $obj->memory;
       $href   = $obj->attr;
       $depth  = $obj->depth;
       $idx    = $obj->logical_index;
       $level  = $obj->os_level;
       $oobj   = $obj->next_cousin;
       $oobj   = $obj->prev_cousin;
       $oobj   = $obj->parent;
       $rank   = $obj->sibling_rank;
       $oobj   = $obj->next_sibling;
       $oobj   = $obj->prev_sibling;
       $arity  = $obj->arity;
       @oobjs  = $obj->children;
       $oobj   = $obj->first_child;
       $oobj   = $obj->last_child;
       $set    = $obj->cpuset;
       $set    = $obj->complete_cpuset;
       $set    = $obj->online_cpuset;
       $set    = $obj->allowed_cpuset;
       $set    = $obj->nodeset;
       $set    = $obj->complete_nodeset;
       $set    = $obj->allowed_nodeset;
       $href   = $obj->infos;

       $string = $obj->sprintf_type( $verbose );
       $string = $obj->sprintf_attr( $separator, $verbose );
       $string = $obj->sprintf_cpuset;
       $string = $obj->sprintf( $prefix, $verbose );
       $string = $obj->info_by_name ( $name );

       $oobj   = $obj->ancestor_by_depth( $depth );
       $oobj   = $obj->ancestor_by_type( $type );
       $oobj   = $obj->next_child( $oobj );
       $oobj   = $obj->common_ancestor( $oobj );

       $rc     = $obj->is_same_obj( $oobj );

DESCRIPTION

Sys::Hwloc::Obj is the Perl namespace used for struct hwloc_obj data.

The Sys::Hwloc::Obj class provides an object-oriented interface for members of struct hwloc_obj, and for hwloc C functions that act on topology objects without involving the topology context. In particular, every hwloc C function that gets a hwloc_obj pointer as first argument has an OO-ish counterpart in Sys::Hwloc::Obj.

There are no constructors and destructors of Sys::Hwloc::Obj instances.

A Sys::Hwloc::Obj instance is retrieved either from a Sys::Hwloc::Topology instance, or from another Sys::Hwloc::Obj instance.

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.

memory

  $memory = $obj->memory;

Retrieves the object memory as reference to a hash.

The corresponding hwloc C struct member points to a struct hwloc_obj_memory_s.

As with hwloc-1.1, the memory hashref consists of the following:

  $memory->{total_memory}
  $memory->{local_memory}
  $memory->{page_types_len}
  @{$memory->{page_types}}

The $memory->{page_types} array reference contains $memory->{page_types_len} references to hashes with

  $memory->{page_types}->[$i]->{size}
  $memory->{page_types}->[$i]->{count}

attr

  $attrs = $obj->attr;

Retrieves the object attributes as reference to a hash.

The corresponding hwloc C struct member points to a union hwloc_obj_attr_u.

The content of the attrs hashref depends on the object type and the hwloc version, and may be empty.

As with hwloc-1.1, if e.g. $obj->type == HWLOC_OBJ_CACHE, there will be

  $obj->attr->{cache}->{depth}
  $obj->attr->{cache}->{size}
  $obj->attr->{cache}->{linesize}

To inspect the content, parse it like

  while(my ($key, $value) = each %{$obj->attr}) {
    ...
  }

children

  @oobj = $obj->children;

Returns an array with Sys::Hwloc::Obj instances representing the child objects of $obj. The returned array has $obj->arity members. If $obj->arity is 0, the array is empty.

The array may be processed by array index or with foreach() and the like. The following constructs are equivalent:

  for($i = 0; $i < $obj->arity; $i++) {
    $type = ($obj->children)[$i]->type;
  }

  foreach($obj->children) {
    $type = $_->type;
  }

cpuset

  $set = $obj->cpuset

Returns an object that represents the object's cpuset.

Before hwloc-1.1, this method returns an instance of Sys::Hwloc::Cpuset.

Since hwloc-1.1, this method returns an instance of Sys::Hwloc::Bitmap. A class Sys::Hwloc::Cpuset does not exist.

nodeset

  $set = $obj->nodeset

Returns an object that represents the object's nodeset.

In hwloc-1.0, this method returns an instance of Sys::Hwloc::Cpuset. There is no class Sys::Hwloc::Nodeset.

Since hwloc-1.1, this method returns an instance of Sys::Hwloc::Bitmap. A class Sys::Hwloc::Nodeset does not exist.

infos

  $infos = $obj->infos;

Retrieves the object info as reference to a hash.

The corresponding hwloc C struct member points to an array of struct hwloc_obj_info_s.

The $infos hash represents individual object infos as name->value pairs.

There also exists the method $obj->info_by_name($name), which allows the retrieval of an individual value that corresponds to a name key via the hwloc C API directly from the topology object.

A method infos_count that returns the extent of the $infos hash is not provided.

sprintf_type

  $string = $obj->sprintf_type( $verbose );

This method is an alias of Sys::Hwloc::hwloc_obj_type_sprintf($obj,$verbose).

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

The argument $verbose is optional, and defaults to 0. The handling of this default is done by the hwloc C API.

sprintf_attr

  $string = $obj->sprintf_attr( $separator, $verbose );

This method is an alias of Sys::Hwloc::hwloc_obj_attr_sprintf($obj,$separator,$verbose).

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

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

sprintf_cpuset

  $string = $obj->sprintf_cpuset;

This method is an alias of Sys::Hwloc::hwloc_obj_cpuset_sprintf($obj).

It returns a string that represents the cpuset of a given single topology object in human-readable form.

The call $obj-cpuset->sprintf> yields the same result.

In contrast to that, the function Sys::Hwloc::hwloc_obj_cpuset_sprintf() understands more than one object in its argument list.

sprintf

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

This method is an alias of Sys::Hwloc::hwloc_obj_sprintf($obj,$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.

is_same_obj

  $rc = $obj->is_same_obj( $oobj );

Compares the Sys::Hwloc::Obj instance $obj with the Sys::Hwloc::Obj instance $oobj.

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.

The method is an alias for Sys::Hwloc::hwloc_compare_objects($topo,$obj1,$obj2).

SEE ALSO

hwloc(7), Sys::Hwloc::Topology(3pm), Sys::Hwloc::Cpuset(3pm), Sys::Hwloc::Bitmap(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.