Sys::Hwloc ========== This is a perl binding for the Portable Hardware Locality (hwloc) library. See http://www.open-mpi.org/projects/hwloc/ for details. DEPENDENCIES ------------ This module requires hwloc >= 0.9 (recommended: >= 1.1) Makefile.PL uses ExtUtils::MakeMaker and ExtUtils::Constant to create the Makefile. Parts of the test suite need Test::More >= 0.89. The module was tested on some i686/intel64 machines running recent Linux and Perl 5.8.8 or 5.10. Other architectures were not tested. The Windows OS is currently not supported. INSTALLATION ------------ To install this module, type the following: perl Makefile.PL make make test make install hwloc libraries and header files are searched for by using pkg-config. If they cannot be found, set the PKG_CONFIG_PATH environment variable to the directory where the file hwloc.pc is located. EXAMPLE SCRIPTS --------------- Look into the examples directory to get inspired. HWLOC API VERSION ----------------- The configure step figures out the value of the HWLOC_API_VERSION constant from hwloc.h, and compiles and exports Hwloc functions accordingly. Thus, the Hwloc module depends on the hwloc version against which it was built. Undefined results are got when another hwloc library version is used at runtime. This constant was introduced in hwloc 1.0. For earlier hwloc versions, the Hwloc module exports this constant with an undefined value. For convenience, the Hwloc module also exports the constant HWLOC_XSAPI_VERSION, which is always defined. These constants can be used in a Perl script using Hwloc as follows to make it work with different HWLOC_API_VERSIONs: $proc_t = HWLOC_API_VERSION() ? HWLOC_OBJ_PU() : HWLOC_OBJ_PROC(); To bind a Perl script to a specific hwloc API version, check it in a BEGIN block: BEGIN { die "This script needs HWLOC_XSAPI_VERSION >= 0x00010000\n" unless HWLOC_XSAPI_VERSION() >= 0x00010000; } The compatibility matrix of released hwloc versions with Sys::Hwloc is 0.9.1 not tested 0.9.2 works (some tests fail due to unspecified C API behaviour) 0.9.3 works (some tests fail due to unspecified C API behaviour) 1.0 not tested 1.0.1 not tested 1.0.2 works 1.0.3 works 1.1 works (tests 08-bitmap 2,59 fail due to hwloc bug) XML SUPPORT ----------- The configure step tries to figure out if the hwloc library was built with XML support. Depending on the result, Hwloc functions dealing with XML are compiled and exported or not, and the special constant Sys::Hwloc::HWLOC_HAS_XML is exported with a true or false value. It can be used in Perl scripts using Hwloc as follows: if(HWLOC_HAS_XML) { $topology->export_xml('-'); } else { die "Your hwloc lib was built without XML support"; } CPUSETS, NODESETS, BITMAPS -------------------------- In hwloc 0.9 and 1.0 a hwloc_obj struct defines the struct members cpuset and nodeset with C type hwloc_cpuset. Data of type hwloc_cpuset become created and manipulated with functions of the Cpuset API. When built with these hwloc versions, the Sys::Hwloc module exports the functions of the Cpuset API with EXPORT_TAG :cpuset, blesses these data into the namespace Sys::Hwloc::Cpuset, and provides OO-ish methods for them. In hwloc 1.1 a hwloc_obj struct defines struct members with C type hwloc_cpuset, and struct members with C type hwloc_nodeset. Both C types are aliases of the C type hwloc_bitmap. These data become created and manipulated with functions of the Bitmap API. When built with these hwloc versions, the Sys::Hwloc module exports the functions of the Bitmap API with EXPORT_TAG :bitmap, blesses these data into the namespace Sys::Hwloc::Bitmap, and provides OO-ish methods for them. A distrinction between the C types hwloc_cpuset and hwloc_nodeset is not made. TESTING ------- The test suite runs tests against the hwloc topology of the current machine. Arbitrary topologies can be tested when Hwloc was compiled with XML support. Set the HWLOC_XMLFILE environment variable to the path of an XML file describing the topology, and run the test suite. The test suite makes assumptions about what C API functions should return, based on the docs and observed behaviour of hwloc-1.0. Some tests may apparently fail when testing return values, if other versions are used and the hwloc C API behaves differently. TODO ---- - extend XML support by using XML::LibXML BUGS ---- Note that this is a wrapper, which cannot correct bugs in the underlying hwloc library. If you feel that you found a wrapper bug, report it via https://rt.cpan.org/ If you feel that you found a hwloc bug, refer to http://www.open-mpi.org/projects/hwloc/ how to report it. 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.