hwloc

package module
v0.0.0-...-0e7d07c Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 12, 2023 License: MIT Imports: 3 Imported by: 0

README

go-hwloc

Build Status Go Doc

Introduction

Golang binding for static hwloc

Ready

Install hwloc from your system package manager or compile from the source in https://github.com/open-mpi/hwloc

For example:

# Static Build
git clone https://github.com/open-mpi/hwloc && cd hwloc
./autogen.sh
./configure --enable-static --disable-shared LDFLAGS="-static"
make LDFLAGS=-all-static
sudo make install
sudo ldconfig /usr/local/lib

Usage

import hwloc "github.com/c0mm4nd/go-hwloc"

Extra

  • Q: Why not assemble hwloc into go lib?

A: hwloc is a very powerful and platform-based native library, so comparing to provide a simple version, I prefer to let developers compile it by their own hands or the binary for their platform.

  • Q: Why build fails when using bazel?

A: Bazel compiling project within a sandbox, which disallow linker find the "external" library, hwloc, so you should write BUILD.bazel and WORKSPACE for hwloc before using this go binding lib. Actually, it is what tensorflow does, and you can learn from their practice

Hwloc

Introduction

The Hardware Locality (hwloc) software project aims at easing the process of discovering hardware resources in parallel architectures. It offers command-line tools and a C API for consulting these resources, their locality, attributes, and interconnection. hwloc primarily aims at helping high-performance computing (HPC) applications, but is also applicable to any project seeking to exploit code and/or data locality on modern computing platforms.

hwloc is actually made of two subprojects distributed together:

  • The original hwloc project for describing the internals of computing nodes. It is described in details starting at section Hardware Locality (hwloc) Introduction.
  • The network-oriented companion called netloc (Network Locality), described in details starting with section Network Locality (netloc).

See also the Related pages tab above for links to other sections.

Netloc may be disabled, but the original hwloc cannot. Both hwloc and netloc APIs are documented after these sections.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// HwlocTopologyFlagIncludeDisallowed Detect the whole system, ignore reservations, include disallowed objects.
	/*
	 * Gather all resources, even if some were disabled by the administrator.
	 * For instance, ignore Linux Cgroup/Cpusets and gather all processors and memory nodes.
	 *
	 * When this flag is not set, PUs and NUMA nodes that are disallowed are not added to the topology.
	 * Parent objects (package, core, cache, etc.) are added only if some of their children are allowed.
	 * All existing PUs and NUMA nodes in the topology are allowed.
	 * hwloc_topology_get_allowed_cpuset() and hwloc_topology_get_allowed_nodeset()
	 * are equal to the root object cpuset and nodeset.
	 *
	 * When this flag is set, the actual sets of allowed PUs and NUMA nodes are given
	 * by hwloc_topology_get_allowed_cpuset() and hwloc_topology_get_allowed_nodeset().
	 * They may be smaller than the root object cpuset and nodeset.
	 *
	 * If the current topology is exported to XML and reimported later, this flag
	 * should be set again in the reimported topology so that disallowed resources
	 * are reimported as well.
	 */
	HwlocTopologyFlagIncludeDisallowed = HwlocTopologyFlags(uint64(1) << 0)
	// HwlocTopologyFlagIsThisSystem Assume that the selected backend provides the topology for the system on which we are running.
	/*
	 * This forces hwloc_topology_is_thissystem() to return 1, i.e. makes hwloc assume that
	 * the selected backend provides the topology for the system on which we are running,
	 * even if it is not the OS-specific backend but the XML backend for instance.
	 * This means making the binding functions actually call the OS-specific
	 * system calls and really do binding, while the XML backend would otherwise
	 * provide empty hooks just returning success.
	 *
	 * Setting the environment variable HWLOC_THISSYSTEM may also result in the
	 * same behavior.
	 *
	 * This can be used for efficiency reasons to first detect the topology once,
	 * save it to an XML file, and quickly reload it later through the XML
	 * backend, but still having binding functions actually do bind.
	 */
	HwlocTopologyFlagIsThisSystem = HwlocTopologyFlags(uint64(1) << 1)
	// HwlocTopologyFlagThisSystemAllowedResources Get the set of allowed resources from the local operating system even if the topology was loaded from XML or synthetic description.
	/*
	 * If the topology was loaded from XML or from a synthetic string,
	 * restrict it by applying the current process restrictions such as
	 * Linux Cgroup/Cpuset.
	 *
	 * This is useful when the topology is not loaded directly from
	 * the local machine (e.g. for performance reason) and it comes
	 * with all resources, while the running process is restricted
	 * to only parts of the machine.
	 *
	 * This flag is ignored unless ::HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM is
	 * also set since the loaded topology must match the underlying machine
	 * where restrictions will be gathered from.
	 *
	 * Setting the environment variable HWLOC_THISSYSTEM_ALLOWED_RESOURCES
	 * would result in the same behavior.
	 */
	HwlocTopologyFlagThisSystemAllowedResources = HwlocTopologyFlags(uint64(1) << 2)
)
View Source 
var NotImplementError = errors.New("not implemented")

Functions

This section is empty.

Types

type BitMap 

type BitMap struct {
	// contains filtered or unexported fields
}

BitMap is a struct containing a slice of bytes, being used as a bitmap.

func FromString 

func FromString(input string) (BitMap, error)

func NewBitmap 

func NewBitmap(set C.hwloc_bitmap_t) BitMap

NewBitmap returns a BitMap. It requires a size. A bitmap with a size of eight or less will be one byte in size, and so on.

func (BitMap) Destroy 

func (b BitMap) Destroy()

Destroy free the BitMap

func (BitMap) IsSet 

func (b BitMap) IsSet(i uint64) (bool, error)

IsSet returns a boolean indicating whether the bit is set for the position in question.

func (BitMap) IsZero 

func (b BitMap) IsZero() (bool, error)

IsZero Test whether bitmap is empty return 1 if bitmap is empty, 0 otherwise.

func (BitMap) Set 

func (b BitMap) Set(i uint64) error

Set sets a position in the bitmap to 1.

func (BitMap) String 

func (b BitMap) String() string

func (BitMap) Unset 

func (b BitMap) Unset(i uint64) error

Unset sets a position in the bitmap to 0.

func (BitMap) Values 

func (b BitMap) Values() ([]uint64, error)

Values returns a slice of ints represented by the values in the bitmap.

type HwlocAllowFlags 

type HwlocAllowFlags int

HwlocAllowFlags Flags to be given to hwloc_topology_allow(). 

const (
	// HwlocAllowFlagAll Mark all objects as allowed in the topology.
	//  cpuset and  nođeset given to hwloc_topology_allow() must be NULL
	HwlocAllowFlagAll HwlocAllowFlags = C.HWLOC_ALLOW_FLAG_ALL
	// HwlocAllowFlagLocalRestrictions Only allow objects that are available to the current process.
	// The topology must have ::HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM so that the set
	// of available resources can actually be retrieved from the operating system.
	// cpuset and nođeset given to hwloc_topology_allow() must be NULL.
	HwlocAllowFlagLocalRestrictions HwlocAllowFlags = C.HWLOC_ALLOW_FLAG_LOCAL_RESTRICTIONS
	// HwlocAllowFlagCustom Allow a custom set of objects, given to hwloc_topology_allow() as cpuset and/or nodeset parameters.
	HwlocAllowFlagCustom HwlocAllowFlags = C.HWLOC_ALLOW_FLAG_CUSTOM
)

type HwlocBridgeAttr 

