Rust::com Field and Method Rust Design and Example of APIs usage

score/mw/com/example/com-api-example/BUILD

@@ -25,6 +25,7 @@ rust_library(
         "@score_baselibs//src/log/score_log",
         "@score_communication_crate_index//:clap",
         "@score_communication_crate_index//:futures",
+        "@score_communication_crate_index//:tokio",
     ],
 )
 

score/mw/com/example/com-api-example/com-api-gen/com_api_gen.rs

@@ -11,7 +11,7 @@
  * SPDX-License-Identifier: Apache-2.0
  ********************************************************************************/
 
-use score_com::{interface, CommData, ProviderInfo, Publisher, Reloc, Subscriber};
+use score_com::{interface, CommData, FieldPublisher, ProviderInfo, Publisher, Reloc, Subscriber};
 use score_log::ScoreDebug;
 
 #[derive(Debug, Reloc, CommData, ScoreDebug)]
@@ -47,3 +47,52 @@ interface!(
         exhaust: Event<Exhaust>,
      }
 );
+
+// Example interface definition using the interface macro with a custom UID for the interface.
+// This will generate the following types and trait implementations:
+// - VehicleMethodsInterface struct with INTERFACE_ID = "VehicleMethodsInterface"
+// - VehicleMethodsConsumer<R>, VehicleMethodsProducer<R>, VehicleMethodsOfferedProducer<R>
+//   with appropriate trait implementations for the VehicleMethods interface.
+// As passed methods to macro it will generate the following methods:
+// - update_tire_pressure(Tire) -> ()
+// - update_front_tires_pressure(Tire, Tire) -> ()
+// - get_tire_pressure() -> Tire
+// and this method can be accessed through the consumer instance of VehicleMethodsConsumer<R>.
+// Methods use fn-like syntax:
+// method_name(ArgType0, ArgType1, ...) -> score_com::Result<R::MethodReturnSample<ReturnType>>.
+// For void return, -> () is required so the macro can identify the member as a method.
+interface!(
+    interface VehicleMethods {
+        Id = "VehicleMethodsInterface",
+        update_tire_pressure(Tire) -> (),
+        update_front_tires_pressure(Tire, Tire) -> (),
+        get_tire_pressure() -> Tire,
+    }
+);
+
+// Field-based interface with compile-time initialization safety.
+// All fields must be explicitly initialized via the Type State pattern before offering.
+// The Type State pattern ensures that you cannot call offer() until all fields have been updated.
+// This separate field-only interface is intentionally kept for demonstration purposes.
+// Mixed event and field interfaces are already supported, as shown by VehicleMonitor below.
+interface!(
+    interface VehicleField {
+        Id = "VehicleFieldInterface",
+        left_tire: Field<Tire, WithGetter + WithSetter + WithNotifier>,
+        exhaust: Field<Exhaust, WithGetter + WithSetter + WithNotifier>,
+     }
+);
+
+// We can also define mix of event , field and method in one interface.
+interface!(
+    interface VehicleMonitor {
+        Id = "VehicleMonitorInterface",
+        left_tire: Event<Tire>,
+        exhaust: Event<Exhaust>,
+        left_tire_field: Field<Tire, WithGetter + WithSetter + WithNotifier>,
+        exhaust_field: Field<Exhaust, WithGetter + WithSetter + WithNotifier>,
+        update_tire_pressure(Tire) -> (),
+        update_front_tires_pressure(Tire, Tire) -> (),
+        get_tire_pressure() -> Tire,
+    }
+);

score/mw/com/example/com-api-example/src/field_consumer.rs

