Debian Codegraph @

upstream/debian-unstable/man3/CPAN::Mirrors.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "CPAN::Mirrors 3perl"
58 .TH CPAN::Mirrors 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 CPAN::Mirrors \- Get CPAN mirror information and select a fast one
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 1
68 \& use CPAN::Mirrors;
69 \&
70 \& my $mirrors = CPAN::Mirrors\->new( $mirrored_by_file );
71 \&
72 \& my $seen = {};
73 \&
74 \& my $best_continent = $mirrors\->find_best_continents( { seen => $seen } );
75 \& my @mirrors = $mirrors\->get_mirrors_by_continents( $best_continent );
76 \&
77 \& my $callback = sub {
78 \& my( $m ) = @_;
79 \& printf "%s = %s\en", $m\->hostname, $m\->rtt
80 \& };
81 \& $mirrors\->get_mirrors_timings( \e@mirrors, $seen, $callback, %args );
82 \&
83 \& @mirrors = sort { $a\->rtt <=> $b\->rtt } @mirrors;
84 \&
85 \& print "Best mirrors are ", map( { $_\->rtt } @mirrors[0..3] ), "\en";
86 .Ve
87 .SH DESCRIPTION
88 .IX Header "DESCRIPTION"
89 .IP "new( LOCAL_FILE_NAME )" 4
90 .IX Item "new( LOCAL_FILE_NAME )"
91 Create a new CPAN::Mirrors object from LOCAL_FILE_NAME. This file
92 should look like that in http://www.cpan.org/MIRRORED.BY .
93 .IP \fBcontinents()\fR 4
94 .IX Item "continents()"
95 Return a list of continents based on those defined in \fIMIRRORED.BY\fR.
96 .IP "countries( [CONTINENTS] )" 4
97 .IX Item "countries( [CONTINENTS] )"
98 Return a list of countries based on those defined in \fIMIRRORED.BY\fR.
99 It only returns countries for the continents you specify (as defined
100 in \f(CW\*(C`continents\*(C'\fR). If you don't specify any continents, it returns all
101 of the countries listed in \fIMIRRORED.BY\fR.
102 .IP "mirrors( [COUNTRIES] )" 4
103 .IX Item "mirrors( [COUNTRIES] )"
104 Return a list of mirrors based on those defined in \fIMIRRORED.BY\fR.
105 It only returns mirrors for the countries you specify (as defined
106 in \f(CW\*(C`countries\*(C'\fR). If you don't specify any countries, it returns all
107 of the mirrors listed in \fIMIRRORED.BY\fR.
108 .IP "get_mirrors_by_countries( [COUNTRIES] )" 4
109 .IX Item "get_mirrors_by_countries( [COUNTRIES] )"
110 A more sensible synonym for mirrors.
111 .IP "get_mirrors_by_continents( [CONTINENTS] )" 4
112 .IX Item "get_mirrors_by_continents( [CONTINENTS] )"
113 Return a list of mirrors for all of continents you specify. If you don't
114 specify any continents, it returns all of the mirrors.
115 .Sp
116 You can specify a single continent or an array reference of continents.
117 .IP "get_countries_by_continents( [CONTINENTS] )" 4
118 .IX Item "get_countries_by_continents( [CONTINENTS] )"
119 A more sensible synonym for countries.
120 .IP default_mirror 4
121 .IX Item "default_mirror"
122 Returns the default mirror, http://www.cpan.org/ . This mirror uses
123 dynamic DNS to give a close mirror.
124 .IP best_mirrors 4
125 .IX Item "best_mirrors"
126 \&\f(CW\*(C`best_mirrors\*(C'\fR checks for the best mirrors based on the list of
127 continents you pass, or, without that, all continents, as defined
128 by \f(CW\*(C`CPAN::Mirrored::By\*(C'\fR. It pings each mirror, up to the value of
129 \&\f(CW\*(C`how_many\*(C'\fR. In list context, it returns up to \f(CW\*(C`how_many\*(C'\fR mirrors.
130 In scalar context, it returns the single best mirror.
131 .Sp
132 Arguments
133 .Sp
134 .Vb 5
135 \& how_many \- the number of mirrors to return. Default: 1
136 \& callback \- a callback for find_best_continents
137 \& verbose \- true or false on all the whining and moaning. Default: false
138 \& continents \- an array ref of the continents to check
139 \& external_ping \- if true, use external ping via Net::Ping::External. Default: false
140 .Ve
141 .Sp
142 If you don't specify the continents, \f(CW\*(C`best_mirrors\*(C'\fR calls
143 \&\f(CW\*(C`find_best_continents\*(C'\fR to get the list of continents to check.
144 .Sp
145 If you don't have Net::Ping v2.13 or later, needed for timings,
146 this returns the default mirror.
147 .Sp
148 \&\f(CW\*(C`external_ping\*(C'\fR should be set and then \f(CW\*(C`Net::Ping::External\*(C'\fR needs
149 to be installed, if the local network has a transparent proxy.
150 .IP "get_n_random_mirrors_by_continents( N, [CONTINENTS] )" 4
151 .IX Item "get_n_random_mirrors_by_continents( N, [CONTINENTS] )"
152 Returns up to N random mirrors for the specified continents. Specify the
153 continents as an array reference.
154 .ie n .IP "get_mirrors_timings( MIRROR_LIST, SEEN, CALLBACK, %ARGS );" 4
155 .el .IP "get_mirrors_timings( MIRROR_LIST, SEEN, CALLBACK, \f(CW%ARGS\fR );" 4
156 .IX Item "get_mirrors_timings( MIRROR_LIST, SEEN, CALLBACK, %ARGS );"
157 Pings the listed mirrors and returns a list of mirrors sorted in
158 ascending ping times.
159 .Sp
160 \&\f(CW\*(C`MIRROR_LIST\*(C'\fR is an anonymous array of \f(CW\*(C`CPAN::Mirrored::By\*(C'\fR objects to
161 ping.
162 .Sp
163 The optional argument \f(CW\*(C`SEEN\*(C'\fR is a hash reference used to track the
164 mirrors you've already pinged.
165 .Sp
166 The optional argument \f(CW\*(C`CALLBACK\*(C'\fR is a subroutine reference to call
167 after each ping. It gets the \f(CW\*(C`CPAN::Mirrored::By\*(C'\fR object after each
168 ping.
169 .IP "find_best_continents( HASH_REF );" 4
170 .IX Item "find_best_continents( HASH_REF );"
171 \&\f(CW\*(C`find_best_continents\*(C'\fR goes through each continent and pings \f(CW\*(C`N\*(C'\fR
172 random mirrors on that continent. It then orders the continents by
173 ascending median ping time. In list context, it returns the ordered list
174 of continent. In scalar context, it returns the same list as an
175 anonymous array.
176 .Sp
177 Arguments:
178 .Sp
179 .Vb 6
180 \& n \- the number of hosts to ping for each continent. Default: 3
181 \& seen \- a hashref of cached hostname ping times
182 \& verbose \- true or false for noisy or quiet. Default: false
183 \& callback \- a subroutine to run after each ping.
184 \& ping_cache_limit \- how long, in seconds, to reuse previous ping times.
185 \& Default: 1 day
186 .Ve
187 .Sp
188 The \f(CW\*(C`seen\*(C'\fR hash has hostnames as keys and anonymous arrays as values.
189 The anonymous array is a triplet of a \f(CW\*(C`CPAN::Mirrored::By\*(C'\fR object, a
190 ping time, and the epoch time for the measurement.
191 .Sp
192 The callback subroutine gets the \f(CW\*(C`CPAN::Mirrored::By\*(C'\fR object, the ping
193 time, and measurement time (the same things in the \f(CW\*(C`seen\*(C'\fR hashref) as
194 arguments. \f(CW\*(C`find_best_continents\*(C'\fR doesn't care what the callback does
195 and ignores the return value.
196 .Sp
197 With a low value for \f(CW\*(C`N\*(C'\fR, a single mirror might skew the results enough
198 to choose a worse continent. If you have that problem, try a larger
199 value.
200 .SH AUTHOR
201 .IX Header "AUTHOR"
202 Andreas Koenig \f(CW\*(C`<[email protected]>\*(C'\fR, David Golden \f(CW\*(C`<[email protected]>\*(C'\fR,
203 brian d foy \f(CW\*(C`<[email protected]>\*(C'\fR
204 .SH LICENSE
205 .IX Header "LICENSE"
206 This program is free software; you can redistribute it and/or
207 modify it under the same terms as Perl itself.
208 .PP
209 See <http://www.perl.com/perl/misc/Artistic.html>