English | 中文

PickFast : Lock-Free Weighted Load Balancer for Low-Latency Selection

High-performance weighted random selection library with atomic EMA weight updates. Designed for load balancing, A/B testing, resource scheduling, and scenarios requiring probability-based selection with dynamic weight adjustment.

Navigation

• Features
• Usage Demonstration
• Integration with Race Crate
• Custom Rank Strategy
• Design Rationale
• API Reference
• Tech Stack
• Directory Structure
• Historical Anecdote

Features

• Lock-Free Updates: Uses AtomicU32 and Compare-And-Swap (CAS) for thread-safe weight updates without locks
• Adaptive Weighting: Implements Exponential Moving Average (EMA) to smooth latency fluctuations
• Failure Handling: Provides failed() method to quickly penalize underperforming nodes
• Weight Floor Protection: Ensures minimum weight of 1 to prevent nodes from being completely excluded
• Cache Friendly: Struct alignment prevents false sharing in multi-core environments
• Flexible Strategies: Supports custom ranking strategies via the Rank trait
• Zero Allocation: All operations are allocation-free after initialization

Usage Demonstration

High-Speed DNS Selection

use pick_fast::PickFast;
use race::Race;
use std::{net::IpAddr, sync::Arc, time::Duration};
use tokio::net::lookup_host;

#[derive(Debug, Clone, Copy)]
struct DnsServer {
  ip: IpAddr,
}

// 真实的 DNS 服务器 IP 地址 / Real DNS server IP addresses
const DNS_HOSTS: [&str; 8] = [
  "8.8.8.8",        // Google DNS
  "1.1.1.1",        // Cloudflare DNS
  "9.9.9.9",        // Quad9 DNS
  "208.67.222.222", // OpenDNS
  "223.5.5.5",      // 阿里DNS / AliDNS
  "114.114.114.114", // 114DNS
  "119.29.29.29",   // 腾讯DNS / Tencent DNS
  "180.76.76.76",   // 百度DNS / Baidu DNS
];

// 创建服务器节点（使用真实 DNS IP）/ Create server nodes (using real DNS IPs)
let servers: Vec<DnsServer> = DNS_HOSTS
  .iter()
  .map(|&ip_str| DnsServer {
    ip: ip_str.parse().expect("Invalid IP address"),
  })
  .collect();

let lb = Arc::new(PickFast::<DnsServer, pick_fast::Inverse>::new(servers));

// DNS 任务结构体，包含主机名、索引和开始时间 / DNS task struct with hostname, index and start time
#[derive(Debug, Clone)]
struct DnsTask {
  host: &'static str,
  index: usize,
  start: std::time::Instant,
}

// 带权重更新的 DNS 解析函数 / DNS resolution function with weight updates
let lb_clone = lb.clone();
let resolve_dns_with_feedback = move |task: DnsTask| {
  let lb = lb_clone.clone();

  async move {
    match lookup_host(task.host).await {
      Ok(mut addrs) => {
        if let Some(addr) = addrs.next() {
          let duration = task.start.elapsed();
          let latency_us = duration.as_micros() as u32;

          // 成功解析：更新延时权重 / Successful resolution: update latency weight
          lb.set(task.index, latency_us);

          println!(
            "  ✅ {} resolved in {duration:?} (latency: {latency_us}μs)",
            task.host
          );
          Ok(addr.ip())
        } else {
          let duration = task.start.elapsed();

          // 解析失败：降低权重 / Resolution failed: reduce weight
          lb.failed(task.index);

          let error = std::io::Error::new(
            std::io::ErrorKind::NotFound,
            format!("No address found for {}", task.host),
          );
          println!("  ❌ {} failed after {duration:?}: {error}", task.host);
          Err(error)
        }
      }
      Err(e) => {
        let duration = task.start.elapsed();

        // 网络错误：降低权重 / Network error: reduce weight
        lb.failed(task.index);

        println!("  ❌ {} failed after {duration:?}: {e}", task.host);
        Err(e)
      }
    }
  }
};

// DNS主机名带端口 / DNS hostnames with port
const DNS_HOSTS_WITH_PORT: [&str; 8] = [
  "8.8.8.8:53",        // Google DNS
  "1.1.1.1:53",        // Cloudflare DNS
  "9.9.9.9:53",        // Quad9 DNS
  "208.67.222.222:53", // OpenDNS
  "223.5.5.5:53",      // 阿里DNS / AliDNS
  "114.114.114.114:53", // 114DNS
  "119.29.29.29:53",   // 腾讯DNS / Tencent DNS
  "180.76.76.76:53",   // 百度DNS / Baidu DNS
];

