/build/source/nativelink-util/src/platform_properties.rs

Source
// Copyright 2024 The NativeLink Authors. All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//    http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

use std::borrow::Cow;
use std::collections::HashMap;

use nativelink_metric::{
    MetricFieldData, MetricKind, MetricPublishKnownKindData, MetricsComponent, publish,
};
use nativelink_proto::build::bazel::remote::execution::v2::Platform as ProtoPlatform;
use nativelink_proto::build::bazel::remote::execution::v2::platform::Property as ProtoProperty;
use serde::{Deserialize, Serialize};
#[cfg(feature = "worker_find_logging")]
use tracing::info;

/// `PlatformProperties` helps manage the configuration of platform properties to
/// keys and types. The scheduler uses these properties to decide what jobs
/// can be assigned to different workers. For example, if a job states it needs
/// a specific key, it will never be run on a worker that does not have at least
/// all the platform property keys configured on the worker.
///
/// Additional rules may be applied based on `PlatformPropertyValue`.
#[derive(Eq, PartialEq, Clone, Debug, Default, Serialize, Deserialize, MetricsComponent)]
pub struct PlatformProperties {
    #[metric]
    pub properties: HashMap<String, PlatformPropertyValue>,
}

impl PlatformProperties {
    #[must_use]
    pub const fn new(map: HashMap<String, PlatformPropertyValue>) -> Self {
        Self { properties: map }
    }

    /// Determines if the worker's `PlatformProperties` is satisfied by this struct.
    #[must_use]
    pub fn is_satisfied_by(&self, worker_properties: &Self) -> bool {
        for (property9, check_value9) in &self.properties {
            if let Some(worker_value) = worker_properties.properties.get(property) {
                if !check_value.is_satisfied_by(worker_value) {
                    #[cfg(feature = "worker_find_logging")]
                    {
                        info!(
                            "Property mismatch on worker property {property}. {worker_value:?} != {check_value:?}"
                        );
                    }
                    return false;
                }
            } else {
                #[cfg(feature = "worker_find_logging")]
                {
                    info!("Property missing on worker property {property}");
                }
                return false;
            }
        }
        true
    }
}

impl From<ProtoPlatform> for PlatformProperties {
    fn from(platform: ProtoPlatform) -> Self {
        let mut properties = HashMap::with_capacity(platform.properties.len());
        for property in platform.properties {
            properties.insert(
                property.name,
                PlatformPropertyValue::Unknown(property.value),
            );
        }
        Self { properties }
    }
}

impl From<&PlatformProperties> for ProtoPlatform {
    fn from(val: &PlatformProperties) -> Self {
        Self {
            properties: val
                .properties
                .iter()
                .map(|(name, value)| ProtoProperty {
                    name: name.clone(),
                    value: value.as_str().to_string(),
                })
                .collect(),
        }
    }
}

/// Holds the associated value of the key and type.
///
/// Exact    - Means the worker must have this exact value.
/// Minimum  - Means that workers must have at least this number available. When
///            a worker executes a task that has this value, the worker will have
///            this value subtracted from the available resources of the worker.
/// Priority - Means the worker is given this information, but does not restrict
///            what workers can take this value. However, the worker must have the
///            associated key present to be matched.
///            TODO(palfrey) In the future this will be used by the scheduler and
///            worker to cause the scheduler to prefer certain workers over others,
///            but not restrict them based on these values.
#[derive(Eq, PartialEq, Hash, Clone, Ord, PartialOrd, Debug, Serialize, Deserialize)]
pub enum PlatformPropertyValue {
    Exact(String),
    Minimum(u64),
    Priority(String),
    Unknown(String),
}

impl PlatformPropertyValue {
    /// Same as `PlatformProperties::is_satisfied_by`, but on an individual value.
    #[must_use]
    pub fn is_satisfied_by(&self, worker_value: &Self) -> bool {
        if self == worker_value {
            return true;
        }
        match self {
            Self::Minimum(v) => {
                if let Self::Minimum(worker_v) = worker_value {
                    return worker_v >= v;
                }
                false
            }
            // Priority is used to pass info to the worker and not restrict which
            // workers can be selected, but might be used to prefer certain workers
            // over others.
            Self::Priority(_) => true,
            // Success exact case is handled above.
            Self::Exact(_) | Self::Unknown(_) => false,
        }
    }

