CPAN::Mirrors(3pm)

📦
version 5.42.3 · 8 versions
, in alpine 3.24

okay so this is CPAN::Mirrors(3pm) straight out of the Perl Programmers Reference Guide, and yes bestie it's giving "official documentation but make it make sense" energy 💅

🎀 NAME 🎀

CPAN::Mirrors — Get CPAN mirror information and select a fast one. literally that's the whole job. it gets mirror info and picks a speedy one. iconic of it honestly ✨

🦋 SYNOPSIS 🦋

here's the whole vibe start to finish, no notes:

    use CPAN::Mirrors;

    my $mirrors = CPAN::Mirrors->new( $mirrored_by_file );

    my $seen = {};

    my $best_continent = $mirrors->find_best_continents( { seen => $seen } );
    my @mirrors        = $mirrors->get_mirrors_by_continents( $best_continent );

    my $callback = sub {
        my( $m ) = @_;
        printf "%s = %s\n", $m->hostname, $m->rtt
        };
    $mirrors->get_mirrors_timings( \@mirrors, $seen, $callback, %args );

    @mirrors = sort { $a->rtt <=> $b->rtt } @mirrors;

    print "Best mirrors are ", map( { $_->rtt } @mirrors[0..3] ), "\n";

like... look at her go 🫶

✨ DESCRIPTION ✨

💖 new( LOCAL_FILE_NAME )

Makes you a brand new CPAN::Mirrors object out of LOCAL_FILE_NAME. that file should look exactly like the one at http://www.cpan.org/MIRRORED.BY — that's the blueprint, don't deviate, mwah 🎀

💖 continents()

Returns a list of continents, based on the ones defined in MIRRORED.BY. simple. clean. no cap.

💖 countries( [CONTINENTS] )

Returns a list of countries, based on the ones defined in MIRRORED.BY. she only gives you countries for the continents you actually specify (as defined in "continents"). and if you don't specify any continents? she returns all the countries listed in MIRRORED.BY. generous queen 🌸

💖 mirrors( [COUNTRIES] )

Returns a list of mirrors based on the ones defined in MIRRORED.BY. only returns mirrors for the countries you specify (as defined in "countries"). if you don't specify any countries, you get all the mirrors listed in MIRRORED.BY. the whole buffet. 🔥

💖 get_mirrors_by_countries( [COUNTRIES] )

A more sensible synonym for mirrors. that's it, that's the whole thing. she said "let me name this properly" 💅

💖 get_mirrors_by_continents( [CONTINENTS] )

Returns a list of mirrors for all of the continents you specify. if you don't specify any continents, she returns all of the mirrors. all of them. every last one. 👑

You can specify a single continent or an array reference of continents — either works, she's flexible like that.

💖 get_countries_by_continents( [CONTINENTS] )

A more sensible synonym for countries. again: better name, same energy. 🎀

💖 default_mirror

Returns the default mirror, http://www.cpan.org/. this mirror uses dynamic DNS to give you a close mirror, which is lowkey genius of it.

💖 best_mirrors

"best_mirrors" checks for the best mirrors based on the list of continents you pass — or, if you don't pass any, all continents, as defined by "CPAN::Mirrored::By". it pings each mirror, up to the value of "how_many". in list context it returns up to "how_many" mirrors. in scalar context it returns the single best mirror. main character energy only 😌

Arguments

  • how_many — the number of mirrors to return. Default: 1
  • callback — a callback for find_best_continents
  • verbose — true or false on all the whining and moaning. Default: false
  • continents — an array ref of the continents to check
  • external_ping — if true, use external ping via Net::Ping::External. Default: false

If you don't specify the continents, "best_mirrors" calls "find_best_continents" to get the list of continents to check. she's not gonna guess, she's gonna go find out 🧚

⚠️ If you don't have Net::Ping v2.13 or later — which is what timings need — this returns the default mirror. so like, no fancy ping for you, you get the standard one. 💀
⚠️ "external_ping" should be set, and then "Net::Ping::External" needs to be installed, if the local network has a transparent proxy. don't skip this, fr fr 🙈

💖 get_n_random_mirrors_by_continents( N, [CONTINENTS] )

Returns up to N random mirrors for the specified continents. you specify the continents as an array reference. random but make it continental 🎲

💖 get_mirrors_timings( MIRROR_LIST, SEEN, CALLBACK, %ARGS );

Pings the listed mirrors and returns a list of mirrors sorted in ascending ping times. fastest first, obviously, we're not waiting around 💨

  • "MIRROR_LIST" is an anonymous array of "CPAN::Mirrored::By" objects to ping.
  • The optional argument "SEEN" is a hash reference used to track the mirrors you've already pinged. so you don't double-ping, we're not doing that here.
  • The optional argument "CALLBACK" is a subroutine reference to call after each ping. it gets the "CPAN::Mirrored::By" object after each ping.

💖 find_best_continents( HASH_REF );

"find_best_continents" goes through each continent and pings N random mirrors on that continent. then she orders the continents by ascending median ping time. in list context, it returns the ordered list of continent. in scalar context, it returns the same list as an anonymous array. same data, different outfit 💅

Arguments

  • n — the number of hosts to ping for each continent. Default: 3
  • seen — a hashref of cached hostname ping times
  • verbose — true or false for noisy or quiet. Default: false
  • callback — a subroutine to run after each ping.
  • ping_cache_limit — how long, in seconds, to reuse previous ping times. Default: 1 day

The "seen" hash has hostnames as keys and anonymous arrays as values. that anonymous array is a triplet of a "CPAN::Mirrored::By" object, a ping time, and the epoch time for the measurement. trio! 🍓

The callback subroutine gets the "CPAN::Mirrored::By" object, the ping time, and measurement time (the same things in the "seen" hashref) as arguments. "find_best_continents" doesn't care what the callback does and ignores the return value. she is unbothered, moisturized, in her lane 😭

🫶 heads up bestie: with a low value for "N", a single mirror might skew the results enough to choose a worse continent. if you have that problem, try a larger value. like, don't let one weird mirror ruin the whole selection, ok?

🌈 AUTHOR 🌈

Andreas Koenig "<andk@cpan.org>", David Golden "<dagolden@cpan.org>", brian d foy "<bdfoy@cpan.org>" — the trio behind the whole thing. legends, honestly 👑

⭐ LICENSE ⭐

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

See <http://www.perl.com/perl/misc/Artistic.html> — go read it, it's the receipts. 📜

and that's the page!! this was perl v5.42.3, dated 2026-11-03, living in the Perl Programmers Reference Guide — ty for coming to my TED talk, ily, go pick a fast mirror 💜🦋✨

📦 where this page comes from