// 使用 lb.iter() 创建加权随机序列用于 race / Use lb.iter() to create weighted random sequence for race
let server_iter = lb.iter().map(|server_node| {
  let index = lb.li.iter().position(|n| std::ptr::eq(n, server_node)).unwrap();
  DnsTask {
    host: DNS_HOSTS_WITH_PORT[index],
    index,
    start: std::time::Instant::now(),
  }
});

// 使用 race 进行阶梯式 DNS 解析 / Use race for staggered DNS resolution
let race = Race::new(resolve_dns_with_feedback, Duration::from_millis(500)); // 500ms 间隔 / 500ms interval
let rx = race.run(server_iter);

// 等待第一个成功的解析结果 / Wait for first successful resolution
let mut resolved_ip = None;
while let Ok(result) = rx.recv().await {
  match result {
    Ok(ip) => {
      println!("🎯 First successful resolution: {ip}");
      resolved_ip = Some(ip);
      drop(rx); // 终止 race，停止其他任务 / Terminate race, stop other tasks
      break;
    }
    Err(e) => {
      println!("⚠️  Resolution attempt failed: {e}");
      // 继续等待其他结果 / Continue waiting for other results
    }
  }
}

Custom Rank Strategy

The Rank trait defines how observed values (e.g., latency) convert to selection weights.

use pick_fast::Rank;

/// Priority-based ranking: higher priority = higher weight
pub struct Priority;

impl Rank for Priority {
  fn calc(priority: u32) -> u32 {
    priority // Direct mapping: priority value becomes weight
  }
}

// Usage
let lb = PickFast::<Task, Priority>::new(tasks);
lb.set(index, 100); // Set priority to 100

Built-in Inverse strategy suits latency-based selection:

Weight = (1 << 22) / max(Latency, 1)
Initial Weight = (1 << 22) / max(Node Count, 1)

Design choice: 2²² base ensures 256 nodes at 1μs latency won't overflow u32. Initial weight is inversely proportional to node count for reasonable initial distribution.

Design Rationale

Architecture focuses on minimizing synchronization overhead and maximizing throughput.

Call Flow

graph TD
  A[Client Request] --> B["pick()"]
  B --> C[Atomic Load Total Weight]
  C --> D[Random Target Selection]
  D --> E["Linear Scan Nodes O(N)"]
  E --> F[Return Handle]

  G[Performance Feedback] --> H["set()"]
  H --> I[Calculate Target Weight via Rank]
  I --> J[CAS Update Node Weight with EMA]
  J --> K[Atomic Update Total Weight]

EMA Smoothing

New Weight = (Old Weight + Target Weight) / 2

Smoothing prevents drastic weight changes from transient spikes.

API Reference

Core Types

Key Methods

Other Types

Tech Stack

Directory Structure

.
├── Cargo.toml          # Project configuration
├── src/
│   └── lib.rs          # Core implementation
├── tests/
│   └── main.rs         # Integration tests and chart generation
└── readme/
    ├── en.md           # English documentation
    ├── zh.md           # Chinese documentation
    ├── rank-en.svg     # English performance chart
    └── rank-zh.svg     # Chinese performance chart

Historical Anecdote

Weighted load balancing has roots in network packet scheduling. The "Weighted Round Robin" (WRR) concept was formalized in 1991 for ATM (Asynchronous Transfer Mode) networks, where heterogeneous link speeds required differential treatment.

The evolution from WRR to modern weighted random selection represents a paradigm shift: instead of deterministic slot allocation, probabilistic approaches like pick_fast offer natural load distribution. Combined with EMA smoothing—a technique borrowed from stock market technical analysis dating back to the 1960s—the algorithm adapts gracefully to varying network conditions.

Interestingly, the Compare-And-Swap primitive used here traces back to IBM System/370 in 1970, making lock-free programming concepts over 50 years old—yet they remain the cornerstone of modern high-performance concurrent systems.

About

This project is an open-source component of js0.site ⋅ Refactoring the Internet Plan.