@@ -0,0 +1,101 @@
+/********************************************************************************
+ * Copyright (c) 2025 Contributors to the Eclipse Foundation
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Apache License Version 2.0 which is available at
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ ********************************************************************************/
+
+// This file demonstrate the usage of consumer field APIs, which are generated for the VehicleFieldInterface.
+
+// Notes: we are creating consumer instance specific for field here but this is just for demonstration purpose,
+// for same consumer instance method / event/ field can be subscribed as per subscribe interface.
+
+// All the functions and types in this file are just for demonstration purpose,
+// as this are not part of any callable because of that unused warning is suppressed for this file.
+
+use score_com::{
+    Builder, FindServiceSpecifier, InstanceSpecifier, Interface, Runtime, SampleContainer,
+    ServiceDiscovery, Subscriber, Subscription,
+};
+
+use com_api_gen::{Tire, VehicleFieldInterface};
+
+#[allow(dead_code)]
+type VehicleFieldConsumer<R> = <VehicleFieldInterface as Interface>::Consumer<R>;
+
+// create the consumer.
+#[allow(dead_code)]
+fn create_consumer_field<R: Runtime>(
+    runtime: &R,
+    service_id: InstanceSpecifier,
+) -> VehicleFieldConsumer<R> {
+    let consumer_discovery =
+        runtime.find_service::<VehicleFieldInterface>(FindServiceSpecifier::Specific(service_id));
+    let available_service_instances = consumer_discovery
+        .get_available_instances()
+        .expect("Failed to get available service instances");
+
+    // Select service instance at specific handle_index
+    let handle_index = 0; // or any index you need from vector of instances
+    let consumer_builder = available_service_instances
+        .into_iter()
+        .nth(handle_index)
+        .expect("Failed to get consumer builder at specified handle index");
+
+    consumer_builder
+        .build()
+        .expect("Failed to build consumer instance")
+}
+
+// Function to demonstrate the usage of the consumer to get and set fields,
+// and subscribe to field update notifications.
+//
+// Field get/set are now fully async via the MethodCaller-based wrappers generated by the
+// interface! macro. They live on the consumer struct as separate fields (`{name}_get`,
+// `{name}_set`) and are independent of subscribe() - they remain usable before and after.
+//
+// Because subscribe() takes `left_tire` by value, extract the callers before subscribing
+// if both are needed in the same async context.
+#[allow(dead_code)]
+async fn consumer_processing_field<R: Runtime>(consumer: VehicleFieldConsumer<R>) {
+    // Async get via the generated get_left_tire() wrapper.
+    // Uses MethodCaller<(), Tire> under the hood - reuses Method infrastructure.
+    match consumer.get_left_tire().await {
+        Ok(result) => println!("Current tire pressure (async get): {:?}", *result),
+        Err(e) => eprintln!("Failed to get tire pressure: {:?}", e),
+    }
+
+    // Async set via the generated set_left_tire(val) wrapper.
+    // Uses MethodCaller<(Tire,), Tire> under the hood - reuses Method infrastructure.
+    match consumer.set_left_tire(Tire { pressure: 35.0 }).await {
+        Ok(result) => println!("Confirmed tire pressure after set: {:?}", *result),
+        Err(e) => eprintln!("Failed to set tire pressure: {:?}", e),
+    }
+
+    // Subscribe to the field to receive update notifications (field value changes).
+    // Note: subscribe() takes `left_tire` by value. The get/set callers are separate
+    // struct fields so they are not consumed here, but the consumer is partially moved.
+    let subscription = consumer
+        .left_tire
+        .subscribe(3)
+        .expect("Failed to subscribe to field");
+
+    // Poll for updates (non-blocking)
+    let mut sample_buf = SampleContainer::new(3);
+    match subscription.try_receive(&mut sample_buf, 1) {
+        Ok(n) if n > 0 => {
+            while let Some(sample) = sample_buf.pop_front() {
+                println!("Updated tire pressure: {:?}", *sample);
+            }
+        }
+        _ => println!("No new tire pressure updates available"),
+    }
+
+    // subscription is automatically unsubscribed when dropped
+}

score/mw/com/example/com-api-example/src/field_producer.rs

