AnyEven...xt::Ping(3)

💖 NAME 💖

AnyEvent::XMPP::Ext::Ping — literally the implementation of XMPP Ping XEP-0199, bestie. That's it, that's the whole vibe. It lives in the User Contributed Perl Documentation corner of the man-page universe ✨

---

🌸 SYNOPSIS 🌸

use AnyEvent::XMPP::Ext::Ping;

my $con = AnyEvent::XMPP::IM::Connection->new (...);
$con->add_extension (my $ping = AnyEvent::XMPP::Ext::Ping->new);

# this enables auto-timeout of a connection if it didn't answer
# within 120 seconds to a ping with a reply
$ping->enable_timeout ($con, 120);

my $cl = AnyEvent::XMPP::Client->new (...);
$cl->add_extension (my $ping = AnyEvent::XMPP::Ext::Ping->new);

# this enables auto-timeout of newly created connections
$ping->auto_timeout (120);

$ping->ping ($con, 'ping_dest@server.tld', sub {
   my ($time, $error) = @_;
   if ($error) {
      # we got an error
   }
   # $time is a float (seconds) of the rtt if you got Time::HiRes
});

No cap, that's the whole program right there 🫶

---

🦋 DESCRIPTION 🦋

okay so this extension implements XEP-0199: XMPP Ping. It gives you the power to define an automatic ping timeouter that will disconnect dead connections — like, the ones that ghosted you and didn't reply to a ping after N seconds 😭. See also the docs for the enable_timeout method below, mwah 💋

It also lets you send pings to literally any XMPP entity you want, and it'll measure how long it took — if you got Time::HiRes. If you don't... it's giving undef energy, we'll get to that 💀

---

🎀 METHODS 🎀

⭐ new (%args)

Creates a new ping handle. Fresh ping handle, main character energy 👑

🔥 auto_timeout ($timeout)

This one enables automatic connection timeout of new connections. It calls enable_timeout (see below, bestie, keep reading 💅) for every new connection that was connected and emitted a stream_ready event.

Super useful if you want connections that have this extension to automatically be timeouted. Especially iconic with modules like AnyEvent::XMPP::Client (peep the SYNOPSIS above, it's right there 🌈).

💜 enable_timeout ($con, $timeout)

This enables a periodical ping on the connection $con. $timeout must be the seconds that the ping intervals last. Periodt ⏰

If the server connected via $con didn't respond within $timeout seconds, the connection $con will be disconnected. Bye bestie 👋💀

⚠️ ngl, heads up: there's already a basic timeout mechanism for dead TCP connections in AnyEvent::XMPP::Connection — see also the whitespace_ping_interval configuration variable for a connection there. It then will depend on TCP timeouts to disconnect the connection. So basically the low-key default is already doing stuff.

Use enable_timeout and auto_timeout only if you really feel like you need an explicit timeout for your connections. Like, fr fr, only if you're sure 🫶

❇️ ping ($con, $dest, $cb, $timeout)

This method sends a ping request to $dest via the AnyEvent::XMPP::Connection in $con. If $dest is undefined, the ping will be sent to the connected server (sending it to nobody in particular, iconic behaviour honestly). $cb gets called when either the ping timeouts, an error occurs, or the ping result was received. $timeout is an optional timeout for the ping request — if $timeout isn't given, the default IQ timeout for the connection is the relevant timeout. iykyk ✨

The first argument to $cb will be the seconds of the round trip time for that request (if you have Time::HiRes). If you don't have Time::HiRes installed, the first argument will be undef. Sad but true 😭

The second argument to $cb will be either undef if no error occured, or a AnyEvent::XMPP::Error::IQ error object. 🍓

🧚 ignore_pings ($bool)

This method is mostly for testing — it tells this extension to ignore all ping requests and will prevent any response from being sent. Screaming into the void, on purpose 🙈

---

👑 AUTHOR 👑

Robin Redeker, "<elmex at ta-sa.org>", JID: "<elmex at jabber.org>" — the legend themselves 💖

---

🌈 COPYRIGHT & LICENSE 🌈

Copyright 2007, 2008 Robin Redeker, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

and that's the whole page, bestie 💅 perl v5.42.2, dated 2026-02-15 — go forth and ping responsibly, ily, mwah 🎀💜🦋