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.
201 (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 (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 (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 "$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 "$obj->watch_read( $boolean )"
223 Turn 'readable' event notification on or off.
224 "$obj->watch_write( $boolean )"
226 Turn 'writable' event notification on or off.
227 "$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 "$obj->debugmsg( $format, @args )"
233 Print the debugging message specified by the "sprintf"-style format and
234 args.
235 "$obj->peer_ip_string()"
237 Returns the string describing the peer's IP
238 "$obj->peer_addr_string()"
240 Returns the string describing the peer for the socket which underlies
241 this object in form "ip:port"
242 "$obj->local_ip_string()"
244 Returns the string describing the local IP
245 "$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 "$obj->as_string()"
251 Returns a string describing this socket.
252
254 Brad Fitzpatrick <brad@danga.com> - author
255 Michael Granger <ged@danga.com> - docs, testing
257 Mark Smith <junior@danga.com> - contributor, heavy user, testing
259 Matt Sergeant <matt@sergeant.org> - kqueue support, docs, timers, other
261 bits
262
264 Not documented enough (but isn't that true of every project?).
265 tcp_cork only works on Linux for now. No BSD push/nopush support.
267
269 License is granted to use and distribute this module under the same
270 terms as Perl itself.
271perl v5.12.1 2008-11-28 Danga::Socket(3)