Struct NeighborLists 

pub struct NeighborLists { /* private fields */ }

Storage for neighbor lists (lock-free reads, thread-safe writes)

Neighbors are stored separately from nodes to improve cache utilization. Only fetch neighbors when traversing the graph.

Thread-safety:

• Reads: Lock-free via ArcSwap (just atomic load)
• Writes: Mutex-protected copy-on-write for thread-safety

Performance: Search is read-heavy, construction is write-heavy. Lock-free reads give ~40% speedup on high-dimension searches.

Implementations

impl NeighborLists

pub fn new(max_levels: usize) -> Self

Create empty neighbor lists

pub fn with_capacity(num_nodes: usize, max_levels: usize, m: usize) -> Self

Create with pre-allocated capacity and M parameter

pub fn m_max(&self) -> usize

Get M_max (max neighbors)

pub fn len(&self) -> usize

Get number of nodes with neighbor lists

pub fn is_empty(&self) -> bool

Check if empty

pub fn get_neighbors(&self, node_id: u32, level: u8) -> Vec<u32>

Get neighbors for a node at a specific level (lock-free)

Returns a cloned Vec. For iteration without allocation, use with_neighbors.

pub fn with_neighbors<F, R>(&self, node_id: u32, level: u8, f: F) -> R

where F: FnOnce(&[u32]) -> R,

Execute a closure with read access to neighbors (LOCK-FREE, zero-copy)

This is the hot path for search - just an atomic load, no locking. ~40% faster than RwLock at high dimensions (1536D+).

pub fn prefetch(&self, node_id: u32, level: u8)

Prefetch neighbor list into CPU cache

Hints to CPU that we’ll need the neighbor data soon. This hides memory latency by overlapping data fetch with computation. Only beneficial on x86/ARM servers - Apple Silicon’s DMP handles this automatically.

pub fn set_neighbors( &mut self, node_id: u32, level: u8, neighbors_list: Vec<u32>, )

Set neighbors for a node at a specific level

pub fn add_bidirectional_link(&mut self, node_a: u32, node_b: u32, level: u8)

Add a bidirectional link between two nodes at a level

Thread-safe with deadlock prevention via ordered locking. Uses copy-on-write for lock-free reads during search.

pub fn add_bidirectional_link_parallel( &self, node_a: u32, node_b: u32, level: u8, )

Add bidirectional link (thread-safe version for parallel construction)

Assumes nodes are already allocated. Uses mutex + copy-on-write. Only for use during parallel graph construction where all nodes pre-exist.

pub fn remove_link_parallel(&self, node_a: u32, node_b: u32, level: u8)

Remove unidirectional link (thread-safe version for parallel construction)

Removes link from node_a to node_b (NOT bidirectional). Uses mutex + copy-on-write for thread-safety.

pub fn set_neighbors_parallel( &self, node_id: u32, level: u8, neighbors_list: Vec<u32>, )

Set neighbors (thread-safe version for parallel construction)

Assumes node is already allocated. Uses mutex for thread-safety.

pub fn total_neighbors(&self) -> usize

Get total number of neighbor entries

pub fn memory_usage(&self) -> usize

Get memory usage in bytes (approximate)

pub fn reorder_bfs(&mut self, entry_point: u32, start_level: u8) -> Vec<u32>

Reorder nodes using BFS for cache locality

This improves cache performance by placing frequently-accessed neighbors close together in memory. Uses BFS from the entry point to determine ordering.

Returns a mapping from old_id -> new_id

pub fn num_nodes(&self) -> usize

Get number of nodes

Trait Implementations

impl Debug for NeighborLists

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for NeighborLists

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for NeighborLists

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.