1Games::FrozenBubble::NeUtsDeirscCoovnetrr(i3b)uted PerlGDaomceusm:e:nFtraotzieonnBubble::NetDiscover(3)
2
3
4

Frozen-Bubble

6       Copyright X 2010 The Frozen-Bubble Team
7
8       This program is free software; you can redistribute it and/or modify it
9       under the terms of the GNU General Public License version 2, as
10       published by the Free Software Foundation.
11
12       This program is distributed in the hope that it will be useful, but
13       WITHOUT ANY WARRANTY; without even the implied warranty of
14       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
15       General Public License for more details.
16
17       You should have received a copy of the GNU General Public License along
18       with this program; if not, write to the Free Software Foundation, Inc.,
19       59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
20

NAME

22       Games::FrozenBubble::NetDiscover - high performance server discovery
23       plugin for frozen bubble
24

SYNOPSIS

26           my $discover = Games::FrozenBubble::NetDiscover->new(
27               { host => "1.2.3.4", port => 1511 },
28               { host => "5.6.7.8", port => 1512 }, ...);
29           while($discover->pending()) {
30               my @servers = $discover->found();
31               for(my $server = 0; $server < @servers; $server++) {
32                   printf("%02i: ip %s ping %i\n",
33                       $server, $servers[$server]{ip}, $servers[$server]{ping});
34               }
35               $discover->work(0.1); # sit in a select loop for 100ms
36
37               # update your screen, and all of that stuff, here.
38           }
39

DESCRIPTION

41       Games::FrozenBubble::NetDiscover checks a list of servers, finding
42       their versions, ping times, and number of current clients.  It uses
43       nonblocking IO and select, to connect to multiple servers in parallel,
44       thus reducing the total amount of time elapsed.  This, in turn, allows
45       the user to begin playing frozen bubble more quickly. :)
46
47       This module is designed to be called from a GUI loop.  It has to spend
48       sit in a select loop for most of its life in order to get accurate ping
49       times, but it will return back to your loop at intervals you specify,
50       so you can check for keystrokes and refresh the screen and so forth.
51
52       In order to get consistent results on slow dialup links, this module
53       will only attempt to connect to one server per each 200ms.  This means
54       for 18 servers that there are 3.4 seconds of extra guaranteed lag, but
55       it also means packets from multiple servers are less likely to bump
56       into eachother in the queue, so ping reply times will be more reliable.
57
58       In the source script, there are two configuration parameters:
59       $number_of_pings and $time_between_connections.  These are set to 2 and
60       0.2, respectively.  These two parameters will determine the amount of
61       bandwidth used, and the amount of time taken before the user can select
62       a server.  Assuming the user's internet connection can handle the
63       traffic without extra latency from queueing or retransmissions, the
64       worst case latency will be, in seconds:
65
66           N*L + T*(S-1)
67
68       where
69
70           N = $number_of_pings
71           L = the roundtrip time of the slowest server in the list, in seconds
72           T = $time_between_connections
73           S = the number of servers in the list
74

CONSTRUCTOR

76           ...->new ({host => "server1", port => port}, {host => "server2", port => port}, ...)
77
78       Takes a list of servers as arguments.  Each server argument should be a
79       hash reference, consisting of {host => host, port => port}.  Returns a
80       Games::FrozenBubble::NetDiscover object, which can be used within a GUI
81       loop to discover all of your servers.
82
83       The host string should ideally be an IP address.  A hostname string
84       should work too, but DNS lookups will introduce extra, unpredictable
85       latency later on.
86

METHODS

88       These methods define the public API for instances of this class.
89
90   found
91       Returns a list of 0 or more servers found.  Each return value is a hash
92       reference, containing the following keys:
93
94           host: the IP address of the server
95           port: the TCP port of the server
96           pingtimes: array reference, contains the actual result times of 4 pings
97           ping: the average roundtrip latency of the server, in ms
98           freenicks: the list of players connected
99           freegames: the list of open games (not yet started)
100           free: the number of idle clients connected to this server
101           games: the number of clients connected to this server, who are playing games
102           playing: the list of players in games
103           geolocs: the geolocations of players in games
104           name: the self-proclaimed "name" reported by the server
105           language: the preferred language reported by the server
106
107   pending
108       Returns non-zero if we are still waiting for a response from one or
109       more servers; returns 0 if processing is complete.
110
111   work(seconds)
112       Enters the main loop of this module.  This method requires one
113       argument, a numeric count of seconds to work for.  This is expected to
114       be a floating point decimal, for sub-second precision.  Returns the
115       number of servers pending, just like the pending method does.
116

INTERNAL METHODS

118       These methods are only meant to be called from within the module.  They
119       are subject to change without notice.
120
121   try_connect
122       Attempts to connect to a server.  Moves the first "not_started" server
123       to the "pending" list, and creates a non-blocking IO::Socket::INET
124       object for it.  Updates the begin_time timestamp, to determine when the
125       next server should be connected.
126
127   server_sm(connection_number)
128       Implements a simple state machine.  Called with an index into the
129       pending array, to indicate that data is available for reading from this
130       server.
131
132   give_up_on(connection_number, reason)
133       Called if select reports a socket as has_exception.  Also called if the
134       server has a bogus version, times out, or we can't parse the IP address
135       or something.  Removes the entry from further processing, and emits an
136       error message on stderr.
137

EXPORT

139       None.
140

BUGS

142       implement some sort of timeout, for servers which don't respond within
143       5 seconds.
144

AUTHOR

146       Mark Glines, <mark@glines.org>.
147
149       This code is donated to the frozen bubble project,
150       www.frozen-bubble.org, so they can do whatever they want with it.
151       Copyright is therefore assigned to those guys.
152
153
154
155perl v5.34.0                      2022-01-20Games::FrozenBubble::NetDiscover(3)
Impressum