1Danga::Socket(3) User Contributed Perl Documentation Danga::Socket(3)
2
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 sub new {
15 my My::Socket $self = shift;
16 $self = fields::new($self) unless ref $self;
17 $self->SUPER::new( @_ );
18 $self->{my_attribute} = 1234;
20 return $self;
21 }
22 sub event_err { ... }
24 sub event_hup { ... }
25 sub event_write { ... }
26 sub event_read { ... }
27 sub close { ... }
28 $my_sock->tcp_cork($bool);
30 # 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 # read max $bytecount bytes, or undef on connection closed
39 $scalar_ref = $my_sock->read($bytecount);
40 # 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 # watch for readability
47 $my_sock->watch_read($bool);
48 # 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 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 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 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 Danga::Socket->method(...);
82 However using a subclass works too.
84 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 "CLASS->Reset()"
90 Reset all state
91 "CLASS->HaveEpoll()"
93 Returns a true value if this class will use IO::Epoll for async IO.
94 "CLASS->WatchedSockets()"
96 Returns the number of file descriptors which are registered with the
97 global poll object.
98 "CLASS->EnableProfiling()"
100 Turns profiling on, clearing current profiling data.
101 "CLASS->DisableProfiling()"
103 Turns off profiling, but retains data up to this point
104 "CLASS->ProfilingData()"
106 Returns reference to a hash of data in format:
107 ITEM => [ utime, stime, #calls ]
109 "CLASS->ToClose()"
111 Return the list of sockets that are awaiting close() at the end of the
112 current event loop.
113 "CLASS->OtherFds( [%fdmap] )"
115 Get/set the hash of file descriptors that need processing in parallel
116 with the registered Danga::Socket objects.
117 "CLASS->AddOtherFds( [%fdmap] )"
119 Add fds to the OtherFds hash for processing.
120 "CLASS->SetLoopTimeout( $timeout )"
122 Set the loop timeout for the event loop to some value in milliseconds.
123 A timeout of 0 (zero) means poll forever. A timeout of -1 means poll
125 and return immediately.
126 "CLASS->DebugMsg( $format, @args )"
128 Print the debugging message specified by the "sprintf"-style format and
129 args
130 "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 Returns a timer object which you can call "$timer->cancel" on if you
136 need to.
137 "CLASS->DescriptorMap()"
139 Get the hash of Danga::Socket objects keyed by the file descriptor
140 (fileno) they are wrapping.
141 Returns a hash in list context or a hashref in scalar context.
143 "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 "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 Return 1 (or any true value) from the sub to make the loop continue, 0
153 or false and it will exit.
154 The callback function will be passed two parameters: \%DescriptorMap,
156 \%OtherFds.
157 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 This is normally (always?) called from your subclass via:
164 $class->SUPER::new($socket);
166 "$obj->tcp_cork( $boolean )"
168 Turn TCP_CORK on or off depending on the value of boolean.
169 "$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 "$obj->close( [$reason] )"
176 Close the socket. The reason argument will be used in debugging
177 messages.
178 "$obj->sock()"
180 Returns the underlying IO::Handle for the object.
181 "$obj->set_writer_func( CODEREF )"
183 Sets a function to use instead of syswrite() when writing data to the
184 socket.
185 "$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 "$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 "$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 (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 (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 (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 "$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 "$obj->watch_read( $boolean )"
225 Turn 'readable' event notification on or off.
226 "$obj->watch_write( $boolean )"
228 Turn 'writable' event notification on or off.
229 "$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 "$obj->debugmsg( $format, @args )"
235 Print the debugging message specified by the "sprintf"-style format and
236 args.
237 "$obj->peer_ip_string()"
239 Returns the string describing the peer's IP
240 "$obj->peer_addr_string()"
242 Returns the string describing the peer for the socket which underlies
243 this object in form "ip:port"
244 "$obj->local_ip_string()"
246 Returns the string describing the local IP
247 "$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 "$obj->as_string()"
253 Returns a string describing this socket.
254
256 Brad Fitzpatrick <brad@danga.com> - author
257 Michael Granger <ged@danga.com> - docs, testing
259 Mark Smith <junior@danga.com> - contributor, heavy user, testing
261 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 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.
273perl v5.36.0 2023-01-20 Danga::Socket(3)