Changeset 100
- Timestamp:
- 08/16/06 15:23:42 (2 years ago)
- Files:
-
- trunk/CHANGES (modified) (1 diff)
- trunk/Socket.pm (modified) (32 diffs)
Legend:
- Unmodified
- Added
- Removed
- Modified
- Copied
- Moved
trunk/CHANGES
r99 r100 2 2 -- Added local_ip_string() and local_addr_string() (msergeant). 3 3 -- Removed bogus 'ticker' code from KQueue event loop (msergeant). 4 -- Converted comment based docs to POD and fix some of those docs 5 to match reality (msergeant). 4 6 5 7 1.52: (2006-07-09) trunk/Socket.pm
r99 r100 77 77 perlbal, mogilefsd, or ddlockd. 78 78 79 =head1 AUTHORS 80 81 Brad Fitzpatrick <brad@danga.com> - author 82 83 Michael Granger <ged@danga.com> - docs, testing 84 85 Mark Smith <junior@danga.com> - contributor, heavy user, testing 86 87 Matt Sergeant <matt@sergeant.org> - kqueue support 88 89 =head1 BUGS 90 91 Not documented enough. 92 93 tcp_cork only works on Linux for now. No BSD push/nopush support. 94 95 =head1 LICENSE 96 97 License is granted to use and distribute this module under the same 98 terms as Perl itself. 79 =head1 API 80 81 Note where "C<CLASS>" is used below, normally you would call these methods as: 82 83 Danga::Socket->method(...); 84 85 However using a subclass works too. 86 87 The CLASS methods are all methods for the event loop part of Danga::Socket, 88 whereas the object methods are all used on your subclasses. 99 89 100 90 =cut … … 177 167 ##################################################################### 178 168 179 # (CLASS) method: reset all state 169 =head2 C<< CLASS->Reset() >> 170 171 Reset all state 172 173 =cut 180 174 sub Reset { 181 175 %DescriptorMap = (); … … 192 186 } 193 187 194 ### (CLASS) METHOD: HaveEpoll() 195 ### Returns a true value if this class will use IO::Epoll for async IO. 188 =head2 C<< CLASS->HaveEpoll() >> 189 190 Returns a true value if this class will use IO::Epoll for async IO. 191 192 =cut 196 193 sub HaveEpoll { 197 194 _InitPoller(); … … 199 196 } 200 197 201 ### (CLASS) METHOD: WatchedSockets() 202 ### Returns the number of file descriptors which are registered with the global 203 ### poll object. 198 =head2 C<< CLASS->WatchedSockets() >> 199 200 Returns the number of file descriptors which are registered with the global 201 poll object. 202 203 =cut 204 204 sub WatchedSockets { 205 205 return scalar keys %DescriptorMap; … … 207 207 *watched_sockets = *WatchedSockets; 208 208 209 ### (CLASS) METHOD: EnableProfiling() 210 ### Turns profiling on, clearing current profiling data. 209 =head2 C<< CLASS->EnableProfiling() >> 210 211 Turns profiling on, clearing current profiling data. 212 213 =cut 211 214 sub EnableProfiling { 212 215 if ($opt_bsd_resource) { … … 218 221 } 219 222 220 ### (CLASS) METHOD: DisableProfiling() 221 ### Turns off profiling, but retains data up to this point 223 =head2 C<< CLASS->DisableProfiling() >> 224 225 Turns off profiling, but retains data up to this point 226 227 =cut 222 228 sub DisableProfiling { 223 229 $DoProfile = 0; 224 230 } 225 231 226 ### (CLASS) METHOD: ProfilingData() 227 ### Returns reference to a hash of data in format above (see %Profiling) 232 =head2 C<< CLASS->ProfilingData() >> 233 234 Returns reference to a hash of data in format: 235 236 ITEM => [ utime, stime, #calls ] 237 238 =cut 228 239 sub ProfilingData { 229 240 return \%Profiling; 230 241 } 231 242 232 ### (CLASS) METHOD: ToClose() 233 ### Return the list of sockets that are awaiting close() at the end of the 234 ### current event loop. 243 =head2 C<< CLASS->ToClose() >> 244 245 Return the list of sockets that are awaiting close() at the end of the 246 current event loop. 247 248 =cut 235 249 sub ToClose { return @ToClose; } 236 250 237 ### (CLASS) METHOD: OtherFds( [%fdmap] ) 238 ### Get/set the hash of file descriptors that need processing in parallel with 239 ### the registered Danga::Socket objects. 251 =head2 C<< CLASS->OtherFds( [%fdmap] ) >> 252 253 Get/set the hash of file descriptors that need processing in parallel with 254 the registered Danga::Socket objects. 255 256 =cut 240 257 sub OtherFds { 241 258 my $class = shift; … … 244 261 } 245 262 246 ### (CLASS) METHOD: AddOtherFds( [%fdmap] ) 247 ### Add fds to the OtherFds hash for processing. 263 =head2 C<< CLASS->AddOtherFds( [%fdmap] ) >> 264 265 Add fds to the OtherFds hash for processing. 266 267 =cut 248 268 sub AddOtherFds { 249 269 my $class = shift; … … 252 272 } 253 273 254 ### (CLASS) METHOD: SetLoopTimeout( $timeout ) 255 ### Set the loop timeout for the event loop to some value in milliseconds. 274 =head2 C<< CLASS->SetLoopTimeout( $timeout ) >> 275 276 Set the loop timeout for the event loop to some value in milliseconds. 277 278 A timeout of 0 (zero) means poll forever. A timeout of -1 means poll and return 279 immediately. 280 281 =cut 256 282 sub SetLoopTimeout { 257 283 return $LoopTimeout = $_[1] + 0; 258 284 } 259 285 260 ### (CLASS) METHOD: DebugMsg( $format, @args ) 261 ### Print the debugging message specified by the C<sprintf>-style I<format> and 262 ### I<args> 286 =head2 C<< CLASS->DebugMsg( $format, @args ) >> 287 288 Print the debugging message specified by the C<sprintf>-style I<format> and 289 I<args> 290 291 =cut 263 292 sub DebugMsg { 264 293 my ( $class, $fmt, @args ) = @_; … … 267 296 } 268 297 269 ### (CLASS) METHOD: AddTimer( $seconds, $coderef ) 270 ### Add a timer to occur $seconds from now. $seconds may be fractional. Don't 271 ### expect this to be accurate though. 298 =head2 C<< CLASS->AddTimer( $seconds, $coderef ) >> 299 300 Add a timer to occur $seconds from now. $seconds may be fractional, but timers 301 are not guaranteed to fire at the exact time you ask for. 302 303 Returns a timer object which you can call C<< $timer->cancel >> on if you need to. 304 305 =cut 272 306 sub AddTimer { 273 307 my $class = shift; … … 297 331 } 298 332 299 300 ### (CLASS) METHOD: DescriptorMap() 301 ### Get the hash of Danga::Socket objects keyed by the file descriptor they are 302 ### wrapping. 333 =head2 C<< CLASS->DescriptorMap() >> 334 335 Get the hash of Danga::Socket objects keyed by the file descriptor (fileno) they 336 are wrapping. 337 338 Returns a hash in list context or a hashref in scalar context. 339 340 =cut 303 341 sub DescriptorMap { 304 342 return wantarray ? %DescriptorMap : \%DescriptorMap; … … 333 371 } 334 372 335 ### FUNCTION: EventLoop() 336 ### Start processing IO events. 373 =head2 C<< CLASS->EventLoop() >> 374 375 Start processing IO events. In most daemon programs this never exits. See 376 C<PostLoopCallback> below for how to exit the loop. 377 378 =cut 337 379 sub EventLoop { 338 380 my $class = shift; … … 599 641 } 600 642 601 ### CLASS METHOD: SetPostLoopCallback 602 ### Sets post loop callback function. Pass a subref and it will be 603 ### called every time the event loop finishes. Return 1 from the sub 604 ### to make the loop continue, else it will exit. The function will 605 ### be passed two parameters: \%DescriptorMap, \%OtherFds. 643 =head2 C<< CLASS->SetPostLoopCallback( CODEREF ) >> 644 645 Sets post loop callback function. Pass a subref and it will be 646 called every time the event loop finishes. 647 648 Return 1 (or any true value) from the sub to make the loop continue, 0 or false 649 and it will exit. 650 651 The callback function will be passed two parameters: \%DescriptorMap, \%OtherFds. 652 653 =cut 606 654 sub SetPostLoopCallback { 607 655 my ($class, $ref) = @_; … … 682 730 ##################################################################### 683 731 684 ### METHOD: new( $socket ) 685 ### Create a new Danga::Socket object for the given I<socket> which will react 686 ### to events on it during the C<wait_loop>. 732 =head2 OBJECT METHODS 733 734 =head2 C<< CLASS->new( $socket ) >> 735 736 Create a new Danga::Socket subclass object for the given I<socket> which will 737 react to events on it during the C<EventLoop>. 738 739 This is normally (always?) called from your subclass via: 740 741 $class->SUPER::new($socket); 742 743 =cut 687 744 sub new { 688 745 my Danga::Socket $self = shift; … … 733 790 ##################################################################### 734 791 735 ### METHOD: tcp_cork( $boolean ) 736 ### Turn TCP_CORK on or off depending on the value of I<boolean>. 792 =head2 C<< $obj->tcp_cork( $boolean ) >> 793 794 Turn TCP_CORK on or off depending on the value of I<boolean>. 795 796 =cut 737 797 sub tcp_cork { 738 798 my Danga::Socket $self = $_[0]; … … 770 830 } 771 831 772 ### METHOD: steal_socket 773 ### Basically returns our socket and makes it so that we don't try to close it, 774 ### but we do remove it from epoll handlers. THIS CLOSES $self. It is the same 775 ### thing as calling close, except it gives you the socket to use. 832 =head2 C<< $obj->steal_socket() >> 833 834 Basically returns our socket and makes it so that we don't try to close it, 835 but we do remove it from epoll handlers. THIS CLOSES $self. It is the same 836 thing as calling close, except it gives you the socket to use. 837 838 =cut 776 839 sub steal_socket { 777 840 my Danga::Socket $self = $_[0]; … … 787 850 } 788 851 789 ### METHOD: close( [$reason] ) 790 ### Close the socket. The I<reason> argument will be used in debugging messages. 852 =head2 C<< $obj->close( [$reason] ) >> 853 854 Close the socket. The I<reason> argument will be used in debugging messages. 855 856 =cut 791 857 sub close { 792 858 my Danga::Socket $self = $_[0]; … … 857 923 } 858 924 859 ### METHOD: sock() 860 ### Returns the underlying IO::Handle for the object. 925 =head2 C<< $obj->sock() >> 926 927 Returns the underlying IO::Handle for the object. 928 929 =cut 861 930 sub sock { 862 931 my Danga::Socket $self = shift; … … 864 933 } 865 934 935 =head2 C<< $obj->set_writer_func( CODEREF ) >> 936 937 Sets a function to use instead of C<syswrite()> when writing data to the socket. 938 939 =cut 866 940 sub set_writer_func { 867 941 my Danga::Socket $self = shift; … … 871 945 } 872 946 873 ### METHOD: write( $data ) 874 ### Write the specified data to the underlying handle. I<data> may be scalar, 875 ### scalar ref, code ref (to run when there), or undef just to kick-start. 876 ### Returns 1 if writes all went through, or 0 if there are writes in queue. If 877 ### it returns 1, caller should stop waiting for 'writable' events) 947 =head2 C<< $obj->write( $data ) >> 948 949 Write the specified data to the underlying handle. I<data> may be scalar, 950 scalar ref, code ref (to run when there), or undef just to kick-start. 951 Returns 1 if writes all went through, or 0 if there are writes in queue. If 952 it returns 1, caller should stop waiting for 'writable' events) 953 954 =cut 878 955 sub write { 879 956 my Danga::Socket $self; … … 1000 1077 } 1001 1078 1002 ### METHOD: push_back_read( $buf ) 1003 ### Push back I<buf> (a scalar or scalarref) into the read stream 1079 =head2 C<< $obj->push_back_read( $buf ) >> 1080 1081 Push back I<buf> (a scalar or scalarref) into the read stream. Useful if you read 1082 more than you need to and want to return this data on the next "read". 1083 1084 =cut 1004 1085 sub push_back_read { 1005 1086 my Danga::Socket $self = shift; … … 1009 1090 } 1010 1091 1011 ### METHOD: read( $bytecount ) 1012 ### Read at most I<bytecount> bytes from the underlying handle; returns scalar 1013 ### ref on read, or undef on connection closed. 1092 =head2 C<< $obj->read( $bytecount ) >> 1093 1094 Read at most I<bytecount> bytes from the underlying handle; returns scalar 1095 ref on read, or undef on connection closed. 1096 1097 =cut 1014 1098 sub read { 1015 1099 my Danga::Socket $self = shift; … … 1050 1134 } 1051 1135 1052 1053 ### (VIRTUAL) METHOD: event_read() 1054 ### Readable event handler. Concrete deriviatives of Danga::Socket should 1055 ### provide an implementation of this. The default implementation will die if 1056 ### called. 1136 =head2 (VIRTUAL) C<< $obj->event_read() >> 1137 1138 Readable event handler. Concrete deriviatives of Danga::Socket should 1139 provide an implementation of this. The default implementation will die if 1140 called. 1141 1142 =cut 1057 1143 sub event_read { die "Base class event_read called for $_[0]\n"; } 1058 1144 1059 1060 ### (VIRTUAL) METHOD: event_err() 1061 ### Error event handler. Concrete deriviatives of Danga::Socket should 1062 ### provide an implementation of this. The default implementation will die if 1063 ### called. 1145 =head2 (VIRTUAL) C<< $obj->event_err() >> 1146 1147 Error event handler. Concrete deriviatives of Danga::Socket should 1148 provide an implementation of this. The default implementation will die if 1149 called. 1150 1151 =cut 1064 1152 sub event_err { die "Base class event_err called for $_[0]\n"; } 1065 1153 1066 1067 ### (VIRTUAL) METHOD: event_hup() 1068 ### 'Hangup' event handler. Concrete deriviatives of Danga::Socket should 1069 ### provide an implementation of this. The default implementation will die if 1070 ### called. 1154 =head2 (VIRTUAL) C<< $obj->event_hup() >> 1155 1156 'Hangup' event handler. Concrete deriviatives of Danga::Socket should 1157 provide an implementation of this. The default implementation will die if 1158 called. 1159 1160 =cut 1071 1161 sub event_hup { die "Base class event_hup called for $_[0]\n"; } 1072 1162 1073 1074 ### METHOD: event_write() 1075 ### Writable event handler. Concrete deriviatives of Danga::Socket may wish to 1076 ### provide an implementation of this. The default implementation calls 1077 ### C<write()> with an C<undef>. 1163 =head2 C<< $obj->event_write() >> 1164 1165 Writable event handler. Concrete deriviatives of Danga::Socket may wish to 1166 provide an implementation of this. The default implementation calls 1167 C<write()> with an C<undef>. 1168 1169 =cut 1078 1170 sub event_write { 1079 1171 my $self = shift; … … 1081 1173 } 1082 1174 1083 1084 ### METHOD: watch_read( $boolean ) 1085 ### Turn 'readable' event notification on or off. 1175 =head2 C<< $obj->watch_read( $boolean ) >> 1176 1177 Turn 'readable' event notification on or off. 1178 1179 =cut 1086 1180 sub watch_read { 1087 1181 my Danga::Socket $self = shift; … … 1109 1203 } 1110 1204 1111 ### METHOD: watch_write( $boolean ) 1112 ### Turn 'writable' event notification on or off. 1205 =head2 C<< $obj->watch_write( $boolean ) >> 1206 1207 Turn 'writable' event notification on or off. 1208 1209 =cut 1113 1210 sub watch_write { 1114 1211 my Danga::Socket $self = shift; … … 1136 1233 } 1137 1234 1138 # METHOD: dump_error( $message ) 1139 # Prints to STDERR a backtrace with information about this socket and what lead 1140 # up to the dump_error call. 1235 =head2 C<< $obj->dump_error( $message ) >> 1236 1237 Prints to STDERR a backtrace with information about this socket and what lead 1238 up to the dump_error call. 1239 1240 =cut 1141 1241 sub dump_error { 1142 1242 my $i = 0; … … 1151 1251 } 1152 1252 1153 1154 ### METHOD: debugmsg( $format, @args ) 1155 ### Print the debugging message specified by the C<sprintf>-style I<format> and 1156 ### I<args> if the object's C<debug_level> is greater than or equal to the given 1157 ### I<level>. 1253 =head2 C<< $obj->debugmsg( $format, @args ) >> 1254 1255 Print the debugging message specified by the C<sprintf>-style I<format> and 1256 I<args>. 1257 1258 =cut 1158 1259 sub debugmsg { 1159 1260 my ( $self, $fmt, @args ) = @_; … … 1165 1266 1166 1267 1167 ### METHOD: peer_ip_string() 1168 ### Returns the string describing the peer's IP 1268 =head2 C<< $obj->peer_ip_string() >> 1269 1270 Returns the string describing the peer's IP 1271 1272 =cut 1169 1273 sub peer_ip_string { 1170 1274 my Danga::Socket $self = shift; … … 1189 1293 } 1190 1294 1191 ### METHOD: peer_addr_string() 1192 ### Returns the string describing the peer for the socket which underlies this 1193 ### object in form "ip:port" 1295 =head2 C<< $obj->peer_addr_string() >> 1296 1297 Returns the string describing the peer for the socket which underlies this 1298 object in form "ip:port" 1299 1300 =cut 1194 1301 sub peer_addr_string { 1195 1302 my Danga::Socket $self = shift; … … 1198 1305 } 1199 1306 1200 ### METHOD: local_ip_string() 1201 ### Returns the string describing the local IP 1307 =head2 C<< $obj->local_ip_string() >> 1308 1309 Returns the string describing the local IP 1310 1311 =cut 1202 1312 sub local_ip_string { 1203 1313 my Danga::Socket $self = shift; … … 1214 1324 } 1215 1325 1216 ### METHOD: local_addr_string() 1217 ### Returns the string describing the local end of the socket which underlies this 1218 ### object in form "ip:port" 1326 =head2 C<< $obj->local_addr_string() >> 1327 1328 Returns the string describing the local end of the socket which underlies this 1329 object in form "ip:port" 1330 1331 =cut 1219 1332 sub local_addr_string { 1220 1333 my Danga::Socket $self = shift; … … 1224 1337 1225 1338 1226 ### METHOD: as_string() 1227 ### Returns a string describing this socket. 1339 =head2 C<< $obj->as_string() >> 1340 1341 Returns a string describing this socket. 1342 1343 =cut 1228 1344 sub as_string { 1229 1345 my Danga::Socket $self = shift; … … 1251 1367 } 1252 1368 1369 =head1 AUTHORS 1370 1371 Brad Fitzpatrick <brad@danga.com> - author 1372 1373 Michael Granger <ged@danga.com> - docs, testing 1374 1375 Mark Smith <junior@danga.com> - contributor, heavy user, testing 1376 1377 Matt Sergeant <matt@sergeant.org> - kqueue support, docs, timers, other bits 1378 1379 =head1 BUGS 1380 1381 Not documented enough (but isn't that true of every project?). 1382 1383 tcp_cork only works on Linux for now. No BSD push/nopush support. 1384 1385 =head1 LICENSE 1386 1387 License is granted to use and distribute this module under the same 1388 terms as Perl itself. 1389 1390 =cut 1391 1253 1392 1; 1254 1393
