Debian Codegraph @

upstream/mageia-cauldron/man3pm/CPAN::Mirrors.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (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 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "CPAN::Mirrors 3pm"
61 .TH CPAN::Mirrors 3pm 2023-12-22 "perl v5.42.0" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 CPAN::Mirrors \- Get CPAN mirror information and select a fast one
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& use CPAN::Mirrors;
72 \&
73 \& my $mirrors = CPAN::Mirrors\->new( $mirrored_by_file );
74 \&
75 \& my $seen = {};
76 \&
77 \& my $best_continent = $mirrors\->find_best_continents( { seen => $seen } );
78 \& my @mirrors = $mirrors\->get_mirrors_by_continents( $best_continent );
79 \&
80 \& my $callback = sub {
81 \& my( $m ) = @_;
82 \& printf "%s = %s\en", $m\->hostname, $m\->rtt
83 \& };
84 \& $mirrors\->get_mirrors_timings( \e@mirrors, $seen, $callback, %args );
85 \&
86 \& @mirrors = sort { $a\->rtt <=> $b\->rtt } @mirrors;
87 \&
88 \& print "Best mirrors are ", map( { $_\->rtt } @mirrors[0..3] ), "\en";
89 .Ve
90 .SH DESCRIPTION
91 .IX Header "DESCRIPTION"
92 .IP "new( LOCAL_FILE_NAME )" 4
93 .IX Item "new( LOCAL_FILE_NAME )"
94 Create a new CPAN::Mirrors object from LOCAL_FILE_NAME. This file
95 should look like that in http://www.cpan.org/MIRRORED.BY .
96 .IP \fBcontinents()\fR 4
97 .IX Item "continents()"
98 Return a list of continents based on those defined in \fIMIRRORED.BY\fR.
99 .IP "countries( [CONTINENTS] )" 4
100 .IX Item "countries( [CONTINENTS] )"
101 Return a list of countries based on those defined in \fIMIRRORED.BY\fR.
102 It only returns countries for the continents you specify (as defined
103 in \f(CW\*(C`continents\*(C'\fR). If you don\*(Aqt specify any continents, it returns all
104 of the countries listed in \fIMIRRORED.BY\fR.
105 .IP "mirrors( [COUNTRIES] )" 4
106 .IX Item "mirrors( [COUNTRIES] )"
107 Return a list of mirrors based on those defined in \fIMIRRORED.BY\fR.
108 It only returns mirrors for the countries you specify (as defined
109 in \f(CW\*(C`countries\*(C'\fR). If you don\*(Aqt specify any countries, it returns all
110 of the mirrors listed in \fIMIRRORED.BY\fR.
111 .IP "get_mirrors_by_countries( [COUNTRIES] )" 4
112 .IX Item "get_mirrors_by_countries( [COUNTRIES] )"
113 A more sensible synonym for mirrors.
114 .IP "get_mirrors_by_continents( [CONTINENTS] )" 4
115 .IX Item "get_mirrors_by_continents( [CONTINENTS] )"
116 Return a list of mirrors for all of continents you specify. If you don\*(Aqt
117 specify any continents, it returns all of the mirrors.
118 .Sp
119 You can specify a single continent or an array reference of continents.
120 .IP "get_countries_by_continents( [CONTINENTS] )" 4
121 .IX Item "get_countries_by_continents( [CONTINENTS] )"
122 A more sensible synonym for countries.
123 .IP default_mirror 4
124 .IX Item "default_mirror"
125 Returns the default mirror, http://www.cpan.org/ . This mirror uses
126 dynamic DNS to give a close mirror.
127 .IP best_mirrors 4
128 .IX Item "best_mirrors"
129 \&\f(CW\*(C`best_mirrors\*(C'\fR checks for the best mirrors based on the list of
130 continents you pass, or, without that, all continents, as defined
131 by \f(CW\*(C`CPAN::Mirrored::By\*(C'\fR. It pings each mirror, up to the value of
132 \&\f(CW\*(C`how_many\*(C'\fR. In list context, it returns up to \f(CW\*(C`how_many\*(C'\fR mirrors.
133 In scalar context, it returns the single best mirror.
134 .Sp
135 Arguments
136 .Sp
137 .Vb 5
138 \& how_many \- the number of mirrors to return. Default: 1
139 \& callback \- a callback for find_best_continents
140 \& verbose \- true or false on all the whining and moaning. Default: false
141 \& continents \- an array ref of the continents to check
142 \& external_ping \- if true, use external ping via Net::Ping::External. Default: false
143 .Ve
144 .Sp
145 If you don\*(Aqt specify the continents, \f(CW\*(C`best_mirrors\*(C'\fR calls
146 \&\f(CW\*(C`find_best_continents\*(C'\fR to get the list of continents to check.
147 .Sp
148 If you don\*(Aqt have Net::Ping v2.13 or later, needed for timings,
149 this returns the default mirror.
150 .Sp
151 \&\f(CW\*(C`external_ping\*(C'\fR should be set and then \f(CW\*(C`Net::Ping::External\*(C'\fR needs
152 to be installed, if the local network has a transparent proxy.
153 .IP "get_n_random_mirrors_by_continents( N, [CONTINENTS] )" 4
154 .IX Item "get_n_random_mirrors_by_continents( N, [CONTINENTS] )"
155 Returns up to N random mirrors for the specified continents. Specify the
156 continents as an array reference.
157 .ie n .IP "get_mirrors_timings( MIRROR_LIST, SEEN, CALLBACK, %ARGS );" 4
158 .el .IP "get_mirrors_timings( MIRROR_LIST, SEEN, CALLBACK, \f(CW%ARGS\fR );" 4
159 .IX Item "get_mirrors_timings( MIRROR_LIST, SEEN, CALLBACK, %ARGS );"
160 Pings the listed mirrors and returns a list of mirrors sorted in
161 ascending ping times.
162 .Sp
163 \&\f(CW\*(C`MIRROR_LIST\*(C'\fR is an anonymous array of \f(CW\*(C`CPAN::Mirrored::By\*(C'\fR objects to
164 ping.
165 .Sp
166 The optional argument \f(CW\*(C`SEEN\*(C'\fR is a hash reference used to track the
167 mirrors you\*(Aqve already pinged.
168 .Sp
169 The optional argument \f(CW\*(C`CALLBACK\*(C'\fR is a subroutine reference to call
170 after each ping. It gets the \f(CW\*(C`CPAN::Mirrored::By\*(C'\fR object after each
171 ping.
172 .IP "find_best_continents( HASH_REF );" 4
173 .IX Item "find_best_continents( HASH_REF );"
174 \&\f(CW\*(C`find_best_continents\*(C'\fR goes through each continent and pings \f(CW\*(C`N\*(C'\fR
175 random mirrors on that continent. It then orders the continents by
176 ascending median ping time. In list context, it returns the ordered list
177 of continent. In scalar context, it returns the same list as an
178 anonymous array.
179 .Sp
180 Arguments:
181 .Sp
182 .Vb 6
183 \& n \- the number of hosts to ping for each continent. Default: 3
184 \& seen \- a hashref of cached hostname ping times
185 \& verbose \- true or false for noisy or quiet. Default: false
186 \& callback \- a subroutine to run after each ping.
187 \& ping_cache_limit \- how long, in seconds, to reuse previous ping times.
188 \& Default: 1 day
189 .Ve
190 .Sp
191 The \f(CW\*(C`seen\*(C'\fR hash has hostnames as keys and anonymous arrays as values.
192 The anonymous array is a triplet of a \f(CW\*(C`CPAN::Mirrored::By\*(C'\fR object, a
193 ping time, and the epoch time for the measurement.
194 .Sp
195 The callback subroutine gets the \f(CW\*(C`CPAN::Mirrored::By\*(C'\fR object, the ping
196 time, and measurement time (the same things in the \f(CW\*(C`seen\*(C'\fR hashref) as
197 arguments. \f(CW\*(C`find_best_continents\*(C'\fR doesn\*(Aqt care what the callback does
198 and ignores the return value.
199 .Sp
200 With a low value for \f(CW\*(C`N\*(C'\fR, a single mirror might skew the results enough
201 to choose a worse continent. If you have that problem, try a larger
202 value.
203 .SH AUTHOR
204 .IX Header "AUTHOR"
205 Andreas Koenig \f(CW\*(C`<[email protected]>\*(C'\fR, David Golden \f(CW\*(C`<[email protected]>\*(C'\fR,
206 brian d foy \f(CW\*(C`<[email protected]>\*(C'\fR
207 .SH LICENSE
208 .IX Header "LICENSE"
209 This program is free software; you can redistribute it and/or
210 modify it under the same terms as Perl itself.
211 .PP
212 See <http://www.perl.com/perl/misc/Artistic.html>