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. If you call read more than
201       once and no more data available after the first call, a scalar ref to
202       an empty string is returned.
203
204   (VIRTUAL) "$obj->event_read()"
205       Readable event handler. Concrete derivatives of Danga::Socket should
206       provide an implementation of this. The default implementation will die
207       if called.
208
209   (VIRTUAL) "$obj->event_err()"
210       Error event handler. Concrete derivatives of Danga::Socket should
211       provide an implementation of this. The default implementation will die
212       if called.
213
214   (VIRTUAL) "$obj->event_hup()"
215       'Hangup' event handler. Concrete derivatives of Danga::Socket should
216       provide an implementation of this. The default implementation will die
217       if called.
218
219   "$obj->event_write()"
220       Writable event handler. Concrete derivatives of Danga::Socket may wish
221       to provide an implementation of this. The default implementation calls
222       "write()" with an "undef".
223
224   "$obj->watch_read( $boolean )"
225       Turn 'readable' event notification on or off.
226
227   "$obj->watch_write( $boolean )"
228       Turn 'writable' event notification on or off.
229
230   "$obj->dump_error( $message )"
231       Prints to STDERR a backtrace with information about this socket and
232       what lead up to the dump_error call.
233
234   "$obj->debugmsg( $format, @args )"
235       Print the debugging message specified by the "sprintf"-style format and
236       args.
237
238   "$obj->peer_ip_string()"
239       Returns the string describing the peer's IP
240
241   "$obj->peer_addr_string()"
242       Returns the string describing the peer for the socket which underlies
243       this object in form "ip:port"
244
245   "$obj->local_ip_string()"
246       Returns the string describing the local IP
247
248   "$obj->local_addr_string()"
249       Returns the string describing the local end of the socket which
250       underlies this object in form "ip:port"
251
252   "$obj->as_string()"
253       Returns a string describing this socket.
254

AUTHORS

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

BUGS

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

LICENSE

271       License is granted to use and distribute this module under the same
272       terms as Perl itself.
273
274
275
276perl v5.34.0                      2021-07-22                  Danga::Socket(3)
Impressum