feat: add optional hotpath profiling support (#2380)

* feat: add hotpath profiling support
* perf(hotpath): make hotpath an optional dependency

easytier/Cargo.toml

@@ -52,6 +52,7 @@ toml = "0.8.12"
 chrono = { version = "0.4.37", features = ["serde"] }
 
 guarden = "0.2"
+hotpath = { version = "0.18", default-features = false, optional = true }
 
 delegate = "0.13.5"
 
@@ -401,6 +402,15 @@ jemalloc-prof = [
     "jemalloc-sys/stats",
 ]
 tracing = ["tokio/tracing", "dep:console-subscriber"]
+hotpath = [
+    "dep:hotpath",
+    "hotpath/hotpath",
+    "hotpath/tokio",
+    "hotpath/parking_lot",
+    "hotpath/flume",
+]
+hotpath-cpu = ["hotpath", "hotpath/hotpath-cpu"]
+hotpath-alloc = ["hotpath", "hotpath/hotpath-alloc"]
 magic-dns = ["dep:hickory-client", "dep:hickory-server"]
 faketcp = ["dep:flume"]
 zstd = ["dep:zstd"]

easytier/src/easytier-core.rs

@@ -1,5 +1,11 @@
 use easytier::core;
 
+#[cfg(all(
+    feature = "hotpath-alloc",
+    any(feature = "jemalloc", feature = "mimalloc")
+))]
+compile_error!("feature `hotpath-alloc` cannot be enabled together with `jemalloc` or `mimalloc`");
+
 #[cfg(all(feature = "mimalloc", not(feature = "jemalloc")))]
 use mimalloc::MiMalloc;
 
@@ -24,6 +30,16 @@ pub static malloc_conf: &[u8] = b"retain:false\0";
 rust_i18n::i18n!("locales", fallback = "en");
 
 #[tokio::main(flavor = "current_thread")]
+#[cfg_attr(
+    all(
+        feature = "hotpath",
+        not(all(
+            feature = "hotpath-alloc",
+            any(feature = "jemalloc", feature = "mimalloc")
+        ))
+    ),
+    hotpath::main
+)]
 async fn main() -> std::process::ExitCode {
     core::main().await
 }

easytier/src/hotpath_off.rs

@@ -0,0 +1,40 @@
+//! No-op stand-in for the `hotpath` macros used by this crate, selected when
+//! the `hotpath` feature is disabled.
+//!
+//! Keeping `hotpath` as an optional dependency means default builds do not pull
+//! the profiler (or any of its transitive dependencies) into the dependency
+//! graph. These macros expand to their input unchanged, mirroring `hotpath`'s
+//! own disabled mode so call sites compile identically with or without the
+//! feature.
+//!
+//! The macros are `#[macro_export]`-ed so that `lib.rs`' `extern crate self as
+//! hotpath` alias exposes them through the same `hotpath::...` paths used when
+//! the feature is enabled.
+
+/// No-op mirroring `hotpath::channel!`: returns the channel expression
+/// unchanged (dropping any optional trailing `label`/`log`/`capacity` args).
+#[doc(hidden)]
+#[macro_export]
+macro_rules! channel {
+    ($expr:expr $(, $($rest:tt)*)?) => {
+        $expr
+    };
+}
+
+/// No-op mirroring `hotpath::mutex!`: returns the expression unchanged.
+#[doc(hidden)]
+#[macro_export]
+macro_rules! mutex {
+    ($expr:expr $(, $($rest:tt)*)?) => {
+        $expr
+    };
+}
+
+/// No-op mirroring `hotpath::rw_lock!`: returns the expression unchanged.
+#[doc(hidden)]
+#[macro_export]
+macro_rules! rw_lock {
+    ($expr:expr $(, $($rest:tt)*)?) => {
+        $expr
+    };
+}

easytier/src/lib.rs

@@ -5,6 +5,15 @@ use std::io;
 use clap::Command;
 use clap_complete::{Generator, Shell};
 