@@ -0,0 +1,96 @@
+/********************************************************************************
+ * Copyright (c) 2025 Contributors to the Eclipse Foundation
+ *
+ * See the NOTICE file(s) distributed with this work for additional
+ * information regarding copyright ownership.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Apache License Version 2.0 which is available at
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ ********************************************************************************/
+
+// This file demonstrate the usage of producer field APIs, which are generated for the VehicleFieldInterface.
+
+// Notes: we are creating producer instance specific for field here but this is just for demonstration purpose,
+// for same producer instance method / event/ field can be offered as per offer interface.
+
+// All the functions and types in this file are just for demonstration purpose,
+// as this are not part of any callable because of that unused warning is suppressed for this file.
+
+use score_com::{Builder, FieldPublisher, InstanceSpecifier, Interface, Producer, Runtime};
+
+use com_api_gen::{Exhaust, Tire, VehicleFieldInterface};
+
+// VehicleFieldProducer is the producer type for the VehicleField interface (before offering)
+#[allow(dead_code)]
+type VehicleFieldProducer<R> = <VehicleFieldInterface as Interface>::Producer<R>;
+// VehicleFieldOfferedProducer is the offered producer type for the VehicleField interface (fields support update/set-handler)
+#[allow(dead_code)]
+type VehicleFieldOfferedProducer<R> =
+    <<VehicleFieldInterface as Interface>::Producer<R> as Producer<R>>::OfferedProducer;
+
+// Below function demonstrates the field APIs usage.
+// This builds fine, but it cannot run as the field APIs in Lola runtime are not implemented yet.
+
+// Producer creation and initialization of fields with initial values and set handlers for the fields.
+// It will return the offered producer instance which can be used to update the fields.
+#[allow(dead_code)]
+fn create_producer_field<R: Runtime + 'static>(
+    runtime: &R,
+    service_id: InstanceSpecifier,
+    initial_tire_value: Tire,
+    initial_exhaust_value: Exhaust,
+) -> VehicleFieldOfferedProducer<R>
+where
+    <R as Runtime>::FieldPublisher<Tire>: Send + Sync,
+    <R as Runtime>::FieldPublisher<Exhaust>: Send,
+{
+    let producer_builder = runtime.producer_builder::<VehicleFieldInterface>(service_id);
+    let producer = producer_builder
+        .build()
+        .expect("Failed to build producer instance");
+
+    // Use validator pattern with compile-time type-state validation
+    // Must register handlers and initialize all fields before offer() is available
+    let offered = producer
+        .init()
+        // Register set-handler callbacks - required before offer() for WithSetter fields
+        .register_set_handler_left_tire(move |val: Tire| {
+            println!("Received tire pressure update: {:?}", val);
+            // Additional logic: inspect or act on the accepted value (logging, telemetry, etc.).
+            // TODO: in working example add that logic to demonstrate the set handler usage.
+        })
+        .register_set_handler_exhaust(|val: Exhaust| {
+            let _ = val;
+            println!("Received exhaust update");
+        })
+        // Register get-handler callbacks - required before offer() for WithGetter fields
+        .register_get_handler_left_tire(|| Tire { pressure: 32.0 })
+        .register_get_handler_exhaust(|| Exhaust {})
+        .update_left_tire(initial_tire_value)
+        .expect("Failed to update left_tire field")
+        .update_exhaust(initial_exhaust_value)
+        .expect("Failed to update exhaust field")
+        .offer()
+        .expect("Failed to offer producer instance");
+
+    offered
+}
+
+// Function to demonstrate the usage of the offered producer to update fields
+#[allow(dead_code)]
+fn offered_producer_process<R: Runtime>(offered_producer: VehicleFieldOfferedProducer<R>) {
+    // Use the offered producer to update fields
+    let new_tire_value = Tire { pressure: 32.0 };
+    let new_exhaust_value = Exhaust {};
+    offered_producer
+        .left_tire
+        .update(new_tire_value)
+        .expect("Failed to update left_tire field");
+    offered_producer
+        .exhaust
+        .update(new_exhaust_value)
+        .expect("Failed to update exhaust field");
+}

score/mw/com/example/com-api-example/src/lib.rs

@@ -12,12 +12,18 @@
  ********************************************************************************/
 
 pub mod consumer;
+// Method/Field/Mixed modules are just for demonstration purpose, as runtime implementation is not available yet.
+mod field_consumer;
+mod field_producer;
+mod method_consumer;
+mod method_producer;
+mod mixed_monitor;
 pub mod producer;
 pub use consumer::VehicleMonitorConsumer;
 pub use producer::VehicleMonitorProducer;
 
-use score_com::{Interface, Producer};
 use com_api_gen::VehicleInterface;
+use score_com::{Interface, Producer};
 
 // Type aliases for generated consumer and offered producer types for the Vehicle interface
 // VehicleConsumer is the consumer type generated for the Vehicle interface, parameterized by the runtime R