pub struct IcmpEchoRequestor { /* private fields */ }
Expand description
Requestor for sending ICMP Echo Requests (ping) and receiving replies on Unix systems.
This implementation uses ICMP sockets with Tokio for async operations. It requires
unprivileged ICMP socket support, which is available on macOS by default and on
Linux when the net.ipv4.ping_group_range
sysctl parameter is properly configured.
The requestor spawns a background task to handle incoming replies and is safe to clone and use across multiple threads and async tasks.
§Platform Requirements
- macOS: Works with unprivileged sockets out of the box
- Linux: Requires
net.ipv4.ping_group_range
sysctl to allow unprivileged ICMP sockets
§Examples
use ping_async::IcmpEchoRequestor;
use std::net::IpAddr;
#[tokio::main]
async fn main() -> std::io::Result<()> {
let target = "8.8.8.8".parse::<IpAddr>().unwrap();
let pinger = IcmpEchoRequestor::new(target, None, None, None)?;
let reply = pinger.send().await?;
println!("Reply: {:?}", reply);
Ok(())
}
Implementations§
Source§impl IcmpEchoRequestor
impl IcmpEchoRequestor
Sourcepub fn new(
target_addr: IpAddr,
source_addr: Option<IpAddr>,
ttl: Option<u8>,
timeout: Option<Duration>,
) -> Result<Self>
pub fn new( target_addr: IpAddr, source_addr: Option<IpAddr>, ttl: Option<u8>, timeout: Option<Duration>, ) -> Result<Self>
Creates a new ICMP echo requestor for the specified target address.
§Arguments
target_addr
- The IP address to ping (IPv4 or IPv6)source_addr
- Optional source IP address to bind to. Must match the IP version oftarget_addr
ttl
- Optional Time-To-Live value. Defaults toPING_DEFAULT_TTL
timeout
- Optional timeout duration. Defaults toPING_DEFAULT_TIMEOUT
§Errors
Returns an error if:
- The source address type doesn’t match the target address type (IPv4 vs IPv6)
- ICMP socket creation fails (typically due to insufficient permissions)
- Socket configuration fails
§Platform Requirements
- Linux: Requires
net.ipv4.ping_group_range
sysctl parameter to allow unprivileged ICMP sockets. Check with:sysctl net.ipv4.ping_group_range
- macOS: Works with unprivileged sockets by default
§Examples
use ping_async::IcmpEchoRequestor;
use std::net::IpAddr;
use std::time::Duration;
// Basic usage with defaults
let pinger = IcmpEchoRequestor::new(
"8.8.8.8".parse().unwrap(),
None,
None,
None
)?;
// With custom source address and timeout
let pinger = IcmpEchoRequestor::new(
"2001:4860:4860::8888".parse().unwrap(),
Some("::1".parse().unwrap()),
Some(64),
Some(Duration::from_millis(500))
)?;
Sourcepub async fn send(&self) -> Result<IcmpEchoReply>
pub async fn send(&self) -> Result<IcmpEchoReply>
Sends an ICMP echo request and waits for a reply.
This method is async and will complete when either:
- An echo reply is received
- The configured timeout expires
- An error occurs
The requestor uses lazy initialization - the background reply router task
is only spawned on the first call to send()
. The requestor can be used
multiple times and is safe to use concurrently from multiple async tasks.
§Returns
Returns an IcmpEchoReply
containing:
- The destination IP address
- The status of the ping operation
- The measured round-trip time
§Errors
Returns an error if:
- The socket send operation fails immediately
- The background router task has failed (typically due to permission loss)
- Internal communication channels fail unexpectedly
Note that timeout and unreachable conditions are returned as successful
IcmpEchoReply
with appropriate status values, not as errors.
§Examples
use ping_async::{IcmpEchoRequestor, IcmpEchoStatus};
#[tokio::main]
async fn main() -> std::io::Result<()> {
let pinger = IcmpEchoRequestor::new(
"8.8.8.8".parse().unwrap(),
None, None, None
)?;
// Send multiple pings using the same requestor
for i in 0..3 {
let reply = pinger.send().await?;
match reply.status() {
IcmpEchoStatus::Success => {
println!("Ping {}: {:?}", i, reply.round_trip_time());
}
IcmpEchoStatus::TimedOut => {
println!("Ping {} timed out", i);
}
_ => {
println!("Ping {} failed: {:?}", i, reply.status());
}
}
}
Ok(())
}
Trait Implementations§
Source§impl Clone for IcmpEchoRequestor
impl Clone for IcmpEchoRequestor
Source§fn clone(&self) -> IcmpEchoRequestor
fn clone(&self) -> IcmpEchoRequestor
1.0.0 · Source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read more