We are redefining the development paradigm of the Internet in a componentized way. Welcome to follow us:

• Google Group
• js0site.bsky.social

PickFast : 无锁加权负载均衡，优选低延迟节点

高性能加权随机选择库，支持原子 EMA 权重更新。专为负载均衡、A/B 测试、资源调度，以及需要基于概率选择与动态权重调整的场景设计。

目录

• 项目特性
• 使用演示
• 与 Race Crate 集成
• 自定义权重计算
• 设计思路
• API 介绍
• 技术堆栈
• 目录结构
• 历史小故事

项目特性

• 无锁更新：基于 AtomicU32 和 CAS 实现线程安全的权重更新，无需互斥锁
• 自适应权重：集成指数移动平均 (EMA) 算法，平滑延时波动
• 故障处理：提供 failed() 方法快速惩罚性能不佳的节点
• 权重下限保护：确保最小权重为 1，防止节点被完全排除
• 缓存友好：结构对齐避免多核环境下的伪共享
• 灵活策略：通过 Rank 特性支持自定义权重计算逻辑
• 零分配：初始化后所有操作无内存分配

使用演示

高速 DNS 优选

use pick_fast::PickFast;
use race::Race;
use std::{net::IpAddr, sync::Arc, time::Duration};
use tokio::net::lookup_host;

#[derive(Debug, Clone, Copy)]
struct DnsServer {
  ip: IpAddr,
}

// 真实的 DNS 服务器 IP 地址 / Real DNS server IP addresses
const DNS_HOSTS: [&str; 8] = [
  "8.8.8.8",        // Google DNS
  "1.1.1.1",        // Cloudflare DNS
  "9.9.9.9",        // Quad9 DNS
  "208.67.222.222", // OpenDNS
  "223.5.5.5",      // 阿里DNS / AliDNS
  "114.114.114.114", // 114DNS
  "119.29.29.29",   // 腾讯DNS / Tencent DNS
  "180.76.76.76",   // 百度DNS / Baidu DNS
];

// 创建服务器节点（使用真实 DNS IP）/ Create server nodes (using real DNS IPs)
let servers: Vec<DnsServer> = DNS_HOSTS
  .iter()
  .map(|&ip_str| DnsServer {
    ip: ip_str.parse().expect("Invalid IP address"),
  })
  .collect();

let lb = Arc::new(PickFast::<DnsServer, pick_fast::Inverse>::new(servers));

// DNS 任务结构体，包含主机名、索引和开始时间 / DNS task struct with hostname, index and start time
#[derive(Debug, Clone)]
struct DnsTask {
  host: &'static str,
  index: usize,
  start: std::time::Instant,
}

// 带权重更新的 DNS 解析函数 / DNS resolution function with weight updates
let lb_clone = lb.clone();
let resolve_dns_with_feedback = move |task: DnsTask| {
  let lb = lb_clone.clone();

  async move {
    match lookup_host(task.host).await {
      Ok(mut addrs) => {
        if let Some(addr) = addrs.next() {
          let duration = task.start.elapsed();
          let latency_us = duration.as_micros() as u32;

          // 成功解析：更新延时权重 / Successful resolution: update latency weight
          lb.set(task.index, latency_us);

          println!(
            "  ✅ {} resolved in {duration:?} (latency: {latency_us}μs)",
            task.host
          );
          Ok(addr.ip())
        } else {
          let duration = task.start.elapsed();

          // 解析失败：降低权重 / Resolution failed: reduce weight
          lb.failed(task.index);

          let error = std::io::Error::new(
            std::io::ErrorKind::NotFound,
            format!("No address found for {}", task.host),
          );
          println!("  ❌ {} failed after {duration:?}: {error}", task.host);
          Err(error)
        }
      }
      Err(e) => {
        let duration = task.start.elapsed();

        // 网络错误：降低权重 / Network error: reduce weight
        lb.failed(task.index);

        println!("  ❌ {} failed after {duration:?}: {e}", task.host);
        Err(e)
      }
    }
  }
};

// DNS主机名带端口 / DNS hostnames with port
const DNS_HOSTS_WITH_PORT: [&str; 8] = [
  "8.8.8.8:53",        // Google DNS
  "1.1.1.1:53",        // Cloudflare DNS
  "9.9.9.9:53",        // Quad9 DNS
  "208.67.222.222:53", // OpenDNS
  "223.5.5.5:53",      // 阿里DNS / AliDNS
  "114.114.114.114:53", // 114DNS
  "119.29.29.29:53",   // 腾讯DNS / Tencent DNS
  "180.76.76.76:53",   // 百度DNS / Baidu DNS
];