+// When the `hotpath` feature is off, alias the current crate as `hotpath` so
+// call sites keep using `hotpath::...` paths, and provide a local no-op shim
+// for the profiling macros. This keeps `hotpath` an optional dependency: the
+// profiler is absent from the dependency graph entirely in default builds.
+#[cfg(not(feature = "hotpath"))]
+extern crate self as hotpath;
+#[cfg(not(feature = "hotpath"))]
+mod hotpath_off;
+
 mod arch;
 mod gateway;
 pub mod instance;

easytier/src/peers/mod.rs

@@ -59,7 +59,7 @@ type BoxNicPacketFilter = Box<dyn NicPacketFilter + Send + Sync>;
 pub type PacketRecvChan = tokio::sync::mpsc::Sender<ZCPacket>;
 pub type PacketRecvChanReceiver = tokio::sync::mpsc::Receiver<ZCPacket>;
 pub fn create_packet_recv_chan() -> (PacketRecvChan, PacketRecvChanReceiver) {
-    tokio::sync::mpsc::channel(128)
+    hotpath::channel!(tokio::sync::mpsc::channel(128))
 }
 pub async fn recv_packet_from_chan(
     packet_recv_chan_receiver: &mut PacketRecvChanReceiver,

easytier/src/peers/peer.rs

@@ -207,6 +207,7 @@ impl Peer {
             .map(|conn| conn.clone())
     }
 
+    #[cfg_attr(feature = "hotpath", hotpath::measure(impl_type = "Peer"))]
     pub async fn send_msg(&self, msg: ZCPacket) -> Result<(), Error> {
         let Some(conn) = self.select_conn().await else {
             return Err(Error::PeerNoConnectionError(self.peer_node_id));

easytier/src/peers/peer_conn.rs

@@ -10,6 +10,15 @@ use std::{
     },
 };
 
+#[cfg(feature = "hotpath")]
+use hotpath::wrap::std::sync::Mutex as StdMutex;
+#[cfg(feature = "hotpath")]
+use hotpath::wrap::tokio::sync::Mutex;
+#[cfg(not(feature = "hotpath"))]
+use std::sync::Mutex as StdMutex;
+#[cfg(not(feature = "hotpath"))]
+use tokio::sync::Mutex;
+
 use base64::Engine as _;
 use base64::engine::general_purpose::STANDARD as BASE64_STANDARD;
 use guarden::guard;
@@ -17,7 +26,7 @@ use hmac::Mac;
 use prost::Message;
 
 use tokio::{
-    sync::{Mutex, broadcast},
+    sync::broadcast,
     task::JoinSet,
     time::{Duration, timeout},
 };
@@ -98,7 +107,7 @@ struct PeerSessionTunnelFilter {
     enabled: bool,
     my_peer_id: Arc<AtomicCell<PeerId>>,
     peer_id: Arc<AtomicCell<Option<PeerId>>>,
-    session: Arc<std::sync::Mutex<Option<Arc<PeerSession>>>>,
+    session: Arc<StdMutex<Option<Arc<PeerSession>>>>,
 }
 
 impl PeerSessionTunnelFilter {
@@ -107,7 +116,7 @@ impl PeerSessionTunnelFilter {
             enabled,
             my_peer_id: Arc::new(AtomicCell::new(PeerId::default())),
             peer_id: Arc::new(AtomicCell::new(None)),
-            session: Arc::new(std::sync::Mutex::new(None)),
+            session: Arc::new(hotpath::mutex!(std::sync::Mutex::new(None))),
         }
     }
 
@@ -116,7 +125,7 @@ impl PeerSessionTunnelFilter {
             enabled,
             my_peer_id: Arc::new(AtomicCell::new(my_peer_id)),
             peer_id: Arc::new(AtomicCell::new(None)),
-            session: Arc::new(std::sync::Mutex::new(None)),
+            session: Arc::new(hotpath::mutex!(std::sync::Mutex::new(None))),
         }
     }
 
@@ -379,11 +388,12 @@ impl PeerConn {
             session_filter,
             noise_handshake_result: None,
 
-            tunnel: Arc::new(Mutex::new(Box::new(
+            tunnel: Arc::new(hotpath::mutex!(tokio::sync::Mutex::new(Box::new(
                 guard!([mut mpsc_tunnel] mpsc_tunnel.close()),
-            ))),
+            )
+                as Box<dyn Any + Send + 'static>))),
             sink,
-            recv: Mutex::new(Some(recv)),
+            recv: hotpath::mutex!(tokio::sync::Mutex::new(Some(recv))),
             tunnel_info,
 
             tasks: JoinSet::new(),
@@ -1460,6 +1470,7 @@ impl PeerConn {
         });
     }
 
+    #[cfg_attr(feature = "hotpath", hotpath::measure(impl_type = "PeerConn"))]
     pub async fn send_msg(&self, msg: ZCPacket) -> Result<(), Error> {
         Ok(self.sink.send(msg).await?)
     }

easytier/src/peers/peer_manager.rs

@@ -10,11 +10,12 @@ use std::{
     time::{Duration, Instant, SystemTime},
 };
 
+#[cfg(feature = "hotpath")]
+use hotpath::wrap::tokio::sync::{Mutex, RwLock};
+#[cfg(not(feature = "hotpath"))]
+use tokio::sync::{Mutex, RwLock};
 use tokio::{
-    sync::{
-        Mutex, RwLock,
-        mpsc::{self, UnboundedReceiver, UnboundedSender},
-    },
+    sync::mpsc::{self, UnboundedReceiver, UnboundedSender},
     task::JoinSet,
 };
 
@@ -277,8 +278,8 @@ impl PeerManager {
         let rpc_tspt = Arc::new(RpcTransport {
             my_peer_id,
             peers: Arc::downgrade(&peers),
-            foreign_peers: Mutex::new(None),
-            packet_recv: Mutex::new(peer_rpc_tspt_recv),
+            foreign_peers: hotpath::mutex!(tokio::sync::Mutex::new(None)),
+            packet_recv: hotpath::mutex!(tokio::sync::Mutex::new(peer_rpc_tspt_recv)),
             peer_rpc_tspt_sender,
             encryptor: encryptor.clone(),
             is_secure_mode_enabled,
@@ -410,17 +411,21 @@ impl PeerManager {
             global_ctx,
             nic_channel,
 
-            tasks: Mutex::new(JoinSet::new()),
+            tasks: hotpath::mutex!(tokio::sync::Mutex::new(JoinSet::new())),
 
-            packet_recv: Arc::new(Mutex::new(Some(packet_recv))),
+            packet_recv: Arc::new(hotpath::mutex!(tokio::sync::Mutex::new(Some(packet_recv)))),
 
             peers,
 
             peer_rpc_mgr,
             peer_rpc_tspt: rpc_tspt,
 
-            peer_packet_process_pipeline: Arc::new(RwLock::new(Vec::new())),
-            nic_packet_process_pipeline: Arc::new(RwLock::new(Vec::new())),
+            peer_packet_process_pipeline: Arc::new(hotpath::rw_lock!(tokio::sync::RwLock::new(
+                Vec::new()
+            ))),
+            nic_packet_process_pipeline: Arc::new(hotpath::rw_lock!(tokio::sync::RwLock::new(
+                Vec::new()
+            ))),
 
             route_algo_inst,
 
@@ -431,7 +436,7 @@ impl PeerManager {
             encryptor,
             data_compress_algo,
 
-            exit_nodes: RwLock::new(exit_nodes),
+            exit_nodes: hotpath::rw_lock!(tokio::sync::RwLock::new(exit_nodes)),
 
             reserved_my_peer_id_map: DashMap::new(),
             recent_have_traffic: Arc::new(DashMap::new()),
@@ -1438,6 +1443,7 @@ impl PeerManager {
         self.get_route().get_foreign_network_summary().await
     }
 
+    #[cfg_attr(feature = "hotpath", hotpath::measure(impl_type = "PeerManager"))]
     async fn run_nic_packet_process_pipeline(&self, data: &mut ZCPacket) -> bool {
         // Enforce ACL for outbound (NIC-originated) packets. If ACL denies, stop processing.
         if !self.global_ctx.get_acl_filter().process_packet_with_acl(
@@ -1523,6 +1529,7 @@ impl PeerManager {
         result
     }
 
+    #[cfg_attr(feature = "hotpath", hotpath::measure(impl_type = "PeerManager"))]
     async fn send_msg_internal(
         peers: &Arc<PeerMap>,
         foreign_network_client: &Arc<ForeignNetworkClient>,

easytier/src/peers/peer_map.rs

@@ -132,6 +132,7 @@ impl PeerMap {
         peer_id == self.my_peer_id || self.peer_map.contains_key(&peer_id)
     }
 
+    #[cfg_attr(feature = "hotpath", hotpath::measure(impl_type = "PeerMap"))]
     pub async fn send_msg_directly(&self, msg: ZCPacket, dst_peer_id: PeerId) -> Result<(), Error> {
         if dst_peer_id == self.my_peer_id {
             let packet_send = self.packet_send.clone();
@@ -163,6 +164,7 @@ impl PeerMap {
         Ok(())
     }
 
+    #[cfg_attr(feature = "hotpath", hotpath::measure(impl_type = "PeerMap"))]
     pub async fn get_gateway_peer_id(
         &self,
         dst_peer_id: PeerId,

easytier/src/peers/peer_ospf_route.rs

@@ -1393,6 +1393,7 @@ impl RouteTable {
         }
     }
 
+    #[cfg_attr(feature = "hotpath", hotpath::measure(impl_type = "RouteTable"))]
     fn get_next_hop(&self, dst_peer_id: PeerId) -> Option<NextHopInfo> {
         if self.suppressed_peer_ids.contains_key(&dst_peer_id) {
             return None;
@@ -1400,6 +1401,7 @@ impl RouteTable {
         self.get_topology_next_hop(dst_peer_id)
     }
 
+    #[cfg_attr(feature = "hotpath", hotpath::measure(impl_type = "RouteTable"))]
     fn get_topology_next_hop(&self, dst_peer_id: PeerId) -> Option<NextHopInfo> {
         let cur_version = self.next_hop_map_version.get();
         self.next_hop_map.get(&dst_peer_id).and_then(|x| {

easytier/src/peers/peer_session.rs

@@ -337,6 +337,7 @@ impl PeerSession {
         }
     }
 
+    #[cfg_attr(feature = "hotpath", hotpath::measure(impl_type = "PeerSession"))]
     pub fn encrypt_payload(
         &self,
         sender_peer_id: PeerId,
@@ -350,6 +351,7 @@ impl PeerSession {
             .encrypt_payload(Self::dir_for_sender(sender_peer_id, receiver_peer_id), pkt)
     }
 
+    #[cfg_attr(feature = "hotpath", hotpath::measure(impl_type = "PeerSession"))]
     pub fn decrypt_payload(
         &self,
         sender_peer_id: PeerId,

easytier/src/peers/secure_datagram.rs

@@ -701,6 +701,10 @@ impl SecureDatagramSession {
         false
     }
 
+    #[cfg_attr(
+        feature = "hotpath",
+        hotpath::measure(impl_type = "SecureDatagramSession")
+    )]
     pub fn encrypt_payload(
         &self,
         dir: SecureDatagramDirection,
@@ -719,6 +723,10 @@ impl SecureDatagramSession {
         Ok(())
     }
 
+    #[cfg_attr(
+        feature = "hotpath",
+        hotpath::measure(impl_type = "SecureDatagramSession")
+    )]
     pub fn decrypt_payload(
         &self,
         dir: SecureDatagramDirection,

easytier/src/tunnel/fake_tcp/stack.rs

@@ -159,7 +159,7 @@ impl Socket {
         ack: Option<u32>,
         state: State,
     ) -> (Socket, flume::Sender<Bytes>) {
-        let (incoming_tx, incoming_rx) = flume::bounded(MPMC_BUFFER_LEN);
+        let (incoming_tx, incoming_rx) = hotpath::channel!(flume::bounded(MPMC_BUFFER_LEN));
 
         (
             Socket {

easytier/src/tunnel/mpsc.rs

@@ -43,7 +43,7 @@ pub struct MpscTunnel<T> {
 
 impl<T: Tunnel> MpscTunnel<T> {
     pub fn new(tunnel: T, send_timeout: Option<Duration>) -> Self {
-        let (tx, mut rx) = channel(32);
+        let (tx, mut rx) = hotpath::channel!(channel(32));
         let (stream, mut sink) = tunnel.split();
 
         let task = tokio::spawn(async move {
@@ -66,6 +66,7 @@ impl<T: Tunnel> MpscTunnel<T> {
         }
     }
 
+    #[cfg_attr(feature = "hotpath", hotpath::measure(impl_type = "MpscTunnel"))]
     async fn forward_one_round(
         rx: &mut Receiver<ZCPacket>,
         sink: &mut Pin<Box<dyn ZCPacketSink>>,
@@ -79,6 +80,7 @@ impl<T: Tunnel> MpscTunnel<T> {
         }
     }
 
+    #[cfg_attr(feature = "hotpath", hotpath::measure(impl_type = "MpscTunnel"))]
     async fn forward_one_round_no_timeout(
         rx: &mut Receiver<ZCPacket>,
         sink: &mut Pin<Box<dyn ZCPacketSink>>,
@@ -96,6 +98,7 @@ impl<T: Tunnel> MpscTunnel<T> {
         sink.flush().await
     }
 
+    #[cfg_attr(feature = "hotpath", hotpath::measure(impl_type = "MpscTunnel"))]
     async fn forward_one_round_with_timeout(
         rx: &mut Receiver<ZCPacket>,
         sink: &mut Pin<Box<dyn ZCPacketSink>>,

easytier/src/tunnel/ring.rs

@@ -196,7 +196,8 @@ pub struct RingTunnelListener {
 
 impl RingTunnelListener {
     pub fn new(key: url::Url) -> Self {
-        let (conn_sender, conn_receiver) = tokio::sync::mpsc::unbounded_channel();
+        let (conn_sender, conn_receiver) =
+            hotpath::channel!(tokio::sync::mpsc::unbounded_channel());
         RingTunnelListener {
             listener_addr: key,
             conn_sender,

easytier/src/tunnel/udp.rs

@@ -572,8 +572,9 @@ pub struct UdpTunnelListener {
 
 impl UdpTunnelListener {
     pub fn new(addr: url::Url) -> Self {
-        let (close_event_send, close_event_recv) = tokio::sync::mpsc::unbounded_channel();
-        let (conn_send, conn_recv) = tokio::sync::mpsc::channel(100);
+        let (close_event_send, close_event_recv) =
+            hotpath::channel!(tokio::sync::mpsc::unbounded_channel());
+        let (conn_send, conn_recv) = hotpath::channel!(tokio::sync::mpsc::channel(100));
         Self {
             addr: addr.clone(),
             socket: None,
@@ -784,7 +785,8 @@ impl UdpTunnelConnector {
             "udp build tunnel for connector"
         );
 
-        let (close_event_sender, mut close_event_recv) = tokio::sync::mpsc::unbounded_channel();
+        let (close_event_sender, mut close_event_recv) =
+            hotpath::channel!(tokio::sync::mpsc::unbounded_channel());
 
         let ring_recv = RingStream::new(ring_for_send_udp.clone());
         let ring_sender = RingSink::new(ring_for_recv_udp.clone());

easytier/src/tunnel/wireguard.rs

@@ -468,7 +468,7 @@ pub struct WgTunnelListener {
 
 impl WgTunnelListener {
     pub fn new(addr: url::Url, config: WgConfig) -> Self {
-        let (conn_send, conn_recv) = tokio::sync::mpsc::unbounded_channel();
+        let (conn_send, conn_recv) = hotpath::channel!(tokio::sync::mpsc::unbounded_channel());
         WgTunnelListener {
             addr,
             config,