Struct hwlocality::topology::builder::BuildFlags
source · pub struct BuildFlags(/* private fields */);
Expand description
Topology building configuration flags
Implementations§
source§impl BuildFlags
impl BuildFlags
sourcepub const INCLUDE_DISALLOWED: Self = _
pub const INCLUDE_DISALLOWED: Self = _
Detect the whole system, ignore reservations, include disallowed objects
Gather all online resources, even if some were disabled by the administrator. For instance, ignore Linux Cgroup/Cpusets and gather all processors and memory nodes. However offline PUs and NUMA nodes are still ignored.
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.
Topology::allowed_cpuset()
and Topology::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 Topology::allowed_cpuset()
and
Topology::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.
What additional objects could be detected with this flag depends on
DiscoverySupport::disallowed_pu()
and
DiscoverySupport::disallowed_numa()
, which can be checked after
building the topology.
sourcepub const ASSUME_THIS_SYSTEM: Self = _
pub const ASSUME_THIS_SYSTEM: Self = _
Assume that the selected backend provides the topology for the system on which we are running
This forces Topology::is_this_system()
to return true, 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.
sourcepub const GET_ALLOWED_RESOURCES_FROM_THIS_SYSTEM: Self = _
pub const GET_ALLOWED_RESOURCES_FROM_THIS_SYSTEM: Self = _
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.
If this flag is set, ASSUME_THIS_SYSTEM
must also be 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.
sourcepub const IMPORT_SUPPORT: Self = _
Available on crate feature hwloc-2_3_0
only.
pub const IMPORT_SUPPORT: Self = _
hwloc-2_3_0
only.Import support from the imported topology
When importing a XML topology from a remote machine, binding is
disabled by default (see ASSUME_THIS_SYSTEM
). This disabling is
also marked by putting zeroes in the corresponding supported feature
bits reported by Topology::feature_support()
.
This flag allows you to actually import support bits from the remote
machine. It also sets the MiscSupport::imported()
support flag.
If the imported XML did not contain any support information
(exporter hwloc is too old), this flag is not set.
Note that these supported features are only relevant for the hwloc installation that actually exported the XML topology (it may vary with the operating system, or with how hwloc was compiled).
Note that setting this flag however does not enable binding for the locally imported hwloc topology, it only reports what the remote hwloc and machine support.
sourcepub const RESTRICT_CPU_TO_THIS_PROCESS: Self = _
Available on crate feature hwloc-2_5_0
only.
pub const RESTRICT_CPU_TO_THIS_PROCESS: Self = _
hwloc-2_5_0
only.Do not consider resources outside of the process CPU binding
If the binding of the process is limited to a subset of cores, ignore the other cores during discovery.
The resulting topology is identical to what a call to
TopologyEditor::restrict()
would generate, but this flag also
prevents hwloc from ever touching other resources during the
discovery.
This flag especially tells the x86 backend to never temporarily rebind a thread on any excluded core. This is useful on Windows because such temporary rebinding can change the process binding. Another use-case is to avoid cores that would not be able to perform the hwloc discovery anytime soon because they are busy executing some high-priority real-time tasks.
If process CPU binding is not supported, the thread CPU binding is considered instead if supported, or the flag is ignored.
This flag requires ASSUME_THIS_SYSTEM
as well since binding support
is required.
sourcepub const RESTRICT_MEMORY_TO_THIS_PROCESS: Self = _
Available on crate feature hwloc-2_5_0
only.
pub const RESTRICT_MEMORY_TO_THIS_PROCESS: Self = _
hwloc-2_5_0
only.Do not consider resources outside of the process memory binding
If the binding of the process is limited to a subset of NUMA nodes, ignore the other NUMA nodes during discovery.
The resulting topology is identical to what a call to
TopologyEditor::restrict()
would generate, but this flag also
prevents hwloc from ever touching other resources during the
discovery.
This flag is meant to be used together with
RESTRICT_CPU_TO_THIS_PROCESS
when both cores and NUMA nodes should
be ignored outside of the process binding.
If process memory binding is not supported, the thread memory binding is considered instead if supported, or the flag is ignored.
This flag requires ASSUME_THIS_SYSTEM
as well since binding
support is required.
sourcepub const DONT_CHANGE_BINDING: Self = _
Available on crate feature hwloc-2_5_0
only.
pub const DONT_CHANGE_BINDING: Self = _
hwloc-2_5_0
only.Do not ever modify the process or thread binding during discovery
This flag disables all hwloc discovery steps that require a change of the process or thread binding. This currently only affects the x86 backend which gets entirely disabled.
This is useful when a Topology
is loaded while the application
also creates additional threads or modifies the binding.
This flag is also a strict way to make sure the process binding will
not change to due thread binding changes on Windows (see
RESTRICT_CPU_TO_THIS_PROCESS
).
sourcepub const IGNORE_DISTANCES: Self = _
Available on crate feature hwloc-2_8_0
only.
pub const IGNORE_DISTANCES: Self = _
hwloc-2_8_0
only.Ignore distance information from the operating system (and from XML)
Distances will not be used for grouping TopologyObject
s.
sourcepub const IGNORE_MEMORY_ATTRIBUTES: Self = _
Available on crate feature hwloc-2_8_0
only.
pub const IGNORE_MEMORY_ATTRIBUTES: Self = _
hwloc-2_8_0
only.Ignore memory attribues from the operating system (and from XML)
sourcepub const IGNORE_CPU_KINDS: Self = _
Available on crate feature hwloc-2_8_0
only.
pub const IGNORE_CPU_KINDS: Self = _
hwloc-2_8_0
only.Ignore CPU kind information from the operating system (and from XML)
source§impl BuildFlags
impl BuildFlags
sourcepub const fn bits(&self) -> hwloc_topology_flags_e
pub const fn bits(&self) -> hwloc_topology_flags_e
Get the underlying bits value.
The returned value is exactly the bits set in this flags value.
sourcepub const fn from_bits(bits: hwloc_topology_flags_e) -> Option<Self>
pub const fn from_bits(bits: hwloc_topology_flags_e) -> Option<Self>
Convert from a bits value.
This method will return None
if any unknown bits are set.
sourcepub const fn from_bits_truncate(bits: hwloc_topology_flags_e) -> Self
pub const fn from_bits_truncate(bits: hwloc_topology_flags_e) -> Self
Convert from a bits value, unsetting any unknown bits.
sourcepub const fn from_bits_retain(bits: hwloc_topology_flags_e) -> Self
pub const fn from_bits_retain(bits: hwloc_topology_flags_e) -> Self
Convert from a bits value exactly.
sourcepub fn from_name(name: &str) -> Option<Self>
pub fn from_name(name: &str) -> Option<Self>
Get a flags value with the bits of a flag with the given name set.
This method will return None
if name
is empty or doesn’t
correspond to any named flag.
sourcepub const fn intersects(&self, other: Self) -> bool
pub const fn intersects(&self, other: Self) -> bool
Whether any set bits in a source flags value are also set in a target flags value.
sourcepub const fn contains(&self, other: Self) -> bool
pub const fn contains(&self, other: Self) -> bool
Whether all set bits in a source flags value are also set in a target flags value.
sourcepub fn remove(&mut self, other: Self)
pub fn remove(&mut self, other: Self)
The intersection of a source flags value with the complement of a target flags value (&!
).
This method is not equivalent to self & !other
when other
has unknown bits set.
remove
won’t truncate other
, but the !
operator will.
sourcepub fn toggle(&mut self, other: Self)
pub fn toggle(&mut self, other: Self)
The bitwise exclusive-or (^
) of the bits in two flags values.
sourcepub fn set(&mut self, other: Self, value: bool)
pub fn set(&mut self, other: Self, value: bool)
Call insert
when value
is true
or remove
when value
is false
.
sourcepub const fn intersection(self, other: Self) -> Self
pub const fn intersection(self, other: Self) -> Self
The bitwise and (&
) of the bits in two flags values.
sourcepub const fn union(self, other: Self) -> Self
pub const fn union(self, other: Self) -> Self
The bitwise or (|
) of the bits in two flags values.
sourcepub const fn difference(self, other: Self) -> Self
pub const fn difference(self, other: Self) -> Self
The intersection of a source flags value with the complement of a target flags value (&!
).
This method is not equivalent to self & !other
when other
has unknown bits set.
difference
won’t truncate other
, but the !
operator will.
sourcepub const fn symmetric_difference(self, other: Self) -> Self
pub const fn symmetric_difference(self, other: Self) -> Self
The bitwise exclusive-or (^
) of the bits in two flags values.
sourcepub const fn complement(self) -> Self
pub const fn complement(self) -> Self
The bitwise negation (!
) of the bits in a flags value, truncating the result.
source§impl BuildFlags
impl BuildFlags
sourcepub const fn iter(&self) -> Iter<BuildFlags>
pub const fn iter(&self) -> Iter<BuildFlags>
Yield a set of contained flags values.
Each yielded flags value will correspond to a defined named flag. Any unknown bits will be yielded together as a final flags value.
sourcepub const fn iter_names(&self) -> IterNames<BuildFlags>
pub const fn iter_names(&self) -> IterNames<BuildFlags>
Yield a set of contained named flags values.
This method is like iter
, except only yields bits in contained named flags.
Any unknown bits, or bits not corresponding to a contained flag will not be yielded.
Trait Implementations§
source§impl Arbitrary for BuildFlags
Available on crate feature proptest
only.
impl Arbitrary for BuildFlags
proptest
only.§type Parameters = ()
type Parameters = ()
arbitrary_with
accepts for configuration
of the generated Strategy
. Parameters must implement Default
.§type Strategy = Map<Subsequence<BuildFlags>, fn(_: Vec<BuildFlags>) -> BuildFlags>
type Strategy = Map<Subsequence<BuildFlags>, fn(_: Vec<BuildFlags>) -> BuildFlags>
Strategy
used to generate values of type Self
.source§fn arbitrary_with(_args: Self::Parameters) -> Self::Strategy
fn arbitrary_with(_args: Self::Parameters) -> Self::Strategy
source§impl Binary for BuildFlags
impl Binary for BuildFlags
source§impl BitAnd for BuildFlags
impl BitAnd for BuildFlags
source§impl BitAndAssign for BuildFlags
impl BitAndAssign for BuildFlags
source§fn bitand_assign(&mut self, other: Self)
fn bitand_assign(&mut self, other: Self)
The bitwise and (&
) of the bits in two flags values.
source§impl BitOr for BuildFlags
impl BitOr for BuildFlags
source§fn bitor(self, other: BuildFlags) -> Self
fn bitor(self, other: BuildFlags) -> Self
The bitwise or (|
) of the bits in two flags values.
§type Output = BuildFlags
type Output = BuildFlags
|
operator.source§impl BitOrAssign for BuildFlags
impl BitOrAssign for BuildFlags
source§fn bitor_assign(&mut self, other: Self)
fn bitor_assign(&mut self, other: Self)
The bitwise or (|
) of the bits in two flags values.
source§impl BitXor for BuildFlags
impl BitXor for BuildFlags
source§impl BitXorAssign for BuildFlags
impl BitXorAssign for BuildFlags
source§fn bitxor_assign(&mut self, other: Self)
fn bitxor_assign(&mut self, other: Self)
The bitwise exclusive-or (^
) of the bits in two flags values.
source§impl Clone for BuildFlags
impl Clone for BuildFlags
source§fn clone(&self) -> BuildFlags
fn clone(&self) -> BuildFlags
1.0.0 · source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read moresource§impl Debug for BuildFlags
impl Debug for BuildFlags
source§impl Default for BuildFlags
impl Default for BuildFlags
source§fn default() -> BuildFlags
fn default() -> BuildFlags
source§impl Extend<BuildFlags> for BuildFlags
impl Extend<BuildFlags> for BuildFlags
source§fn extend<T: IntoIterator<Item = Self>>(&mut self, iterator: T)
fn extend<T: IntoIterator<Item = Self>>(&mut self, iterator: T)
The bitwise or (|
) of the bits in each flags value.
source§fn extend_one(&mut self, item: A)
fn extend_one(&mut self, item: A)
extend_one
)source§fn extend_reserve(&mut self, additional: usize)
fn extend_reserve(&mut self, additional: usize)
extend_one
)source§impl Flags for BuildFlags
impl Flags for BuildFlags
source§const FLAGS: &'static [Flag<BuildFlags>] = _
const FLAGS: &'static [Flag<BuildFlags>] = _
source§fn bits(&self) -> hwloc_topology_flags_e
fn bits(&self) -> hwloc_topology_flags_e
source§fn from_bits_retain(bits: hwloc_topology_flags_e) -> BuildFlags
fn from_bits_retain(bits: hwloc_topology_flags_e) -> BuildFlags
source§fn from_bits_truncate(bits: Self::Bits) -> Self
fn from_bits_truncate(bits: Self::Bits) -> Self
source§fn from_name(name: &str) -> Option<Self>
fn from_name(name: &str) -> Option<Self>
source§fn iter_names(&self) -> IterNames<Self>
fn iter_names(&self) -> IterNames<Self>
source§fn intersects(&self, other: Self) -> boolwhere
Self: Sized,
fn intersects(&self, other: Self) -> boolwhere
Self: Sized,
source§fn contains(&self, other: Self) -> boolwhere
Self: Sized,
fn contains(&self, other: Self) -> boolwhere
Self: Sized,
source§fn insert(&mut self, other: Self)where
Self: Sized,
fn insert(&mut self, other: Self)where
Self: Sized,
|
) of the bits in two flags values.source§fn remove(&mut self, other: Self)where
Self: Sized,
fn remove(&mut self, other: Self)where
Self: Sized,
&!
). Read moresource§fn toggle(&mut self, other: Self)where
Self: Sized,
fn toggle(&mut self, other: Self)where
Self: Sized,
^
) of the bits in two flags values.source§fn intersection(self, other: Self) -> Self
fn intersection(self, other: Self) -> Self
&
) of the bits in two flags values.source§fn difference(self, other: Self) -> Self
fn difference(self, other: Self) -> Self
&!
). Read moresource§fn symmetric_difference(self, other: Self) -> Self
fn symmetric_difference(self, other: Self) -> Self
^
) of the bits in two flags values.source§fn complement(self) -> Self
fn complement(self) -> Self
!
) of the bits in a flags value, truncating the result.source§impl FromIterator<BuildFlags> for BuildFlags
impl FromIterator<BuildFlags> for BuildFlags
source§fn from_iter<T: IntoIterator<Item = Self>>(iterator: T) -> Self
fn from_iter<T: IntoIterator<Item = Self>>(iterator: T) -> Self
The bitwise or (|
) of the bits in each flags value.
source§impl Hash for BuildFlags
impl Hash for BuildFlags
source§impl IntoIterator for BuildFlags
impl IntoIterator for BuildFlags
source§impl LowerHex for BuildFlags
impl LowerHex for BuildFlags
source§impl Not for BuildFlags
impl Not for BuildFlags
source§impl Octal for BuildFlags
impl Octal for BuildFlags
source§impl PartialEq for BuildFlags
impl PartialEq for BuildFlags
source§fn eq(&self, other: &BuildFlags) -> bool
fn eq(&self, other: &BuildFlags) -> bool
self
and other
values to be equal, and is used
by ==
.source§impl PublicFlags for BuildFlags
impl PublicFlags for BuildFlags
source§impl Sub for BuildFlags
impl Sub for BuildFlags
source§fn sub(self, other: Self) -> Self
fn sub(self, other: Self) -> Self
The intersection of a source flags value with the complement of a target flags value (&!
).
This method is not equivalent to self & !other
when other
has unknown bits set.
difference
won’t truncate other
, but the !
operator will.
§type Output = BuildFlags
type Output = BuildFlags
-
operator.source§impl SubAssign for BuildFlags
impl SubAssign for BuildFlags
source§fn sub_assign(&mut self, other: Self)
fn sub_assign(&mut self, other: Self)
The intersection of a source flags value with the complement of a target flags value (&!
).
This method is not equivalent to self & !other
when other
has unknown bits set.
difference
won’t truncate other
, but the !
operator will.