// 使用 lb.iter() 创建加权随机序列用于 race / Use lb.iter() to create weighted random sequence for race
let server_iter = lb.iter().map(|server_node| {
  let index = lb.li.iter().position(|n| std::ptr::eq(n, server_node)).unwrap();
  DnsTask {
    host: DNS_HOSTS_WITH_PORT[index],
    index,
    start: std::time::Instant::now(),
  }
});

// 使用 race 进行阶梯式 DNS 解析 / Use race for staggered DNS resolution
let race = Race::new(resolve_dns_with_feedback, Duration::from_millis(500)); // 500ms 间隔 / 500ms interval
let rx = race.run(server_iter);

// 等待第一个成功的解析结果 / Wait for first successful resolution
let mut resolved_ip = None;
while let Ok(result) = rx.recv().await {
  match result {
    Ok(ip) => {
      println!("🎯 First successful resolution: {ip}");
      resolved_ip = Some(ip);
      drop(rx); // 终止 race，停止其他任务 / Terminate race, stop other tasks
      break;
    }
    Err(e) => {
      println!("⚠️  Resolution attempt failed: {e}");
      // 继续等待其他结果 / Continue waiting for other results
    }
  }
}

自定义权重计算

Rank 特性定义观测值（如延时）如何转换为选择权重。

use pick_fast::Rank;

/// 优先级排序：优先级越高，权重越大
pub struct Priority;

impl Rank for Priority {
  fn calc(priority: u32) -> u32 {
    priority // 直接映射：优先级值即权重
  }
}

// 使用示例
let lb = PickFast::<Task, Priority>::new(tasks);
lb.set(index, 100); // 设置优先级为 100

内置 Inverse 策略适用于基于延时的选择：

权重 = (1 << 22) / max(延时, 1)
初始权重 = (1 << 22) / max(节点数, 1)

设计考量：2²² 基数确保 256 节点在 1μs 延时下不会溢出 u32。初始权重与节点数成反比，确保合理的初始分布。

设计思路

架构核心：最小化同步开销，最大化吞吐量。

调用流程

graph TD
  A[客户端请求] --> B["pick()"]
  B --> C[原子加载总权重]
  C --> D[随机目标选择]
  D --> E["线性扫描节点 O(N)"]
  E --> F[返回 Handle]

  G[性能反馈] --> H["set()"]
  H --> I[通过 Rank 计算目标权重]
  I --> J[CAS 更新节点权重 含EMA]
  J --> K[原子更新总权重]

EMA 平滑

新权重 = (旧权重 + 目标权重) / 2

平滑机制防止瞬时尖峰导致权重剧烈变化。

API 介绍

核心类型

关键方法

其他类型

技术堆栈

目录结构

.
├── Cargo.toml          # 项目配置
├── src/
│   └── lib.rs          # 核心实现
├── tests/
│   └── main.rs         # 集成测试与图表生成
└── readme/
    ├── en.md           # 英文文档
    ├── zh.md           # 中文文档
    ├── rank-en.svg     # 英文性能图表
    └── rank-zh.svg     # 中文性能图表

历史小故事

加权负载均衡起源于网络数据包调度。1991 年，"加权轮询" (Weighted Round Robin, WRR) 概念在 ATM (异步传输模式) 网络中被正式提出，用于处理异构链路速度的差异化调度需求。

从 WRR 到现代加权随机选择，代表着范式转变：从确定性槽位分配，转向概率方法实现自然的负载分布。结合指数移动平均 (EMA) 平滑——该技术源自 1960 年代的股票市场技术分析——算法能优雅地适应网络条件变化。

有趣的是，这里使用的 CAS (Compare-And-Swap) 原语可追溯至 1970 年的 IBM System/370，使得无锁编程概念已有 50 余年历史——但它仍是现代高性能并发系统的基石。

关于

本项目为 js0.site ⋅ 重构互联网计划 的开源组件。

我们正在以组件化的方式重新定义互联网的开发范式，欢迎关注：

• 谷歌邮件列表
• js0site.bsky.social