ixa/network/
edge.rs

1use std::collections::HashMap;
2use std::sync::atomic::{AtomicUsize, Ordering};
3use std::sync::{LazyLock, Mutex};
4
5use crate::entity::{Entity, EntityId};
6
7#[derive(Copy, Debug, PartialEq)]
8/// An edge in the network graph. Edges are directed, so the
9/// source person is implicit.
10pub struct Edge<E: Entity, ET: EdgeType<E>> {
11    /// The person this edge points to.
12    pub neighbor: EntityId<E>,
13    /// The weight associated with the edge.
14    pub weight: f32,
15    /// An inner value defined by type `T`. Often a ZST.
16    pub inner: ET,
17}
18
19// Generics prevent the compiler from "seeing" that `Edge` always satisfies these
20// traits if they are derived.
21impl<E: Entity, ET: EdgeType<E>> Clone for Edge<E, ET> {
22    fn clone(&self) -> Self {
23        Self {
24            neighbor: self.neighbor,
25            weight: self.weight,
26            inner: self.inner.clone(),
27        }
28    }
29}
30
31pub trait EdgeType<E: Entity>: Clone + 'static {
32    fn name() -> &'static str {
33        let full = std::any::type_name::<Self>();
34        full.rsplit("::").next().unwrap()
35    }
36
37    /// The index of this item in the owner, which is initialized globally per type
38    /// upon first access. We explicitly initialize this in a `ctor` in order to know
39    /// how many [`EdgeType<E>`] types exist globally when we construct any `NetworkStore<E>`.
40    fn id() -> usize;
41}
42
43/// A map from Entity ID to a count of the edge types already associated with the entity. The value for the key is
44/// equivalent to the next edge type ID that will be assigned to the next edge type that requests an ID. Each `Entity`
45/// type has its own series of increasing edge type IDs.
46static NEXT_EDGE_TYPE_ID_BY_ENTITY: LazyLock<Mutex<HashMap<usize, usize>>> =
47    LazyLock::new(|| Mutex::new(HashMap::default()));
48
49/// Returns the number of registered edge types for the entity type `E`.
50pub fn get_registered_edge_type_count<E: Entity>() -> usize {
51    let map = NEXT_EDGE_TYPE_ID_BY_ENTITY.lock().unwrap();
52    *map.get(&E::id()).unwrap_or(&0)
53}
54
55/// Adds a new edge type to the registry. The job of this method is to create whatever
56/// "singleton" data/metadata is associated with the [`EdgeType`] if it doesn't already
57/// exist, which in this case is only the value of `EdgeType::id()`.
58pub fn add_to_edge_type_to_registry<E: Entity, ET: EdgeType<E>>() {
59    let _ = ET::id();
60}
61
62/// Encapsulates the synchronization logic for initializing an [`EdgeType<E>`]'s ID.
63///
64/// Acquires a global lock on the next available edge type ID for the given entity type `E`,
65/// but only increments it if we successfully initialize the provided ID. The ID of an
66/// edge type is
67/// assigned at runtime but only once per type. It's possible for a single
68/// type to attempt to initialize its index multiple times from different threads,
69/// which is why all this synchronization is required. However, the overhead
70/// is negligible, as this initialization only happens once upon first access.
71///
72/// In fact, for our use case we know we are calling this function
73/// once for each type in each `EdgeType<E>`'s `ctor` function, which
74/// should be the only time this method is ever called for the type.
75pub fn initialize_edge_type_id<E: Entity>(edge_type_id: &AtomicUsize) -> usize {
76    // Acquire a global lock.
77    let mut guard = NEXT_EDGE_TYPE_ID_BY_ENTITY.lock().unwrap();
78    let candidate = guard.entry(E::id()).or_insert_with(|| 0);
79
80    // Try to claim the candidate index. Here we guard against the potential race condition that
81    // another instance of this plugin in another thread just initialized the index prior to us
82    // obtaining the lock. If the index has been initialized beneath us, we do not update
83    // NEXT_EDGE_TYPE_ID_BY_ENTITY, we just return the value `edge_type_id` was initialized to.
84    // For a justification of the data ordering, see:
85    //     https://github.com/CDCgov/ixa/pull/477#discussion_r2244302872
86    match edge_type_id.compare_exchange(usize::MAX, *candidate, Ordering::AcqRel, Ordering::Acquire)
87    {
88        Ok(_) => {
89            // We won the race — increment the global next edge-type ID and return the new ID.
90            *candidate += 1;
91            *candidate - 1
92        }
93        Err(existing) => {
94            // Another thread beat us — don’t increment the global next edge-type ID,
95            // just return the existing one.
96            existing
97        }
98    }
99}
ixa/network/edge.rs

ixa/network/
edge.rs
