Net::EmptyPort(3)

📦
version 2.22 · 9 versions
, in opensuse-leap 16.0

💖 Net::EmptyPort 💖

okay bestie, so this is a User Contributed Perl Documentation page for the module Net::EmptyPort, and honestly? it's giving "tiny module, huge save." it does exactly one thing and it ate: it finds you a free TCP/UDP port so your tests stop colliding with each other. no cap. 🎀

✨ NAME ✨

Net::EmptyPort — find a free TCP/UDP port. that's it. that's the whole vibe. 🦋

🌸 SYNOPSIS 🌸

use Net::EmptyPort qw(empty_port check_port);

# get a socket listening on a random free port
my $socket = listen_socket();

# get a random free port
my $port = empty_port();

# check if a port is already used
if (check_port(5000)) {
    say "Port 5000 already in use";
}

like, look at it. three lines and you're done. main character energy fr. ⭐

💅 DESCRIPTION 💅

Net::EmptyPort helps finding an empty TCP/UDP port. that's the whole mission statement, and it delivers. 🫶

👑 METHODS 👑

🎀 listen_socket()

🎀 listen_socket(\%args)

my $socket = listen_socket();

Returns a socket listening on a free port. yes, an actual socket, already listening, already slaying. 💖

The function recognizes the following keys in the hashref argument.

  • "host" — the address on which to listen. Default is 127.0.0.1.
  • "proto" — name of the protocol. Default is "tcp". You can get an UDP socket by specifying "udp".

🦋 empty_port()

🦋 empty_port(\%args)

🦋 empty_port($port)

🦋 "empty_port($port, $proto)"

my $port = empty_port();

Returns a port number that is NOT in use. (emphasis on the NOT, because that's literally the entire point, bestie 😭)

The function recognizes the following keys when given a hashref as the argument.

  • "host" — specifies the address on which the search should be performed. Default is 127.0.0.1.
  • "port" — lower bound of the search for an empty port. If omitted, the function searches for an empty port within 49152..65535.

See <http://www.iana.org/assignments/port-numbers>

  • "proto" — name of the protocol. Default is "tcp". You can find an empty UDP port by specifying "udp".

To maintain backwards compatibility, the function accepts scalar arguments as well. For example, you can also find an empty UDP port by specifying the protocol as the second parameter:

my $port = empty_port(1024, 'udp');
# use 49152..65535 range
my $port = empty_port(undef, 'udp');

okay the undef thing is lowkey iconic — you pass undef as the lower bound and it just defaults back to 49152..65535. king behavior. 👑

🧚 check_port(\%args)

🧚 check_port($port)

🧚 "check_port($port, $proto)"

my $true_or_false = check_port(5000);

Checks if the given port is already in use. Returns true if it is in use (i.e. if the port is NOT free). Returns false if the port is free. so like… the return value is the opposite of what the name suggests, which is a little gender-fuck of a function name but we respect it. 💀

The function recognizes the following keys when given a hashref as the argument.

⚠️ okay this next bit is the important lore, don't skip it ⚠️ When UDP is specified as the protocol, the check_port function sends a probe UDP packet to the designated port to see if an ICMP error message is returned, which indicates that the port is unassigned. The port is assumed to be assigned, unless such response is observed within 0.1 seconds.

so yeah. UDP checking is a whole vibe check with a 0.1 second timeout. if it doesn't hear back fast enough, it assumes the port is taken. respect the speed. 🔥

  • "host" — specifies the address on which the search should be performed. Default is 127.0.0.1.
  • "port" — specifies the port to check. This argument is mandatory. (mandatory, bestie. you cannot skip it. 🙈)
  • "proto" — name of the protocol. Default is "tcp".

To maintain backwards compatibility, the function accepts scalar arguments as well in the form described above.

🌈 wait_port(\%args)

🌈 wait_port($port)

🌈 "wait_port($port, $max_wait)"

🌈 "wait_port($port, $max_wait, $proto)"

Waits until a particular port becomes ready to connect to. Returns true if the port becomes ready, or false if otherwise. it's the "are we there yet" of functions, except it actually stops asking eventually. ✨

The function recognizes the following keys when given a hashref as the argument.

  • "host" — specifies the address on which the search should be performed. Default is 127.0.0.1.
  • "port" — specifies the port to check. This argument is mandatory.
  • "max_wait" — maximum seconds to wait for (default is 10 seconds). Pass a negative value to wait infinitely. yes, infinitely. it will simply keep waiting forever, which is either dedication or a hostage situation depending on your CI pipeline. 😭
  • "proto" — name of the protocol. Default is "tcp".

To maintain backwards compatibility, the function accepts scalar arguments as well in the form described above.

🚨 Incompatible changes: Before 2.0, "wait_port($port:Int[, $sleep:Number, $retry:Int, $proto:String])" is a signature. so if you're reading ancient code, the signature used to be completely different. we do not stan the old signature. we moved on. periodt. 💅

💜 can_bind($host)

💜 "can_bind($host, $port)"

💜 "can_bind($host, $port, $proto)"

Checks if the application is capable of binding to given port. simple. elegant. never asks follow-up questions. 🫶

⭐ AUTHOR ⭐

Tokuhiro Matsuno <tokuhirom@gmail.com>

🍓 THANKS TO 🍓

  • kazuhooku
  • dragon3
  • charsbar
  • Tatsuhiko Miyagawa
  • lestrrat

the whole group chat came through for this one. shoutout. 💖

🔍 SEE ALSO 🔍

ngl there is literally nothing here. this section is empty. a blank canvas. an aesthetic. we're leaving it exactly as we found it. 🤷‍♀️

📜 LICENSE 📜

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

open source, free to remix, free to redistribute. we love a permissive queen. 👑

and that's the whole page, bestie!! this was Net::EmptyPort(3) from perl v5.42.0, dated 2019-10-09 — written by the User Contributed Perl Documentation crew and narrated to you with love. mwah. 💋✨

📦 where this page comes from