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

AUTHORS

292       Brad Fitzpatrick <brad@danga.com> - author
293
294       Michael Granger <ged@danga.com> - docs, testing
295
296       Mark Smith <junior@danga.com> - contributor, heavy user, testing
297
298       Matt Sergeant <matt@sergeant.org> - kqueue support, docs, timers, other
299       bits
300

BUGS

302       Not documented enough (but isn't that true of every project?).
303
304       tcp_cork only works on Linux for now.  No BSD push/nopush support.
305

LICENSE

307       License is granted to use and distribute this module under the same
308       terms as Perl itself.
309
310
311
312perl v5.8.8                       2007-04-16                         Socket(3)