1Danga::Socket(3) User Contributed Perl Documentation Danga::Socket(3)
2
3
4
6 Danga::Socket - Event loop and event-driven async socket base class
7
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
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
74 For now, see servers using Danga::Socket for guidance. For example:
75 perlbal, mogilefsd, or ddlockd.
76
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
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
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
271 License is granted to use and distribute this module under the same
272 terms as Perl itself.
273
274
275
276perl v5.30.0 2019-11-05 Danga::Socket(3)