1Danga::Socket(3)      User Contributed Perl Documentation     Danga::Socket(3)
2
3
4

NAME

6       Danga::Socket - Event loop and event-driven async socket base class
7

SYNOPSIS

9         package My::Socket
10         use Danga::Socket;
11         use base ('Danga::Socket');
12         use fields ('my_attribute');
13
14         sub new {
15            my My::Socket $self = shift;
16            $self = fields::new($self) unless ref $self;
17            $self->SUPER::new( @_ );
18
19            $self->{my_attribute} = 1234;
20            return $self;
21         }
22
23         sub event_err { ... }
24         sub event_hup { ... }
25         sub event_write { ... }
26         sub event_read { ... }
27         sub close { ... }
28
29         $my_sock->tcp_cork($bool);
30
31         # write returns 1 if all writes have gone through, or 0 if there
32         # are writes in queue
33         $my_sock->write($scalar);
34         $my_sock->write($scalarref);
35         $my_sock->write(sub { ... });  # run when previous data written
36         $my_sock->write(undef);        # kick-starts
37
38         # read max $bytecount bytes, or undef on connection closed
39         $scalar_ref = $my_sock->read($bytecount);
40
41         # watch for writability.  not needed with ->write().  write()
42         # will automatically turn on watch_write when you wrote too much
43         # and turn it off when done
44         $my_sock->watch_write($bool);
45
46         # watch for readability
47         $my_sock->watch_read($bool);
48
49         # if you read too much and want to push some back on
50         # readable queue.  (not incredibly well-tested)
51         $my_sock->push_back_read($buf); # scalar or scalar ref
52
53         Danga::Socket->AddOtherFds(..);
54         Danga::Socket->SetLoopTimeout($millisecs);
55         Danga::Socket->DescriptorMap();
56         Danga::Socket->WatchedSockets();  # count of DescriptorMap keys
57         Danga::Socket->SetPostLoopCallback($code);
58         Danga::Socket->EventLoop();
59

DESCRIPTION

61       This is an abstract base class for objects backed by a socket which
62       provides the basic framework for event-driven asynchronous IO, designed
63       to be fast.  Danga::Socket is both a base class for objects, and an
64       event loop.
65
66       Callers subclass Danga::Socket.  Danga::Socket's constructor registers
67       itself with the Danga::Socket event loop, and invokes callbacks on the
68       object for readability, writability, errors, and other conditions.
69
70       Because Danga::Socket uses the "fields" module, your subclasses must
71       too.
72

MORE INFO

74       For now, see servers using Danga::Socket for guidance.  For example:
75       perlbal, mogilefsd, or ddlockd.
76

API

