topoInit

Initialize the hardware topology package

Synopsis

int topoInit(int isVerbose, topoinfo_t **topo_p)

Input Parameter

isVerbose
If true, provide verbose output to stdout about the operation of the routines.

Output Parameter

topo_p
On successful exit, points to a topoinfo_t structure. This lists the topology of the system in which the calling process is executing starting from processor cores and working out. See notes below.

Collective

This routine is collective over all processes in the job. It is not necessarily synchronizing, but some systems may require collective operations in order to return the requested data.

Return value

0 on success, non-zero on failure.

Environment Variables

TOPO_CORESPERCHIP
If set to an integer value (as a string), then every socket (processor chip) is considered to have this many cores.
TOPO_CHIPSPERNODE
If set to an integer value (as a string), then every node is considered to have this many chips (sockets).

Notes

The topo package is designed for massively parallel systems with regular networks, such as a torus or mesh. If the hwloc package is available, this package can use hwloc to provide some information about the node topology. The topoinfo_t structure provides a list of entries, starting with the finest grain (typically a core, but could be a chip or node if more detailed information is not available).

Systems Supported

Note - only IBM, Cray, and HWLOC currently implemented.

IBM Blue Gene/Q
Provides interconnect mesh coordinates
Cray XE6 and XK7
Provides interconnent mesh coordinates and core number; with TOPO_CORESPERCHIP correctly set, also provides socket number
Miscellaneous MPI programs that have MPI_Comm_split_type. This
routine may be used to determine a topology based on processes that can share memory. This is represented as a TOPO_NODE.
Miscellaneous Unix systems
With hwloc, provides node information. if sched_getcpu is available, this is used to find the core number (use the environment variable TOPO_CORESPERCHIP to identify to which chip in a multi-chip node a core belongs). Without hwloc, the code uses the hostname to identify processes that share the same hostname, and identifies these as belonging to the same TOPO_NODE.

Thread safety

If called by multiple threads, they must provide the same value for isVerbose.