.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Games::FrozenBubble::NetDiscover 3pm"
.TH Games::FrozenBubble::NetDiscover 3pm "2018-11-02" "perl v5.28.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "Frozen-Bubble"
.IX Header "Frozen-Bubble"
Copyright X 2010 The Frozen-Bubble Team
.PP
This program is free software; you can redistribute it and/or modify
it under the terms of the \s-1GNU\s0 General Public License version 2, as
published by the Free Software Foundation.
.PP
This program is distributed in the hope that it will be useful,
but \s-1WITHOUT ANY WARRANTY\s0; without even the implied warranty of
\&\s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A PARTICULAR PURPOSE.\s0  See the
\&\s-1GNU\s0 General Public License for more details.
.PP
You should have received a copy of the \s-1GNU\s0 General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place \- Suite 330, Boston, \s-1MA 02111\-1307, USA.\s0
.SH "NAME"
Games::FrozenBubble::NetDiscover \- high performance server discovery plugin for frozen bubble
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 10
\&    my $discover = Games::FrozenBubble::NetDiscover\->new(
\&        { host => "1.2.3.4", port => 1511 },
\&        { host => "5.6.7.8", port => 1512 }, ...);
\&    while($discover\->pending()) {
\&        my @servers = $discover\->found();
\&        for(my $server = 0; $server < @servers; $server++) {
\&            printf("%02i: ip %s ping %i\en",
\&                $server, $servers[$server]{ip}, $servers[$server]{ping});
\&        }
\&        $discover\->work(0.1); # sit in a select loop for 100ms
\&
\&        # update your screen, and all of that stuff, here.
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Games::FrozenBubble::NetDiscover checks a list of servers, finding their versions, ping times,
and number of current clients.  It uses nonblocking \s-1IO\s0 and select, to
connect to multiple servers in parallel, thus reducing the total amount of
time elapsed.  This, in turn, allows the user to begin playing frozen bubble
more quickly. :)
.PP
This module is designed to be called from a \s-1GUI\s0 loop.  It has to spend sit in
a select loop for most of its life in order to get accurate ping times, but
it will return back to your loop at intervals you specify, so you can check
for keystrokes and refresh the screen and so forth.
.PP
In order to get consistent results on slow dialup links, this module will only
attempt to connect to one server per each 200ms.  This means for 18 servers
that there are 3.4 seconds of extra guaranteed lag, but it also means packets
from multiple servers are less likely to bump into eachother in the queue, so
ping reply times will be more reliable.
.PP
In the source script, there are two configuration parameters: \f(CW$number_of_pings\fR
and \f(CW$time_between_connections\fR.  These are set to 2 and 0.2, respectively.
These two parameters will determine the amount of bandwidth used, and the
amount of time taken before the user can select a server.  Assuming the user's
internet connection can handle the traffic without extra latency from queueing
or retransmissions, the worst case latency will be, in seconds:
.PP
.Vb 1
\&    N*L + T*(S\-1)
.Ve
.PP
where
.PP
.Vb 4
\&    N = $number_of_pings
\&    L = the roundtrip time of the slowest server in the list, in seconds
\&    T = $time_between_connections
\&    S = the number of servers in the list
.Ve
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.Vb 1
\&    ...\->new ({host => "server1", port => port}, {host => "server2", port => port}, ...)
.Ve
.PP
Takes a list of servers as arguments.  Each server argument should be a hash
reference, consisting of {host => host, port => port}.  Returns a
Games::FrozenBubble::NetDiscover object, which can be used within a \s-1GUI\s0 loop to discover all of
your servers.
.PP
The host string should ideally be an \s-1IP\s0 address.  A hostname string should work
too, but \s-1DNS\s0 lookups will introduce extra, unpredictable latency later on.
.SH "METHODS"
.IX Header "METHODS"
These methods define the public \s-1API\s0 for instances of this class.
.SS "found"
.IX Subsection "found"
Returns a list of 0 or more servers found.  Each return value is a hash
reference, containing the following keys:
.PP
.Vb 12
\&    host: the IP address of the server
\&    port: the TCP port of the server
\&    pingtimes: array reference, contains the actual result times of 4 pings
\&    ping: the average roundtrip latency of the server, in ms
\&    freenicks: the list of players connected
\&    freegames: the list of open games (not yet started)
\&    free: the number of idle clients connected to this server
\&    games: the number of clients connected to this server, who are playing games
\&    playing: the list of players in games
\&    geolocs: the geolocations of players in games
\&    name: the self\-proclaimed "name" reported by the server
\&    language: the preferred language reported by the server
.Ve
.SS "pending"
.IX Subsection "pending"
Returns non-zero if we are still waiting for a response from one or more
servers; returns 0 if processing is complete.
.SS "work(seconds)"
.IX Subsection "work(seconds)"
Enters the main loop of this module.  This method requires one argument, a
numeric count of seconds to work for.  This is expected to be a floating point
decimal, for sub-second precision.  Returns the number of servers pending, just
like the pending method does.
.SH "INTERNAL METHODS"
.IX Header "INTERNAL METHODS"
These methods are only meant to be called from within the module.  They are
subject to change without notice.
.SS "try_connect"
.IX Subsection "try_connect"
Attempts to connect to a server.  Moves the first \*(L"not_started\*(R" server to the
\&\*(L"pending\*(R" list, and creates a non-blocking IO::Socket::INET object for it.
Updates the begin_time timestamp, to determine when the next server should be
connected.
.SS "server_sm(connection_number)"
.IX Subsection "server_sm(connection_number)"
Implements a simple state machine.  Called with an index into the pending
array, to indicate that data is available for reading from this server.
.SS "give_up_on(connection_number, reason)"
.IX Subsection "give_up_on(connection_number, reason)"
Called if select reports a socket as has_exception.  Also called if the
server has a bogus version, times out, or we can't parse the \s-1IP\s0 address or
something.  Removes the entry from further processing, and emits an error
message on stderr.
.SH "EXPORT"
.IX Header "EXPORT"
None.
.SH "BUGS"
.IX Header "BUGS"
implement some sort of timeout, for servers which don't respond within 5 seconds.
.SH "AUTHOR"
.IX Header "AUTHOR"
Mark Glines, <mark@glines.org>.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This code is donated to the frozen bubble project, www.frozen\-bubble.org, so
they can do whatever they want with it.  Copyright is therefore assigned to
those guys.