type HwlocBridgeAttr struct {
	UpstreamPCI                 *HwlocPCIDevAttr
	UpstreamType                HwlocObjBridgeType
	DownStreamPCIDomain         uint
	DownStreamPCISecondaryBus   string
	DownStreamPCISubordinateBus string
	DownStreamType              HwlocObjBridgeType
	Depth                       uint
}

HwlocBridgeAttr specific Object Attribues

type HwlocCPUBindFlag 

type HwlocCPUBindFlag uint8

HwlocCPUBindFlag Process/Thread binding flags.

  • These bit flags can be used to refine the binding policy. *
  • The default (0) is to bind the current process, assumed to be
  • single-threaded, in a non-strict way. This is the most portable
  • way to bind as all operating systems usually provide it. *
  • \note Not all systems support all kinds of binding. See the
  • "Detailed Description" section of \ref hwlocality_cpubinding for a
  • description of errors that can occur.
const (
	// HwlocCPUBindProcess Bind all threads of the current (possibly) multithreaded process.
	HwlocCPUBindProcess HwlocCPUBindFlag = 1 << 0
	// HwlocCPUBindThread Bind current thread of current process.
	HwlocCPUBindThread HwlocCPUBindFlag = 1 << 1
	// HwlocCPUBindStrict Request for strict binding from the OS.
	/* By default, when the designated CPUs are all busy while other
	 * CPUs are idle, operating systems may execute the thread/process
	 * on those other CPUs instead of the designated CPUs, to let them
	 * progress anyway.  Strict binding means that the thread/process
	 * will _never_ execute on other cpus than the designated CPUs, even
	 * when those are busy with other tasks and other CPUs are idle.
	 *
	 * \note Depending on the operating system, strict binding may not
	 * be possible (e.g., the OS does not implement it) or not allowed
	 * (e.g., for an administrative reasons), and the function will fail
	 * in that case.
	 *
	 * When retrieving the binding of a process, this flag checks
	 * whether all its threads  actually have the same binding. If the
	 * flag is not given, the binding of each thread will be
	 * accumulated.
	 *
	 * \note This flag is meaningless when retrieving the binding of a
	 * thread.
	 */
	HwlocCPUBindStrict HwlocCPUBindFlag = 1 << 2

	// HwlocCPUBindNomemBind Avoid any effect on memory binding
	/* On some operating systems, some CPU binding function would also
	 * bind the memory on the corresponding NUMA node.  It is often not
	 * a problem for the application, but if it is, setting this flag
	 * will make hwloc avoid using OS functions that would also bind
	 * memory.  This will however reduce the support of CPU bindings,
	 * i.e. potentially return -1 with errno set to ENOSYS in some
	 * cases.
	 *
	 * This flag is only meaningful when used with functions that set
	 * the CPU binding.  It is ignored when used with functions that get
	 * CPU binding information.
	 * \hideinitializer
	 */
	HwlocCPUBindNomemBind HwlocCPUBindFlag = 1 << 3
)

type HwlocCPUSet 

type HwlocCPUSet struct {
	BitMap
}

HwlocCPUSet A CPU set is a bitmap whose bits are set according to CPU physical OS indexes.

  • It may be consulted and modified with the bitmap API as any
  • ::hwloc_bitmap_t (see hwloc/bitmap.h). *
  • Each bit may be converted into a PU object using
  • hwloc_get_pu_obj_by_os_index().

func NewCPUSet 

func NewCPUSet(cpuset C.hwloc_cpuset_t) *HwlocCPUSet

NewCPUSet create a HwlocCPUSet instance based on hwloc_cpuset_t

func (HwlocCPUSet) Destroy 

func (set HwlocCPUSet) Destroy()

Destroy free the HwlocCPUSet object

type HwlocCacheAttr 

type HwlocCacheAttr struct {
	Size          uint64
	Depth         uint
	LineSize      uint
	Associativity int
	Type          HwlocObjCacheType
}

HwlocCacheAttr Cache-specific Object Attributes

type HwlocGroupAttr 

type HwlocGroupAttr struct {
	// Depth Depth of group object, It may change if intermediate Group objects are added.
	Depth uint
	// Kind Internally-used kind of group.
	Kind uint
	// SubKind Internally-used subkind to distinguish different levels of groups with same kind.
	SubKind uint
}

HwlocGroupAttr Group-specific Object Attribute

type HwlocMemBindFlag 

type HwlocMemBindFlag uint8

HwlocMemBindFlag Memory binding flags.

  • These flags can be used to refine the binding policy.
  • All flags can be logically OR'ed together with the exception of
  • ::HWLOC_MEMBIND_PROCESS and ::HWLOC_MEMBIND_THREAD;
  • these two flags are mutually exclusive. *
  • Not all systems support all kinds of binding.
  • hwloc_topology_get_support() may be used to query about the actual memory
  • binding support in the currently used operating system.
  • See the "Detailed Description" section of \ref hwlocality_membinding
  • for a description of errors that can occur.
const (
	// HwlocMemBindProcess Set policy for all threads of the specified (possibly
	// multithreaded) process.  This flag is mutually exclusive with ::HWLOC_MEMBIND_THREAD.
	HwlocMemBindProcess HwlocMemBindFlag = 1 << 0
	// HwlocMemBindThread Set policy for a specific thread of the current process.
	// This flag is mutually exclusive with ::HWLOC_MEMBIND_PROCESS.
	HwlocMemBindThread HwlocMemBindFlag = 1 << 1
	// HwlocMemBindStrict  Request strict binding from the OS.
	/* The function will fail if the binding can not be guaranteed / completely enforced.
	 *
	 * This flag has slightly different meanings depending on which
	 * function it is used with.
	 */
	HwlocMemBindStrict HwlocMemBindFlag = 1 << 2
	// HwlocMemBindMigrate Migrate existing allocated memory.
	/* If the memory cannot
	 * be migrated and the ::HWLOC_MEMBIND_STRICT flag is passed, an error
	 * will be returned.
	 */
	HwlocMemBindMigrate HwlocMemBindFlag = 1 << 3
	// HwlocMemBindNoCPUBind Avoid any effect on CPU binding.
	/*
	 * On some operating systems, some underlying memory binding
	 * functions also bind the application to the corresponding CPU(s).
	 * Using this flag will cause hwloc to avoid using OS functions that
	 * could potentially affect CPU bindings.  Note, however, that using
	 * NOCPUBIND may reduce hwloc's overall memory binding
	 * support. Specifically: some of hwloc's memory binding functions
	 * may fail with errno set to ENOSYS when used with NOCPUBIND.
	 */
	HwlocMemBindNoCPUBind HwlocMemBindFlag = 1 << 4
	// HwlocMemBindByNodeSet Consider the bitmap argument as a nodeset.
	/*
	 * The bitmap argument is considered a nodeset if this flag is given,
	 * or a cpuset otherwise by default.
	 *
	 * Memory binding by CPU set cannot work for CPU-less NUMA memory nodes.
	 * Binding by nodeset should therefore be preferred whenever possible.
	 */
	HwlocMemBindByNodeSet HwlocMemBindFlag = 1 << 5
)

func (HwlocMemBindFlag) CType 

func (m HwlocMemBindFlag) CType() C.int

type HwlocMemBindPolicy 

type HwlocMemBindPolicy int

