Added utility method for custom map downlink stores.

Updated doc comments.

Author: horned-sphere

server/swimos_agent/src/agent_lifecycle/utility/mod.rs

@@ -897,6 +897,30 @@ impl<Agent: 'static> HandlerContext<Agent> {
         StatelessMapDownlinkBuilder::new(Address::text(host, node, lane), config)
     }
 
+    /// Create a builder to construct a request to open a map downlink, using the specified map type
+    /// as the backing representation of the downlink.
+    /// # Arguments
+    /// * `host` - The remote host at which the agent resides (a local agent if not specified).
+    /// * `node` - The node URI of the agent.
+    /// * `lane` - The lane to downlink from.
+    /// * `config` - Configuration parameters for the downlink.
+    pub fn map_downlink_builder_for<K, V, M>(
+        &self,
+        host: Option<&str>,
+        node: &str,
+        lane: &str,
+        config: MapDownlinkConfig,
+    ) -> StatelessMapDownlinkBuilder<Agent, K, V, M>
+    where
+        M: MapOpsWithEntry<K, V, K>,
+        K: Form + Hash + Eq + Clone + Send + Sync + 'static,
+        K::Rec: Send,
+        V: Form + Send + Sync + 'static,
+        V::Rec: Send,
+    {
+        StatelessMapDownlinkBuilder::new(Address::text(host, node, lane), config)
+    }
+
     /// Causes the agent to stop. If this is encountered during the `on_start` event of an agent it will
     /// fail to start at all. Otherwise, execution of the event handler will terminate and the agent will
     /// begin to shutdown. The 'on_stop' handler will still be run. If a stop is requested in

server/swimos_agent/src/downlink_lifecycle/map/mod.rs

@@ -44,6 +44,7 @@ mod on_update;
 /// # Type Parameters
 /// * `K` - The type of the keys of the downlink.
 /// * `V` - The type of the values of the downlink.
+/// * `M` - The map type underlying the downlink (i.e. [`std::collections::HashMap<K, V>`]).
 /// * `Context` - The context within which the event handlers execute (providing access to the agent lanes).
 pub trait MapDownlinkLifecycle<K, V, M, Context>:
     OnLinked<Context>
@@ -73,6 +74,7 @@ impl<LC, K, V, M, Context> MapDownlinkLifecycle<K, V, M, Context> for LC where
 /// * `Context` - The context within which the event handlers execute (providing access to the agent lanes).
 /// * `K` - The type of the keys for the map.
 /// * `V` - The type of the values for the map.
+/// * `M` - The map type underlying the downlink (i.e. [`std::collections::HashMap<K, V>`]).
 pub trait StatelessMapLifecycle<Context, K, V, M>: MapDownlinkLifecycle<K, V, M, Context> {
     type WithOnLinked<H>: StatelessMapLifecycle<Context, K, V, M>
     where
@@ -146,6 +148,7 @@ pub trait StatelessMapLifecycle<Context, K, V, M>: MapDownlinkLifecycle<K, V, M,
 /// * `Shared` - The type of the shared state.
 /// * `K` - The type of the keys for the map.
 /// * `V` - The type of the values for the map.
+/// * `M` - The map type underlying the downlink (i.e. [`std::collections::HashMap<K, V>`]).
 pub trait StatefulMapLifecycle<Context, Shared, K, V, M>:
     MapDownlinkLifecycle<K, V, M, Context>
 {
@@ -214,6 +217,7 @@ pub trait StatefulMapLifecycle<Context, Shared, K, V, M>:
 /// * `Context` - The context within which the event handlers execute (providing access to the agent lanes).
 /// * `K` - The type of the keys of the downlink.
 /// * `V` - The type of the values of the downlink.
+/// * `M` - The map type underlying the downlink (i.e. [`std::collections::HashMap<K, V>`]).
 /// * `FLinked` - The type of the 'on_linked' handler.
 /// * `FSynced` - The type of the 'on_synced' handler.
 /// * `FUnlinked` - The type of the 'on_unlinked' handler.
@@ -267,6 +271,7 @@ impl<Context, K, V, M> Default for StatelessMapDownlinkLifecycle<Context, K, V,
 /// * `State` - The type of the shared state.
 /// * `K` - The type of the keys of the downlink.
 /// * `V` - The type of the values of the downlink.
+/// * `M` - The map type underlying the downlink (i.e. [`std::collections::HashMap<K, V>`]).
 /// * `FLinked` - The type of the 'on_linked' handler.
 /// * `FSynced` - The type of the 'on_synced' handler.
 /// * `FUnlinked` - The type of the 'on_unlinked' handler.

server/swimos_agent/src/lanes/map/lifecycle/mod.rs

@@ -33,6 +33,7 @@ pub mod on_update;
 /// # Type Parameters
 /// * `K` - The type of the map keys.
 /// * `V` - The type of the map values.
+/// * `M` - The map type underlying the lane (i.e. [`std::collections::HashMap<K, V>`]).
 /// * `Context` - The context within which the event handlers execute (providing access to the agent lanes).
 pub trait MapLaneLifecycle<K, V, M, Context>:
     OnUpdate<K, V, M, Context> + OnRemove<K, V, M, Context> + OnClear<M, Context>
@@ -67,7 +68,7 @@ type LifecycleType<Context, Shared, K, V, M> = fn(Context, Shared, K, V, M);
 /// * `Shared` - The shared state to which the lifecycle has access.
 /// * `K` - The key type of the map.
 /// * `V` - The value type of the map.
-/// * `M` - The map type (for example `HashMap<K, V>`).
+/// * `M` - The map type underlying the lane (i.e. [`std::collections::HashMap<K, V>`]).
 /// * `FUpd` - The `on_update` event handler.
 /// * `FRem` - The `on_remove` event handler.
 /// * `FClr` - The `on_clear` event handler.