    pub fn as_str(&self) -> Cow<'_, str> {
        match self {
            Self::Exact(value) | Self::Priority(value0) | Self::Unknown(value0) => {
                Cow::Borrowed(value)
            }
            Self::Minimum(value) => Cow::Owned(value.to_string()),
        }
    }
}

impl MetricsComponent for PlatformPropertyValue {
    fn publish(
        &self,
        kind: MetricKind,
        field_metadata: MetricFieldData,
    ) -> Result<MetricPublishKnownKindData, nativelink_metric::Error> {
        let name = field_metadata.name.into_owned();
        let help = field_metadata.help.as_ref();
        match self {
            Self::Exact(v) => publish!(name, v, kind, help, "exact"),
            Self::Minimum(v) => publish!(name, v, kind, help, "minimum"),
            Self::Priority(v) => publish!(name, v, kind, help, "priority"),
            Self::Unknown(v) => publish!(name, v, kind, help, "unknown"),
        }

        Ok(MetricPublishKnownKindData::Component)
    }
}

Line	Count	Source
1		// Copyright 2024 The NativeLink Authors. All rights reserved.
2		//
3		// Licensed under the Apache License, Version 2.0 (the "License");
4		// you may not use this file except in compliance with the License.
5		// You may obtain a copy of the License at
6		//
7		// http://www.apache.org/licenses/LICENSE-2.0
8		//
9		// Unless required by applicable law or agreed to in writing, software
10		// distributed under the License is distributed on an "AS IS" BASIS,
11		// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12		// See the License for the specific language governing permissions and
13		// limitations under the License.
14
15		use std::borrow::Cow;
16		use std::collections::HashMap;
17
18		use nativelink_metric::{
19		MetricFieldData, MetricKind, MetricPublishKnownKindData, MetricsComponent, publish,
20		};
21		use nativelink_proto::build::bazel::remote::execution::v2::Platform as ProtoPlatform;
22		use nativelink_proto::build::bazel::remote::execution::v2::platform::Property as ProtoProperty;
23		use serde::{Deserialize, Serialize};
24		#[cfg(feature = "worker_find_logging")]
25		use tracing::info;
26
27		/// `PlatformProperties` helps manage the configuration of platform properties to
28		/// keys and types. The scheduler uses these properties to decide what jobs
29		/// can be assigned to different workers. For example, if a job states it needs
30		/// a specific key, it will never be run on a worker that does not have at least
31		/// all the platform property keys configured on the worker.
32		///
33		/// Additional rules may be applied based on `PlatformPropertyValue`.
34		#[derive(Eq, PartialEq, Clone, Debug, Default, Serialize, Deserialize, MetricsComponent)]
35		pub struct PlatformProperties {
36		#[metric]
37		pub properties: HashMap<String, PlatformPropertyValue>,
38		}
39
40		impl PlatformProperties {
41		#[must_use]
42	51	pub const fn new(map: HashMap<String, PlatformPropertyValue>) -> Self {
43	51	Self { properties: map }
44	51	}
45
46		/// Determines if the worker's `PlatformProperties` is satisfied by this struct.
47		#[must_use]
48	37	pub fn is_satisfied_by(&self, worker_properties: &Self) -> bool {
49	41	for ( property9 , check_value9 ) in &self.properties {
50	9	if let Some(worker_value) = worker_properties.properties.get(property) { Branch (50:20): [True: 9, False: 0] Branch (50:20): [Folded - Ignored]
51	9	if !check_value.is_satisfied_by(worker_value) { Branch (51:20): [True: 5, False: 4] Branch (51:20): [Folded - Ignored]
52		#[cfg(feature = "worker_find_logging")]
53		{
54		info!(
55		"Property mismatch on worker property {property}. {worker_value:?} != {check_value:?}"
56		);
57		}
58	5	return false;
59	4	}
60		} else {
61		#[cfg(feature = "worker_find_logging")]
62		{
63		info!("Property missing on worker property {property}");
64		}
65	0	return false;
66		}
67		}
68	32	true
69	37	}
70		}
71
72		impl From<ProtoPlatform> for PlatformProperties {
73	0	fn from(platform: ProtoPlatform) -> Self {
74	0	let mut properties = HashMap::with_capacity(platform.properties.len());
75	0	for property in platform.properties {
76	0	properties.insert(
77	0	property.name,
78	0	PlatformPropertyValue::Unknown(property.value),
79	0	);
80	0	}
81	0	Self { properties }
82	0	}
83		}
84
85		impl From<&PlatformProperties> for ProtoPlatform {
86	33	fn from(val: &PlatformProperties) -> Self {
87		Self {
88	33	properties: val
89	33	.properties
90	33	.iter()
91	33	.map(\|(name, value)\| ProtoProperty {
92	5	name: name.clone(),
93	5	value: value.as_str().to_string(),
94	5	})
95	33	.collect(),
96		}
97	33	}
98		}
99
100		/// Holds the associated value of the key and type.
101		///
102		/// Exact - Means the worker must have this exact value.
103		/// Minimum - Means that workers must have at least this number available. When
104		/// a worker executes a task that has this value, the worker will have
105		/// this value subtracted from the available resources of the worker.
106		/// Priority - Means the worker is given this information, but does not restrict
107		/// what workers can take this value. However, the worker must have the
108		/// associated key present to be matched.
109		/// TODO(palfrey) In the future this will be used by the scheduler and
110		/// worker to cause the scheduler to prefer certain workers over others,
111		/// but not restrict them based on these values.
112		#[derive(Eq, PartialEq, Hash, Clone, Ord, PartialOrd, Debug, Serialize, Deserialize)]
113		pub enum PlatformPropertyValue {
114		Exact(String),
115		Minimum(u64),
116		Priority(String),
117		Unknown(String),
118		}
119
120		impl PlatformPropertyValue {
121		/// Same as `PlatformProperties::is_satisfied_by`, but on an individual value.
122		#[must_use]
123	9	pub fn is_satisfied_by(&self, worker_value: &Self) -> bool {
124	9	if self == worker_value { Branch (124:12): [True: 4, False: 5] Branch (124:12): [Folded - Ignored]
125	4	return true;
126	5	}
127	5	match self {
128	3	Self::Minimum(v) => {
129	3	if let Self::Minimum(worker_v) = worker_value { Branch (129:24): [True: 3, False: 0] Branch (129:24): [Folded - Ignored]
130	3	return worker_v >= v;
131	0	}
132	0	false
133		}
134		// Priority is used to pass info to the worker and not restrict which
135		// workers can be selected, but might be used to prefer certain workers
136		// over others.
137	0	Self::Priority(_) => true,
138		// Success exact case is handled above.
139	2	Self::Exact(_) \| Self::Unknown(_) => false,
140		}
141	9	}
142
143	7	pub fn as_str(&self) -> Cow<'_, str> {
144	7	match self {
145	2	Self::Exact(value) \| Self::Priority( value0 ) \| Self::Unknown( value0 ) => {
146	2	Cow::Borrowed(value)
147		}
148	5	Self::Minimum(value) => Cow::Owned(value.to_string()),
149		}
150	7	}
151		}
152
153		impl MetricsComponent for PlatformPropertyValue {
154	0	fn publish(
155	0	&self,
156	0	kind: MetricKind,
157	0	field_metadata: MetricFieldData,
158	0	) -> Result<MetricPublishKnownKindData, nativelink_metric::Error> {
159	0	let name = field_metadata.name.into_owned();
160	0	let help = field_metadata.help.as_ref();
161	0	match self {
162	0	Self::Exact(v) => publish!(name, v, kind, help, "exact"),
163	0	Self::Minimum(v) => publish!(name, v, kind, help, "minimum"),
164	0	Self::Priority(v) => publish!(name, v, kind, help, "priority"),
165	0	Self::Unknown(v) => publish!(name, v, kind, help, "unknown"),
166		}
167
168	0	Ok(MetricPublishKnownKindData::Component)
169	0	}
170		}

Coverage Report

Created: 2025-09-16 19:42