78       Note where ""CLASS"" is used below, normally you would call these
79       methods as:
80
81         Danga::Socket->method(...);
82
83       However using a subclass works too.
84
85       The CLASS methods are all methods for the event loop part of
86       Danga::Socket, whereas the object methods are all used on your
87       subclasses.
88
89   "CLASS->Reset()"
90       Reset all state
91
92   "CLASS->HaveEpoll()"
93       Returns a true value if this class will use IO::Epoll for async IO.
94
95   "CLASS->WatchedSockets()"
96       Returns the number of file descriptors which are registered with the
97       global poll object.
98
99   "CLASS->EnableProfiling()"
100       Turns profiling on, clearing current profiling data.
101
102   "CLASS->DisableProfiling()"
103       Turns off profiling, but retains data up to this point
104
105   "CLASS->ProfilingData()"
106       Returns reference to a hash of data in format:
107
108         ITEM => [ utime, stime, #calls ]
109
110   "CLASS->ToClose()"
111       Return the list of sockets that are awaiting close() at the end of the
112       current event loop.
113
114   "CLASS->OtherFds( [%fdmap] )"
115       Get/set the hash of file descriptors that need processing in parallel
116       with the registered Danga::Socket objects.
117
118   "CLASS->AddOtherFds( [%fdmap] )"
119       Add fds to the OtherFds hash for processing.
120
121   "CLASS->SetLoopTimeout( $timeout )"
122       Set the loop timeout for the event loop to some value in milliseconds.
123
124       A timeout of 0 (zero) means poll forever. A timeout of -1 means poll
125       and return immediately.
126
127   "CLASS->DebugMsg( $format, @args )"
128       Print the debugging message specified by the "sprintf"-style format and
129       args
130
131   "CLASS->AddTimer( $seconds, $coderef )"
132       Add a timer to occur $seconds from now. $seconds may be fractional, but
133       timers are not guaranteed to fire at the exact time you ask for.
134
135       Returns a timer object which you can call "$timer->cancel" on if you
136       need to.
137
138   "CLASS->DescriptorMap()"
139       Get the hash of Danga::Socket objects keyed by the file descriptor
140       (fileno) they are wrapping.
141
142       Returns a hash in list context or a hashref in scalar context.
143
144   "CLASS->EventLoop()"
145       Start processing IO events. In most daemon programs this never exits.
146       See "PostLoopCallback" below for how to exit the loop.
147
148   "CLASS->SetPostLoopCallback( CODEREF )"
149       Sets post loop callback function.  Pass a subref and it will be called
150       every time the event loop finishes.
151
152       Return 1 (or any true value) from the sub to make the loop continue, 0
153       or false and it will exit.
154
155       The callback function will be passed two parameters: \%DescriptorMap,
156       \%OtherFds.
157
158   OBJECT METHODS
159   "CLASS->new( $socket )"
160       Create a new Danga::Socket subclass object for the given socket which
161       will react to events on it during the "EventLoop".
162
163       This is normally (always?) called from your subclass via:
164
165         $class->SUPER::new($socket);
166
167   "$obj->tcp_cork( $boolean )"
168       Turn TCP_CORK on or off depending on the value of boolean.
169
170   "$obj->steal_socket()"
171       Basically returns our socket and makes it so that we don't try to close
172       it, but we do remove it from epoll handlers.  THIS CLOSES $self.  It is
173       the same thing as calling close, except it gives you the socket to use.
174
175   "$obj->close( [$reason] )"
176       Close the socket. The reason argument will be used in debugging
177       messages.
178
179   "$obj->sock()"
180       Returns the underlying IO::Handle for the object.
181
182   "$obj->set_writer_func( CODEREF )"
183       Sets a function to use instead of "syswrite()" when writing data to the
184       socket.
185
186   "$obj->write( $data )"
187       Write the specified data to the underlying handle.  data may be scalar,
188       scalar ref, code ref (to run when there), or undef just to kick-start.
189       Returns 1 if writes all went through, or 0 if there are writes in
190       queue. If it returns 1, caller should stop waiting for 'writable'
191       events)
192
193   "$obj->push_back_read( $buf )"
194       Push back buf (a scalar or scalarref) into the read stream. Useful if
195       you read more than you need to and want to return this data on the next
196       "read".
197
198   "$obj->read( $bytecount )"
199       Read at most bytecount bytes from the underlying handle; returns scalar
200       ref on read, or undef on connection closed.
201
202   (VIRTUAL) "$obj->event_read()"
203       Readable event handler. Concrete deriviatives of Danga::Socket should
204       provide an implementation of this. The default implementation will die
205       if called.
206
207   (VIRTUAL) "$obj->event_err()"
208       Error event handler. Concrete deriviatives of Danga::Socket should
209       provide an implementation of this. The default implementation will die
210       if called.
211
212   (VIRTUAL) "$obj->event_hup()"
213       'Hangup' event handler. Concrete deriviatives of Danga::Socket should
214       provide an implementation of this. The default implementation will die
215       if called.
216
217   "$obj->event_write()"
218       Writable event handler. Concrete deriviatives of Danga::Socket may wish
219       to provide an implementation of this. The default implementation calls
220       "write()" with an "undef".
221
222   "$obj->watch_read( $boolean )"
223       Turn 'readable' event notification on or off.
224
225   "$obj->watch_write( $boolean )"
226       Turn 'writable' event notification on or off.
227
228   "$obj->dump_error( $message )"
229       Prints to STDERR a backtrace with information about this socket and
230       what lead up to the dump_error call.
231
232   "$obj->debugmsg( $format, @args )"
233       Print the debugging message specified by the "sprintf"-style format and
234       args.
235
236   "$obj->peer_ip_string()"
237       Returns the string describing the peer's IP
238
239   "$obj->peer_addr_string()"
240       Returns the string describing the peer for the socket which underlies
241       this object in form "ip:port"
242
243   "$obj->local_ip_string()"
244       Returns the string describing the local IP
245
246   "$obj->local_addr_string()"
247       Returns the string describing the local end of the socket which
248       underlies this object in form "ip:port"
249
250   "$obj->as_string()"
251       Returns a string describing this socket.
252

AUTHORS

254       Brad Fitzpatrick <brad@danga.com> - author
255
256       Michael Granger <ged@danga.com> - docs, testing
257
258       Mark Smith <junior@danga.com> - contributor, heavy user, testing
259
260       Matt Sergeant <matt@sergeant.org> - kqueue support, docs, timers, other
261       bits
262

BUGS

264       Not documented enough (but isn't that true of every project?).
265
266       tcp_cork only works on Linux for now.  No BSD push/nopush support.
267

LICENSE

269       License is granted to use and distribute this module under the same
270       terms as Perl itself.
271
272
273
274perl v5.28.1                      2008-11-28                  Danga::Socket(3)
Impressum