HwlocMemBindPolicy Memory binding policy.

  • These constants can be used to choose the binding policy. Only one policy can
  • be used at a time (i.e., the values cannot be OR'ed together). *
  • Not all systems support all kinds of binding.
  • hwloc_topology_get_support() may be used to query about the actual memory
  • binding policy support in the currently used operating system.
  • See the "Detailed Description" section of \ref hwlocality_membinding
  • for a description of errors that can occur.
const (
	// HwlocMemBindDefault Reset the memory allocation policy to the system default.
	/* Depending on the operating system, this may correspond to
	 * ::HWLOC_MEMBIND_FIRSTTOUCH (Linux),
	 * or ::HWLOC_MEMBIND_BIND (AIX, HP-UX, Solaris, Windows).
	 * This policy is never returned by get membind functions.
	 * The nodeset argument is ignored.
	 */
	HwlocMemBindDefault HwlocMemBindPolicy = 0
	// HwlocMemBindFirstTouch Allocate each memory page individually on the local NUMA node of the thread that touches it.
	/*
	 * The given nodeset should usually be hwloc_topology_get_topology_nodeset()
	 * so that the touching thread may run and allocate on any node in the system.
	 *
	 * On AIX, if the nodeset is smaller, pages are allocated locally (if the local
	 * node is in the nodeset) or from a random non-local node (otherwise).
	 */
	HwlocMemBindFirstTouch HwlocMemBindPolicy = 1
	// HwlocMemBindBind Allocate memory on the specified nodes.
	HwlocMemBindBind HwlocMemBindPolicy = 1
	// HwlocMemBindInterleave Allocate memory on the given nodes in an interleaved round-robin manner
	/*The precise layout of the memory across
	 * multiple NUMA nodes is OS/system specific. Interleaving can be
	 * useful when threads distributed across the specified NUMA nodes
	 * will all be accessing the whole memory range concurrently, since
	 * the interleave will then balance the memory references.
	 */
	HwlocMemBindInterleave HwlocMemBindPolicy = 1
	// HwlocMemBindNextTouch For each page bound with this policy, by next time
	// it is touched (and next time only), it is moved from its current
	// location to the local NUMA node of the thread where the memory
	// reference occurred (if it needs to be moved at all).
	HwlocMemBindNextTouch HwlocMemBindPolicy = 1
	// HwlocMemBindMixed Returned by get_membind() functions when multiple
	/* threads or parts of a memory area have differing memory binding
	 * policies.
	 * Also returned when binding is unknown because binding hooks are empty
	 * when the topology is loaded from XML without HWLOC_THISSYSTEM=1, etc.
	 */
	HwlocMemBindMixed HwlocMemBindPolicy = -1
)

func (HwlocMemBindPolicy) CType 

func (m HwlocMemBindPolicy) CType() C.hwloc_membind_policy_t

type HwlocNodeSet 

type HwlocNodeSet struct {
	BitMap
	// contains filtered or unexported fields
}

HwlocNodeSet A node set is a bitmap whose bits are set according to NUMA memory node physical OS indexes.

  • It may be consulted and modified with the bitmap API as any
  • ::hwloc_bitmap_t (see hwloc/bitmap.h).
  • Each bit may be converted into a NUMA node object using
  • hwloc_get_numanode_obj_by_os_index(). *
  • When binding memory on a system without any NUMA node,
  • the single main memory bank is considered as NUMA node #0. *
  • See also \ref hwlocality_helper_nodeset_convert.

type HwlocNumaNodeAttr 

type HwlocNumaNodeAttr struct {
	LocalMemory     uint64
	PageTypesLength uint
}

HwlocNumaNodeAttr NUMA node-specific Object Attributes

type HwlocObjAttr 

type HwlocObjAttr struct {
	NumaNode  *HwlocNumaNodeAttr
	Cache     *HwlocCacheAttr
	Group     *HwlocGroupAttr
	PCIDev    *HwlocPCIDevAttr
	Bridge    *HwlocBridgeAttr
	OSDevType HwlocObjOSDevType
}

HwlocObjAttr Object type-specific Attributes

type HwlocObjBridgeType 

type HwlocObjBridgeType int
const (
	// HwlocObjBridgeHost Host-side of a bridge, only possible upstream.
	HwlocObjBridgeHost HwlocObjBridgeType = iota
	// HwlocObjBridgePCI PCI-side of a bridge.
	HwlocObjBridgePCI
)

type HwlocObjCacheType 

type HwlocObjCacheType int
const (
	// HwlocObjCacheUnified Unified cache.
	HwlocObjCacheUnified HwlocObjCacheType = iota
	// HwlocObjCacheData Data cache.
	HwlocObjCacheData
	// HwlocObjCacheInstruction Instruction cache (filtered out by default).
	HwlocObjCacheInstruction
)

type HwlocObjOSDevType 

type HwlocObjOSDevType int
const (
	// HwlocObjOSDevBlock Operating system block device, or non-volatile memory device.
	// For instance "sda" or "dax2.0" on Linux.
	HwlocObjOSDevBlock HwlocObjOSDevType = iota
	// HwlocObjOSDevGPU Operating system GPU device.
	// For instance ":0.0" for a GL display, "card0" for a Linux DRM device.
	HwlocObjOSDevGPU
	// HwlocObjOSDevNetwork Operating system network device.
	// For instance the "eth0" interface on Linux.
	HwlocObjOSDevNetwork
	// HwlocObjOSDevOpenFabrics Operating system openfabrics device.
	// For instance the "mlx4_0" InfiniBand HCA, or "hfi1_0" Omni-Path interface on Linux.
	HwlocObjOSDevOpenFabrics
	// HwlocObjOSDevDMA Operating system dma engine device.
	// For instance the "dma0chan0" DMA channel on Linux.
	HwlocObjOSDevDMA
	// HwlocObjOSDevCoproc Operating system co-processor device.
	// For instance "mic0" for a Xeon Phi (MIC) on Linux, "opencl0d0" for a OpenCL device, "cuda0" for a CUDA device.
	HwlocObjOSDevCoproc
)

type HwlocObjType 

type HwlocObjType int

HwlocObjType Type of topology object. Do not rely on the ordering or completeness of the values as new ones may be defined in the future! If you need to compare types, use hwloc_compare_types() instead. 

const (
	// HwlocObjMachine Machine.
	// A set of processors and memory with cache coherency.
	// This type is always used for the root object of a topology, and never used anywhere else.
	// Hence its parent is always NULL.
	HwlocObjMachine HwlocObjType = iota

	// HwlocObjPackage Physical package.
	// The physical package that usually gets inserted
	// into a socket on the motherboard.
	// A processor package usually contains multiple cores.
	HwlocObjPackage
	// HwlocObjCore Core
	// A computation unit (may be shared by several logical processors).
	HwlocObjCore
	// HwlocObjPU Processing Unit, or (Logical) Processor.
	// An execution unit (may share a core with some
	// other logical processors, e.g. in the case of an SMT core).
	// This is the smallest object representing CPU resources,
	// it cannot have any child except Misc objects.
	// Objects of this kind are always reported and can
	// thus be used as fallback when others are not.
	HwlocObjPU
	// HwlocObjL1Cache Level 1 Data (or Unified) Cache.
	HwlocObjL1Cache
	// HwlocObjL2Cache Level 2 Data (or Unified) Cache.
	HwlocObjL2Cache
	// HwlocObjL3Cache Level 3 Data (or Unified) Cache.
	HwlocObjL3Cache
	// HwlocObjL4Cache Level 4 Data (or Unified) Cache.
	HwlocObjL4Cache
	// HwlocObjL5Cache Level 5 Data (or Unified) Cache.
	HwlocObjL5Cache

	// HwlocObjL1ICache  Level 1 instruction Cache (filtered out by default).
	HwlocObjL1ICache
	// HwlocObjL2ICache Level 2 instruction Cache (filtered out by default).
	HwlocObjL2ICache
	// HwlocObjL3ICache Level 3 instruction Cache (filtered out by default).
	HwlocObjL3ICache

	// HwlocObjGroup Group objects.
	// Objects which do not fit in the above but are
	// detected by hwloc and are useful to take into
	// account for affinity. For instance, some operating systems
	// expose their arbitrary processors aggregation this
	// way.  And hwloc may insert such objects to group
	// NUMA nodes according to their distances.
	// See also \ref faq_groups.
	// These objects are removed when they do not bring
	// any structure (see ::HWLOC_TYPE_FILTER_KEEP_STRUCTURE).
	HwlocObjGroup

	// HwlocObjNumaNode NUMA node.
	// An object that contains memory that is directly
	// and byte-accessible to the host processors.
	// It is usually close to some cores (the corresponding objects
	// are descendants of the NUMA node object in the hwloc tree).
	// This is the smallest object representing Memory resources,
	// it cannot have any child except Misc objects.
	// However it may have Memory-side cache parents.
	// There is always at least one such object in the topology
	// even if the machine is not NUMA.
	// Memory objects are not listed in the main children list,
	// but rather in the dedicated Memory children list.
	// NUMA nodes have a special depth ::HWLOC_TYPE_DEPTH_NUMANODE
	// instead of a normal depth just like other objects in the main tree.
	HwlocObjNumaNode

	// HwlocObjBridge Bridge (filtered out by default).
	// Any bridge that connects the host or an I/O bus,
	// to another I/O bus.
	// They are not added to the topology unless I/O discovery
	// is enabled with hwloc_topology_set_flags().
	// I/O objects are not listed in the main children list,
	// but rather in the dedicated io children list.
	// I/O objects have NULL CPU and node sets.
	HwlocObjBridge
	// HwlocObjPCIDevice PCI device (filtered out by default).
	// They are not added to the topology unless I/O discovery
	// is enabled with hwloc_topology_set_flags().
	// I/O objects are not listed in the main children list,
	// but rather in the dedicated io children list.
	// I/O objects have NULL CPU and node sets.
	HwlocObjPCIDevice
	// HwlocObjOSDevice Operating system device (filtered out by default).
	// They are not added to the topology unless I/O discovery
	// is enabled with hwloc_topology_set_flags().
	// I/O objects are not listed in the main children list,
	// but rather in the dedicated io children list.
	// I/O objects have NULL CPU and node sets.
	HwlocObjOSDevice

	// HwlocObjMisc Miscellaneous objects (filtered out by default).
	// Objects without particular meaning, that can e.g. be
	// added by the application for its own use, or by hwloc
	// for miscellaneous objects such as MemoryModule (DIMMs).
	// These objects are not listed in the main children list,
	// but rather in the dedicated misc children list.
	// Misc objects may only have Misc objects as children,
	// and those are in the dedicated misc children list as well.
	// Misc objects have NULL CPU and node sets.
	HwlocObjMisc

	// HwlocObjMemCache Memory-side cache (filtered out by default).
	// A cache in front of a specific NUMA node.
	// This object always has at least one NUMA node as a memory child.
	// Memory objects are not listed in the main children list,
	// but rather in the dedicated Memory children list.
	// Memory-side cache have a special depth ::HWLOC_TYPE_DEPTH_MEMCACHE
	// instead of a normal depth just like other objects in the
	// main tree.
	HwlocObjMemCache
)

func (HwlocObjType) String 

func (t HwlocObjType) String() string

String Return a constant stringified object type. This function is the basic way to convert a generic type into a string. The output string may be parsed back by hwloc_type_sscanf().

type HwlocObject 

type HwlocObject struct {
	// HwlocObjType Type of object
	Type HwlocObjType
	// Subtype string to better describe the type field
	SubType string
	// OSIndex OS-provided physical index number.
	// It is not guaranteed unique across the entire machine, except for PUs and NUMA nodes.
	// Set to HWLOC_UNKNOWN_INDEX if unknown or irrelevant for this object.
	OSIndex uint
	// Name Object-specific name if any.
	// Mostly used for identifying OS devices and Misc objects where
	// a name string is more useful than numerical indexes.
	Name string
	// TotalMemory Total memory (in bytes) in NUMA nodes below this object.
	TotalMemory uint64
	// Attributes Object type-specific Attributes, may be NULL if no attribute value was found global position.
	Attributes *HwlocObjAttr
	// Depth Vertical index in the hierarchy.
	// For normal objects, this is the depth of the horizontal level
	// that contains this object and its cousins of the same type.
	// If the topology is symmetric, this is equal to the parent depth
	// plus one, and also equal to the number of parent/child links
	// from the root object to here.
	// For special objects (NUMA nodes, I/O and Misc) that are not
	// in the main tree, this is a special negative value that
	// corresponds to their dedicated level,
	// see hwloc_get_type_depth() and ::hwloc_get_type_depth_e.
	// Those special values can be passed to hwloc functions such
	// hwloc_get_nbobjs_by_depth() as usual.
	Depth int
	// LogicalIndex Horizontal index in the whole list of similar objects,
	// hence guaranteed unique across the entire machine.
	// Could be a "cousin_rank" since it's the rank within the "cousin" list below
	// Note that this index may change when restricting the topology
	// or when inserting a group.
	LogicalIndex uint
	// NextCousin Next object of same type and depth
	NextCousin *HwlocObject
	// PrevCousin Previous object of same type and depth
	PrevCousin  *HwlocObject
	Parent      *HwlocObject
	SiblingRank uint
	NextSibling *HwlocObject
	PrevSibling *HwlocObject
	// Arity Number of normal children.
	// Memory, Misc and I/O children are not listed here
	// but rather in their dedicated children list.
	Arity uint

	Children   []*HwlocObject
	FirstChild *HwlocObject
	LastChild  *HwlocObject
	// Set if the subtree of normal objects below this object is symmetric,
	// which means all normal children and their children have identical subtrees.
	// Memory, I/O and Misc children are ignored.
	// If set in the topology root object, lstopo may export the topology as a synthetic string.
	SymmetricSubTree int

	MemoryArity      uint
	MemoryFirstChild *HwlocObject
	IOArity          uint
	IOFirstChild     *HwlocObject
	MiscArity        uint
	MiscFirstChild   *HwlocObject
	CPUSet           *HwlocCPUSet
	CompleteCPUSet   *HwlocCPUSet
	NodeSet          *HwlocNodeSet
	CompleteNodeSet  *HwlocNodeSet
	// Infos Array of stringified info type=name.
	Infos map[string]string

	// UserData Application-given private data pointer,
	// initialized to \c NULL, use it as you wish.
	UserData []byte
	// contains filtered or unexported fields
}

HwlocObject Structure of a topology object

func NewHwlocObject 

func NewHwlocObject(obj C.hwloc_obj_t) (*HwlocObject, error)

NewHwlocObject create a HwlocObject based on C.hwloc_obj_t

func (*HwlocObject) AddInfo 

func (o *HwlocObject) AddInfo(name, value string) error

AddInfo Add the given info name and value pair to the given object.

  • The info is appended to the existing info array even if another key
  • with the same name already exists. *
  • The input strings are copied before being added in the object infos. *
  • \return \c 0 on success, \c -1 on error. *
  • \note This function may be used to enforce object colors in the lstopo
  • graphical output by using "lstopoStyle" as a name and "Background=#rrggbb"
  • as a value. See CUSTOM COLORS in the lstopo(1) manpage for details. *
  • \note If \p value contains some non-printable characters, they will
  • be dropped when exporting to XML, see hwloc_topology_export_xml() in hwloc/export.h.

func (*HwlocObject) GetInfo 

func (o *HwlocObject) GetInfo(name string) (string, error)

GetInfo Search the given key name in object infos and return the corresponding value.

  • If multiple keys match the given name, only the first one is returned. *
  • \return \c NULL if no such key exists.

type HwlocPCIDevAttr 

type HwlocPCIDevAttr struct {
	Domain      uint16
	Bus         uint8
	Dev         uint8
	Func        uint8
	ClassID     uint16
	VendorID    uint16
	DeviceID    uint16
	SubVendorID uint16
	SubDeviceID uint16
	Revision    uint8
	LinkSpeed   float32 // in GB/s
}

HwlocPCIDevAttr PCI Device specific Object Attributes

type HwlocPid 

type HwlocPid uintptr

type HwlocRestrictFlags 

type HwlocRestrictFlags int

HwlocRestrictFlags Flags to be given to hwloc_topology_restrict(). 

const (
	// HwlocRestrictFlagRemoveCPULess Remove all objects that became CPU-less.
	// By default, only objects that contain no PU and no memory are removed.
	HwlocRestrictFlagRemoveCPULess HwlocRestrictFlags = C.HWLOC_RESTRICT_FLAG_REMOVE_CPULESS
	// HwlocRestrictFlagByNodeSet Restrict by nodeset instead of CPU set.
	// Only keep objects whose nodeset is included or partially included in the given set.
	// This flag may not be used with ::HWLOC_RESTRICT_FLAG_BYNODESET.
	HwlocRestrictFlagByNodeSet HwlocRestrictFlags = C.HWLOC_RESTRICT_FLAG_BYNODESET
	// HwlocRestrictFlagRemoveMemLess Remove all objects that became Memory-less.
	// By default, only objects that contain no PU and no memory are removed.
	// This flag may only be used with ::HWLOC_RESTRICT_FLAG_BYNODESET.
	HwlocRestrictFlagRemoveMemLess HwlocRestrictFlags = C.HWLOC_RESTRICT_FLAG_REMOVE_MEMLESS
	// HwlocRestrictFlagAdaptMisc Move Misc objects to ancestors if their parents are removed during restriction.
	// If this flag is not set, Misc objects are removed when their parents are removed.
	HwlocRestrictFlagAdaptMisc HwlocRestrictFlags = C.HWLOC_RESTRICT_FLAG_ADAPT_MISC
	// HwlocRestrictFlagAdaptIO Move I/O objects to ancestors if their parents are removed during restriction.
	// If this flag is not set, I/O devices and bridges are removed when their parents are removed.
	HwlocRestrictFlagAdaptIO HwlocRestrictFlags = C.HWLOC_RESTRICT_FLAG_ADAPT_IO
)

type HwlocTopologyCPUBindSupport 

type HwlocTopologyCPUBindSupport struct {
	/** Binding the whole current process is supported.  */
	SetThisProcCPUBind uint8
	/** Getting the binding of the whole current process is supported.  */
	GetThisProcCPUBind uint8
	/** Binding a whole given process is supported.  */
	SetProcCPUBind uint8
	/** Getting the binding of a whole given process is supported.  */
	GetProcCPUBind uint8
	/** Binding the current thread only is supported.  */
	SetThisThreadCPUBind uint8
	/** Getting the binding of the current thread only is supported.  */
	GetThisThreadCPUBind uint8
	/** Binding a given thread only is supported.  */
	SetThreadCPUBind uint8
	/** Getting the binding of a given thread only is supported.  */
	GetThreadCPUBind uint8
	/** Getting the last processors where the whole current process ran is supported */
	GetThisProcLastCPULocation uint8
	/** Getting the last processors where a whole process ran is supported */
	GetProcLastCPULocation uint8
	/** Getting the last processors where the current thread ran is supported */
	GetThisThreadLastCPULocation uint8
}

HwlocTopologyCPUBindSupport Flags describing actual PU binding support for this topology. A flag may be set even if the feature isn't supported in all cases (e.g. binding to random sets of non-contiguous objects).

type HwlocTopologyDiscoverySupport 

type HwlocTopologyDiscoverySupport struct {
	// Detecting the number of PU objects is supported.
	PU uint8
	// Detecting the number of NUMA nodes is supported.
	Numa uint8
	// Detecting the amount of memory in NUMA nodes is supported.
	NumaMemory uint8
	// Detecting and identifying PU objects that are not available to the current process is supported.
	DisallowedPU uint8
	// Detecting and identifying NUMA nodes that are not available to the current process is supported.
	DisallowedNuma uint8
}

HwlocTopologyDiscoverySupport Flags describing actual discovery support for this topology.

type HwlocTopologyFlags 

type HwlocTopologyFlags uint64

HwlocTopologyFlags Flags to be set onto a topology context before load.

  • Flags should be given to hwloc_topology_set_flags().
  • They may also be returned by hwloc_topology_get_flags().

type HwlocTopologyMemBindSupport 

type HwlocTopologyMemBindSupport struct {
}

HwlocTopologyMemBindSupport Flags describing actual memory binding support for this topology. A flag may be set even if the feature isn't supported in all cases (e.g. binding to random sets of non-contiguous objects).

type HwlocTopologySupport 

type HwlocTopologySupport struct {
	// contains filtered or unexported fields
}

HwlocTopologySupport Set of flags describing actual support for this topology. This is retrieved with hwloc_topology_get_support() and will be valid until the topology object is destroyed. Note: the values are correct only after discovery.

type HwlocTypeFilter 

type HwlocTypeFilter int

HwlocTypeFilter Type filtering flags. By default, most objects are kept (::HWLOC_TYPE_FILTER_KEEP_ALL). Instruction caches, I/O and Misc objects are ignored by default (::HWLOC_TYPE_FILTER_KEEP_NONE). Group levels are ignored unless they bring structure (::HWLOC_TYPE_FILTER_KEEP_STRUCTURE). Note that group objects are also ignored individually (without the entire level) when they do not bring structure. 

const (
	// HwlocTypeFilterKeepAll Keep all objects of this type.
	// Cannot be set for ::HWLOC_OBJ_GROUP (groups are designed only to add more structure to the topology).
	HwlocTypeFilterKeepAll HwlocTypeFilter = C.HWLOC_TYPE_FILTER_KEEP_ALL
	// HwlocTypeFilterKeepNone gnore all objects of this type.
	// The bottom-level type ::HWLOC_OBJ_PU, the ::HWLOC_OBJ_NUMANODE type, and
	// the top-level type ::HWLOC_OBJ_MACHINE may not be ignored.
	HwlocTypeFilterKeepNone HwlocTypeFilter = C.HWLOC_TYPE_FILTER_KEEP_NONE
	// HwlocTypeFilterKeepStructure nly ignore objects if their entire level does not bring any structure.
	// Keep the entire level of objects if at least one of these objects adds
	// structure to the topology. An object brings structure when it has multiple
	// children and it is not the only child of its parent.
	// If all objects in the level are the only child of their parent, and if none
	// of them has multiple children, the entire level is removed.
	// Cannot be set for I/O and Misc objects since the topology structure does not matter there.
	HwlocTypeFilterKeepStructure HwlocTypeFilter = C.HWLOC_TYPE_FILTER_KEEP_STRUCTURE
	// HwlocTypeFilterKeepImportant Only keep likely-important objects of the given type.
	// It is only useful for I/O object types.
	// For ::HWLOC_OBJ_PCI_DEVICE and ::HWLOC_OBJ_OS_DEVICE, it means that only objects
	// of major/common kinds are kept (storage, network, OpenFabrics, Intel MICs, CUDA,
	// OpenCL, NVML, and displays).
	// Also, only OS devices directly attached on PCI (e.g. no USB) are reported.
	// For ::HWLOC_OBJ_BRIDGE, it means that bridges are kept only if they have children.
	// This flag equivalent to ::HWLOC_TYPE_FILTER_KEEP_ALL for Normal, Memory and Misc types
	// since they are likely important.
	HwlocTypeFilterKeepImportant HwlocTypeFilter = C.HWLOC_TYPE_FILTER_KEEP_IMPORTANT
)

type Topology 

type Topology struct {
	// contains filtered or unexported fields
}

func NewTopology 

func NewTopology() (*Topology, error)

func (*Topology) AllocGroupObject 

func (t *Topology) AllocGroupObject() (*HwlocObject, error)

AllocGroupObject Allocate a Group object to insert later with hwloc_topology_insert_group_object().

  • This function returns a new Group object.
  • The caller should (at least) initialize its sets before inserting the object.
  • See hwloc_topology_insert_group_object(). *
  • The \p subtype object attribute may be set to display something else
  • than "Group" as the type name for this object in lstopo.
  • Custom name/value info pairs may be added with hwloc_obj_add_info() after
  • insertion. *
  • The \p kind group attribute should be 0. The \p subkind group attribute may
  • be set to identify multiple Groups of the same level. *
  • It is recommended not to set any other object attribute before insertion,
  • since the Group may get discarded during insertion. *
  • The object will be destroyed if passed to hwloc_topology_insert_group_object()
  • without any set defined.

func (*Topology) Check 

func (t *Topology) Check() error

Check Run internal checks on a topology structure The program aborts if an inconsistency is detected in the given topology. This routine is only useful to developers. The input topology should have been previously loaded with Load().

func (*Topology) Destroy 

func (t *Topology) Destroy()

func (*Topology) GetCPUBind 

func (t *Topology) GetCPUBind(flags int) (HwlocCPUSet, error)

GetCPUBind Get current process or thread binding.

  • Writes into \p set the physical cpuset which the process or thread (according to \e
  • flags) was last bound to.

func (*Topology) GetDepth 

func (t *Topology) GetDepth() (int, error)

GetDepth Object levels, depths and types * \defgroup hwlocality_levels Object levels, depths and types

  • @{ *
  • Be sure to see the figure in \ref termsanddefs that shows a
  • complete topology tree, including depths, child/sibling/cousin
  • relationships, and an example of an asymmetric topology where one
  • package has fewer caches than its peers. *
  • \brief Get the depth of the hierarchical tree of objects. *
  • This is the depth of ::HWLOC_OBJ_PU objects plus one. *
  • \note NUMA nodes, I/O and Misc objects are ignored when computing
  • the depth of the tree (they are placed on special levels).

func (*Topology) GetDepthType 

func (t *Topology) GetDepthType(depth int) (HwlocObjType, error)

GetDepthType Returns the type of objects at depth depth should between 0 and hwloc_topology_get_depth()-1. return (hwloc_obj_type_t)-1 if depth \p depth does not exist.

func (*Topology) GetFlags 

func (t *Topology) GetFlags() (HwlocTopologyFlags, error)

GetFlags Get OR'ed flags of a topology.

  • Get the OR'ed set of ::hwloc_topology_flags_e of a topology. *
  • \return the flags previously set with hwloc_topology_set_flags().

func (*Topology) GetLastCPULocation 

func (t *Topology) GetLastCPULocation(flags int) (HwlocCPUSet, error)

GetLastCPULocation Get the last physical CPU where the current process or thread ran.

  • The operating system may move some tasks from one processor
  • to another at any time according to their binding,
  • so this function may return something that is already
  • outdated. *
  • flags can include either ::HWLOC_CPUBIND_PROCESS or ::HWLOC_CPUBIND_THREAD to
  • specify whether the query should be for the whole process (union of all CPUs
  • on which all threads are running), or only the current thread. If the
  • process is single-threaded, flags can be set to zero to let hwloc use
  • whichever method is available on the underlying OS.

func (*Topology) GetMemoryParentsDepth 

func (t *Topology) GetMemoryParentsDepth() (int, error)

GetMemoryParentsDepth Return the depth of parents where memory objects are attached.

  • Memory objects have virtual negative depths because they are not part of
  • the main CPU-side hierarchy of objects. This depth should not be compared
  • with other level depths. *
  • If all Memory objects are attached to Normal parents at the same depth,
  • this parent depth may be compared to other as usual, for instance
  • for knowing whether NUMA nodes is attached above or below Packages. *
  • \return The depth of Normal parents of all memory children
  • if all these parents have the same depth. For instance the depth of
  • the Package level if all NUMA nodes are attached to Package objects. *
  • \return ::HWLOC_TYPE_DEPTH_MULTIPLE if Normal parents of all
  • memory children do not have the same depth. For instance if some
  • NUMA nodes are attached to Packages while others are attached to
  • Groups.

func (*Topology) GetNbobjsByDepth 

func (t *Topology) GetNbobjsByDepth(depth int) (uint, error)

GetNbobjsByDepth Returns the width of level at depth.

func (*Topology) GetNbobjsByType 

func (t *Topology) GetNbobjsByType(ht HwlocObjType) (int, error)

GetNbobjsByType Returns the width of level type If no object for that type exists, 0 is returned. If there are several levels with objects of that type, -1 is returned.

func (*Topology) GetObjByDepth 

func (t *Topology) GetObjByDepth(depth int, idx uint) (*HwlocObject, error)

GetObjByDepth Returns the topology object at logical index idx from depth

func (*Topology) GetObjByType 

func (t *Topology) GetObjByType(ht HwlocObjType, idx uint) (*HwlocObject, error)

GetObjByType Returns the topology object at logical index \p idx with type \p type

  • If no object for that type exists, \c NULL is returned.
  • If there are several levels with objects of that type (::HWLOC_OBJ_GROUP),
  • \c NULL is returned and the caller may fallback to hwloc_get_obj_by_depth().

func (*Topology) GetProcCPUBind 

func (t *Topology) GetProcCPUBind(pid HwlocPid, flags int) (HwlocCPUSet, error)

GetProcCPUBind Get the current physical binding of process pid.

  • \note \p hwloc_pid_t is \p pid_t on Unix platforms,
  • and \p HANDLE on native Windows platforms. *
  • \note As a special case on Linux, if a tid (thread ID) is supplied
  • instead of a pid (process ID) and HWLOC_CPUBIND_THREAD is passed in flags,
  • the binding for that specific thread is returned. *
  • \note On non-Linux systems, HWLOC_CPUBIND_THREAD can not be used in \p flags.

func (*Topology) GetProcLastCPULocation 

func (t *Topology) GetProcLastCPULocation(pid HwlocPid, flags int) (HwlocCPUSet, error)

GetProcLastCPULocation Get the last physical CPU where a process ran. 

The operating system may move some tasks from one processor
* to another at any time according to their binding,
* so this function may return something that is already
* outdated.
*
* \note \p hwloc_pid_t is \p pid_t on Unix platforms,
* and \p HANDLE on native Windows platforms.
*
* \note As a special case on Linux, if a tid (thread ID) is supplied
* instead of a pid (process ID) and ::HWLOC_CPUBIND_THREAD is passed in flags,
* the last CPU location of that specific thread is returned.
*
* \note On non-Linux systems, ::HWLOC_CPUBIND_THREAD can not be used in \p flags.

func (*Topology) GetRootObj 

func (t *Topology) GetRootObj() (*HwlocObject, error)

GetRootObj Returns the top-object of the topology-tree. Its type is ::HWLOC_OBJ_MACHINE.

func (*Topology) GetSupport 

func (t *Topology) GetSupport() (*HwlocTopologySupport, error)

GetSupport Retrieve the topology support. Each flag indicates whether a feature is supported. If set to 0, the feature is not supported. If set to 1, the feature is supported, but the corresponding call may still fail in some corner cases. These features are also listed by hwloc-info \--support

func (*Topology) GetTypeDepth 

func (t *Topology) GetTypeDepth(ht HwlocObjType) (int, error)

GetTypeDepth Retruns the depth of objects of type

  • \brief Returns the depth of objects of type \p type. *
  • If no object of this type is present on the underlying architecture, or if
  • the OS doesn't provide this kind of information, the function returns
  • ::HWLOC_TYPE_DEPTH_UNKNOWN. *
  • If type is absent but a similar type is acceptable, see also
  • hwloc_get_type_or_below_depth() and hwloc_get_type_or_above_depth(). *
  • If ::HWLOC_OBJ_GROUP is given, the function may return ::HWLOC_TYPE_DEPTH_MULTIPLE
  • if multiple levels of Groups exist. *
  • If a NUMA node, I/O or Misc object type is given, the function returns a virtual
  • value because these objects are stored in special levels that are not CPU-related.
  • This virtual depth may be passed to other hwloc functions such as
  • hwloc_get_obj_by_depth() but it should not be considered as an actual
  • depth by the application. In particular, it should not be compared with
  • any other object depth or with the entire topology depth.
  • \sa hwloc_get_memory_parents_depth(). *
  • \sa hwloc_type_sscanf_as_depth() for returning the depth of objects
  • whose type is given as a string.

func (*Topology) GetTypeFilter 

func (t *Topology) GetTypeFilter(ot HwlocObjType) (HwlocTypeFilter, error)

GetTypeFilter Get the current filtering for the given object type.

func (*Topology) GetTypeOrAboveDepth 

func (t *Topology) GetTypeOrAboveDepth(ht HwlocObjType) (int, error)

GetTypeOrAboveDepth Returns the depth of objects of type or above

  • If no object of this type is present on the underlying architecture, the
  • function returns the depth of the first "present" object typically
  • containing \p type. *
  • This function is only meaningful for normal object types.
  • If a memory, I/O or Misc object type is given, the corresponding virtual
  • depth is always returned (see hwloc_get_type_depth()). *
  • May return ::HWLOC_TYPE_DEPTH_MULTIPLE for ::HWLOC_OBJ_GROUP just like
  • hwloc_get_type_depth().

func (*Topology) GetTypeOrBelowDepth 

func (t *Topology) GetTypeOrBelowDepth(ht HwlocObjType) (int, error)

GetTypeOrBelowDepth Returns the depth of objects of type or below

  • If no object of this type is present on the underlying architecture, the
  • function returns the depth of the first "present" object typically found
  • inside \p type. *
  • This function is only meaningful for normal object types.
  • If a memory, I/O or Misc object type is given, the corresponding virtual
  • depth is always returned (see hwloc_get_type_depth()). *
  • May return ::HWLOC_TYPE_DEPTH_MULTIPLE for ::HWLOC_OBJ_GROUP just like
  • hwloc_get_type_depth().

func (*Topology) GetUserData 

func (t *Topology) GetUserData() (unsafe.Pointer, error)

GetUserData Retrieve the topology-specific userdata pointer. Retrieve the application-given private data pointer that was previously set with hwloc_topology_set_userdata().

func (*Topology) HwlocGetNUMANodeObjByOSIndex 

func (t *Topology) HwlocGetNUMANodeObjByOSIndex(affinity uint32) *HwlocNodeSet

func (*Topology) HwlocSetMemBind 

func (t *Topology) HwlocSetMemBind(set *HwlocNodeSet, policy HwlocMemBindPolicy, flags HwlocMemBindFlag)

func (*Topology) InsertGroupObject 

func (t *Topology) InsertGroupObject(group *HwlocObject) error

InsertGroupObject Add more structure to the topology by adding an intermediate Group

  • The caller should first allocate a new Group object with hwloc_topology_alloc_group_object().
  • Then it must setup at least one of its CPU or node sets to specify
  • the final location of the Group in the topology.
  • Then the object can be passed to this function for actual insertion in the topology. *
  • Either the cpuset or nodeset field (or both, if compatible) must be set
  • to a non-empty bitmap. The complete_cpuset or complete_nodeset may be set
  • instead if inserting with respect to the complete topology
  • (including disallowed, offline or unknown objects). *
  • It grouping several objects, hwloc_obj_add_other_obj_sets() is an easy way
  • to build the Group sets iteratively. *
  • These sets cannot be larger than the current topology, or they would get
  • restricted silently. *
  • The core will setup the other sets after actual insertion. *
  • \return The inserted object if it was properly inserted. *
  • \return An existing object if the Group was discarded because the topology already
  • contained an object at the same location (the Group did not add any locality information).
  • Any name/info key pair set before inserting is appended to the existing object. *
  • \return \c NULL if the insertion failed because of conflicting sets in topology tree. *
  • \return \c NULL if Group objects are filtered-out of the topology (::HWLOC_TYPE_FILTER_KEEP_NONE). *
  • \return \c NULL if the object was discarded because no set was initialized in the Group
  • before insert, or all of them were empty.

func (*Topology) InsertMiscObject 

func (t *Topology) InsertMiscObject(parent *HwlocObject, name string) error

InsertMiscObject Add a MISC object as a leaf of the topology

  • A new MISC object will be created and inserted into the topology at the
  • position given by parent. It is appended to the list of existing Misc children,
  • without ever adding any intermediate hierarchy level. This is useful for
  • annotating the topology without actually changing the hierarchy. *
  • \p name is supposed to be unique across all Misc objects in the topology.
  • It will be duplicated to setup the new object attributes. *
  • The new leaf object will not have any \p cpuset. *
  • \return the newly-created object *
  • \return \c NULL on error. *
  • \return \c NULL if Misc objects are filtered-out of the topology (::HWLOC_TYPE_FILTER_KEEP_NONE). *
  • \note If \p name contains some non-printable characters, they will
  • be dropped when exporting to XML, see hwloc_topology_export_xml() in hwloc/export.h.

func (*Topology) IsThisSystem 

func (t *Topology) IsThisSystem() (bool, error)

IsThisSystem Does the topology context come from this system?

  • return 1 if this topology context was built using the system
  • running this program.
  • return 0 instead (for instance if using another file-system root,
  • a XML topology file, or a synthetic topology).

func (*Topology) Load 

func (t *Topology) Load() error

func (*Topology) SetAllTypeFilter 

func (t *Topology) SetAllTypeFilter(f HwlocTypeFilter) error

SetAllTypeFilter Set the filtering for all object types. If some types do not support this filtering, they are silently ignored.

func (*Topology) SetAllow 

func (t *Topology) SetAllow(cpuset HwlocCPUSet, nodeset HwlocNodeSet, flags uint32) error

SetAllow Change the sets of allowed PUs and NUMA nodes in the topology. This function only works if the ::HWLOC_TOPOLOGY_FLAG_INCLUDE_DISALLOWED was set on the topology. It does not modify any object, it only changes the sets returned by hwloc_topology_get_allowed_cpuset() and hwloc_topology_get_allowed_nodeset(). It is notably useful when importing a topology from another process running in a different Linux Cgroup. flags must be set to one flag among ::hwloc_allow_flags_e. Removing objects from a topology should rather be performed with hwloc_topology_restrict().

func (*Topology) SetCPUBind 

func (t *Topology) SetCPUBind(set HwlocCPUSet, flags int) error

SetCPUBind Bind current process or thread on cpus given in physical bitmap set.

  • \return -1 with errno set to ENOSYS if the action is not supported
  • \return -1 with errno set to EXDEV if the binding cannot be enforced

func (*Topology) SetCacheTypeFilter 

func (t *Topology) SetCacheTypeFilter(f HwlocTypeFilter) error

SetCacheTypeFilter Set the filtering for all cache object types.

func (*Topology) SetFlags 

func (t *Topology) SetFlags(flags HwlocTopologyFlags) error

SetFlags Set OR'ed flags to non-yet-loaded topology.

  • Set a OR'ed set of ::hwloc_topology_flags_e onto a topology that was not yet loaded. *
  • If this function is called multiple times, the last invokation will erase
  • and replace the set of flags that was previously set. *
  • The flags set in a topology may be retrieved with hwloc_topology_get_flags()

func (*Topology) SetICacheTypeFilter 

func (t *Topology) SetICacheTypeFilter(f HwlocTypeFilter) error

SetICacheTypeFilter Set the filtering for all instruction cache object types.

func (*Topology) SetIOTypeFilter 

func (t *Topology) SetIOTypeFilter(f HwlocTypeFilter) error

SetIOTypeFilter Set the filtering for all I/O object types.

func (*Topology) SetPid 

func (t *Topology) SetPid(pid HwlocPid) error

SetPid Change which process the topology is viewed from.

  • On some systems, processes may have different views of the machine, for
  • instance the set of allowed CPUs. By default, hwloc exposes the view from
  • the current process. Calling hwloc_topology_set_pid() permits to make it
  • expose the topology of the machine from the point of view of another
  • process. *
  • \note \p hwloc_pid_t is \p pid_t on Unix platforms,
  • and \p HANDLE on native Windows platforms. *
  • \note -1 is returned and errno is set to ENOSYS on platforms that do not
  • support this feature.

func (*Topology) SetProcCPUBind 

func (t *Topology) SetProcCPUBind(pid HwlocPid, set HwlocCPUSet, flags int) error

SetProcCPUBind Bind a process pid on cpus given in physical bitmap set. 

\note \p hwloc_pid_t is \p pid_t on Unix platforms,
* and \p HANDLE on native Windows platforms.
*
* \note As a special case on Linux, if a tid (thread ID) is supplied
* instead of a pid (process ID) and ::HWLOC_CPUBIND_THREAD is passed in flags,
* the binding is applied to that specific thread.
*
* \note On non-Linux systems, ::HWLOC_CPUBIND_THREAD can not be used in \p flags.

func (*Topology) SetRestrict 

func (t *Topology) SetRestrict(bitmap BitMap, flags uint32) error

SetRestrict Restrict the topology to the given CPU set or nodeset. Topology \p topology is modified so as to remove all objects that are not included (or partially included) in the CPU set \p set. All objects CPU and node sets are restricted accordingly. If ::HWLOC_RESTRICT_FLAG_BYNODESET is passed in \p flags, set is considered a nodeset instead of a CPU set. flags is a OR'ed set of ::hwloc_restrict_flags_e. This call may not be reverted by restricting back to a larger set. Once dropped during restriction, objects may not be brought back, except by loading another topology with hwloc_topology_load(). return 0 on success. return -1 with errno set to EINVAL if the input set is invalid. The topology is not modified in this case. return -1 with errno set to ENOMEM on failure to allocate internal data. The topology is reinitialized in this case. It should be either destroyed with hwloc_topology_destroy() or configured and loaded again.

func (*Topology) SetSynthetic 

func (t *Topology) SetSynthetic(desc string) error

SetSynthetic Enable synthetic topology.

  • Gather topology information from the given \p description,
  • a space-separated string of <type:number> describing
  • the object type and arity at each level.
  • All types may be omitted (space-separated string of numbers) so that
  • hwloc chooses all types according to usual topologies.
  • See also the \ref synthetic. *
  • Setting the environment variable HWLOC_SYNTHETIC
  • may also result in this behavior. *
  • If \p description was properly parsed and describes a valid topology
  • configuration, this function returns 0.
  • Otherwise -1 is returned and errno is set to EINVAL. *
  • Note that this function does not actually load topology
  • information; it just tells hwloc where to load it from. You'll
  • still need to invoke hwloc_topology_load() to actually load the
  • topology information. *
  • \note For convenience, this backend provides empty binding hooks which just
  • return success. *
  • \note On success, the synthetic component replaces the previously enabled
  • component (if any), but the topology is not actually modified until
  • hwloc_topology_load().

func (*Topology) SetTypeFilter 

func (t *Topology) SetTypeFilter(ot HwlocObjType, f HwlocTypeFilter) error

SetTypeFilter Set the filtering for the given object type.

func (*Topology) SetUserData 

func (t *Topology) SetUserData(data unsafe.Pointer) error

SetUserData Set the topology-specific userdata pointer. Each topology may store one application-given private data pointer. It is initialized to \c NULL. hwloc will never modify it. Use it as you wish, after hwloc_topology_init() and until hwloc_topolog_destroy(). This pointer is not exported to XML.

func (*Topology) SetXMLBuffer 

func (t *Topology) SetXMLBuffer()

SetXMLBuffer Enable XML based topology using a memory buffer (instead of 

a file, as with hwloc_topology_set_xml()).
*
* Gather topology information from the XML memory buffer given at \p
* buffer and of length \p size.  This buffer may have been filled
* earlier with hwloc_topology_export_xmlbuffer() in hwloc/export.h.
*
* Note that this function does not actually load topology
* information; it just tells hwloc where to load it from.  You'll
* still need to invoke hwloc_topology_load() to actually load the
* topology information.
*
* \return -1 with errno set to EINVAL on failure to read the XML buffer.
*
* \note See also hwloc_topology_set_userdata_import_callback()
* for importing application-specific object userdata.
*
* \note For convenience, this backend provides empty binding hooks which just
* return success.  To have hwloc still actually call OS-specific hooks, the
* ::HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM has to be set to assert that the loaded
* file is really the underlying system.
*
* \note On success, the XML component replaces the previously enabled
* component (if any), but the topology is not actually modified until
* hwloc_topology_load().

func (*Topology) SetXMLFile 

func (t *Topology) SetXMLFile(file string) error

SetXMLFile Enable XML-file based topology.

  • Gather topology information from the XML file given at \p xmlpath.
  • Setting the environment variable HWLOC_XMLFILE may also result in this behavior.
  • This file may have been generated earlier with hwloc_topology_export_xml() in hwloc/export.h,
  • or lstopo file.xml. *
  • Note that this function does not actually load topology
  • information; it just tells hwloc where to load it from. You'll
  • still need to invoke hwloc_topology_load() to actually load the
  • topology information. *
  • \return -1 with errno set to EINVAL on failure to read the XML file. *
  • \note See also hwloc_topology_set_userdata_import_callback()
  • for importing application-specific object userdata. *
  • \note For convenience, this backend provides empty binding hooks which just
  • return success. To have hwloc still actually call OS-specific hooks, the
  • ::HWLOC_TOPOLOGY_FLAG_IS_THISSYSTEM has to be set to assert that the loaded
  • file is really the underlying system. *
  • \note On success, the XML component replaces the previously enabled
  • component (if any), but the topology is not actually modified until
  • hwloc_topology_load().

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.