ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/AnyEvent/lib/AnyEvent/Handle.pm
(Generate patch)

Comparing AnyEvent/lib/AnyEvent/Handle.pm (file contents):
Revision 1.183 by root, Thu Sep 3 12:45:35 2009 UTC vs.
Revision 1.186 by root, Mon Sep 7 19:54:57 2009 UTC

… …
60use AnyEvent (); BEGIN { AnyEvent::common_sense } 60use AnyEvent (); BEGIN { AnyEvent::common_sense }
61use AnyEvent::Util qw(WSAEWOULDBLOCK); 61use AnyEvent::Util qw(WSAEWOULDBLOCK);
62 62
63our $VERSION = $AnyEvent::VERSION; 63our $VERSION = $AnyEvent::VERSION;
64 64
65sub _load_func($) {
66 my $func = $_[0];
67
68 unless (defined &$func) {
69 my $pkg = $func;
70 do {
71 $pkg =~ s/::[^:]+$//
72 or return;
73 eval "require $pkg";
74 } until defined &$func;
75 }
76
77 \&$func
78}
79
65=head1 METHODS 80=head1 METHODS
66 81
67=over 4 82=over 4
68 83
69=item $handle = B<new> AnyEvent::TLS fh => $filehandle, key => value... 84=item $handle = B<new> AnyEvent::TLS fh => $filehandle, key => value...
… …
114 129
115The actual numeric host and port (the socket peername) are passed as 130The actual numeric host and port (the socket peername) are passed as
116parameters, together with a retry callback. 131parameters, together with a retry callback.
117 132
118When, for some reason, the handle is not acceptable, then calling 133When, for some reason, the handle is not acceptable, then calling
119C<$retry> will continue with the next conenction target (in case of 134C<$retry> will continue with the next connection target (in case of
120multi-homed hosts or SRV records there can be multiple connection 135multi-homed hosts or SRV records there can be multiple connection
121endpoints). When it is called then the read and write queues, eof status, 136endpoints). At the time it is called the read and write queues, eof
122tls status and similar properties of the handle are being reset. 137status, tls status and similar properties of the handle will have been
138reset.
123 139
124In most cases, ignoring the C<$retry> parameter is the way to go. 140In most cases, ignoring the C<$retry> parameter is the way to go.
125 141
126=item on_connect_error => $cb->($handle, $message) 142=item on_connect_error => $cb->($handle, $message)
127 143
128This callback is called when the conenction could not be 144This callback is called when the connection could not be
129established. C<$!> will contain the relevant error code, and C<$message> a 145established. C<$!> will contain the relevant error code, and C<$message> a
130message describing it (usually the same as C<"$!">). 146message describing it (usually the same as C<"$!">).
131 147
132If this callback isn't specified, then C<on_error> will be called with a 148If this callback isn't specified, then C<on_error> will be called with a
133fatal error instead. 149fatal error instead.
… …
289 305
290=item keepalive => <boolean> 306=item keepalive => <boolean>
291 307
292Enables (default disable) the SO_KEEPALIVE option on the stream socket: 308Enables (default disable) the SO_KEEPALIVE option on the stream socket:
293normally, TCP connections have no time-out once established, so TCP 309normally, TCP connections have no time-out once established, so TCP
294conenctions, once established, can stay alive forever even when the other 310connections, once established, can stay alive forever even when the other
295side has long gone. TCP keepalives are a cheap way to take down long-lived 311side has long gone. TCP keepalives are a cheap way to take down long-lived
296TCP connections whent he other side becomes unreachable. While the default 312TCP connections whent he other side becomes unreachable. While the default
297is OS-dependent, TCP keepalives usually kick in after around two hours, 313is OS-dependent, TCP keepalives usually kick in after around two hours,
298and, if the other side doesn't reply, take down the TCP connection some 10 314and, if the other side doesn't reply, take down the TCP connection some 10
299to 15 minutes later. 315to 15 minutes later.
… …
312is enabled) gives you the most portable way of getting urgent data, by 328is enabled) gives you the most portable way of getting urgent data, by
313putting it into the stream. 329putting it into the stream.
314 330
315Since BSD emulation of OOB data on top of TCP's urgent data can have 331Since BSD emulation of OOB data on top of TCP's urgent data can have
316security implications, AnyEvent::Handle sets this flag automatically 332security implications, AnyEvent::Handle sets this flag automatically
317unless explicitly specified. 333unless explicitly specified. Note that setting this flag after
334establishing a connection I<may> be a bit too late (data loss could
335already have occured on BSD systems), but at least it will protect you
336from most attacks.
318 337
319=item read_size => <bytes> 338=item read_size => <bytes>
320 339
321The default read block size (the amount of bytes this module will 340The default read block size (the amount of bytes this module will
322try to read during each loop iteration, which affects memory 341try to read during each loop iteration, which affects memory
… …
356C<undef>. 375C<undef>.
357 376
358=item tls => "accept" | "connect" | Net::SSLeay::SSL object 377=item tls => "accept" | "connect" | Net::SSLeay::SSL object
359 378
360When this parameter is given, it enables TLS (SSL) mode, that means 379When this parameter is given, it enables TLS (SSL) mode, that means
361AnyEvent will start a TLS handshake as soon as the conenction has been 380AnyEvent will start a TLS handshake as soon as the connection has been
362established and will transparently encrypt/decrypt data afterwards. 381established and will transparently encrypt/decrypt data afterwards.
363 382
364All TLS protocol errors will be signalled as C<EPROTO>, with an 383All TLS protocol errors will be signalled as C<EPROTO>, with an
365appropriate error message. 384appropriate error message.
366 385
… …
868 }; 887 };
869} 888}
870 889
871our %WH; 890our %WH;
872 891
892# deprecated
873sub register_write_type($$) { 893sub register_write_type($$) {
874 $WH{$_[0]} = $_[1]; 894 $WH{$_[0]} = $_[1];
875} 895}
876 896
877sub push_write { 897sub push_write {
878 my $self = shift; 898 my $self = shift;
879 899
880 if (@_ > 1) { 900 if (@_ > 1) {
881 my $type = shift; 901 my $type = shift;
882 902
903 @_ = ($WH{$type} ||= _load_func "$type\::anyevent_write_type"
883 @_ = ($WH{$type} or Carp::croak "unsupported type passed to AnyEvent::Handle::push_write") 904 or Carp::croak "unsupported/unloadable type '$type' passed to AnyEvent::Handle::push_write")
884 ->($self, @_); 905 ->($self, @_);
885 } 906 }
886 907
887 if ($self->{tls}) { 908 if ($self->{tls}) {
888 $self->{_tls_wbuf} .= $_[0]; 909 $self->{_tls_wbuf} .= $_[0];
… …
893 } 914 }
894} 915}
895 916
896=item $handle->push_write (type => @args) 917=item $handle->push_write (type => @args)
897 918
898Instead of formatting your data yourself, you can also let this module do 919Instead of formatting your data yourself, you can also let this module
899the job by specifying a type and type-specific arguments. 920do the job by specifying a type and type-specific arguments. You
921can also specify the (fully qualified) name of a package, in which
922case AnyEvent tries to load the package and then expects to find the
923C<anyevent_read_type> function inside (see "custom write types", below).
900 924
901Predefined types are (if you have ideas for additional types, feel free to 925Predefined types are (if you have ideas for additional types, feel free to
902drop by and tell us): 926drop by and tell us):
903 927
904=over 4 928=over 4
… …
1016 1040
1017 delete $self->{low_water_mark}; 1041 delete $self->{low_water_mark};
1018 $self->on_drain (sub { shutdown $_[0]{fh}, 1 }); 1042 $self->on_drain (sub { shutdown $_[0]{fh}, 1 });
1019} 1043}
1020 1044
1021=item AnyEvent::Handle::register_write_type type => $coderef->($handle, @args) 1045=item custom write types - Package::anyevent_write_type $handle, @args
1022 1046
1023This function (not method) lets you add your own types to C<push_write>. 1047Instead of one of the predefined types, you can also specify the name of
1048a package. AnyEvent will try to load the package and then expects to find
1049a function named C<anyevent_write_type> inside. If it isn't found, it
1050progressively tries to load the parent package until it either finds the
1051function (good) or runs out of packages (bad).
1052
1024Whenever the given C<type> is used, C<push_write> will invoke the code 1053Whenever the given C<type> is used, C<push_write> will the function with
1025reference with the handle object and the remaining arguments. 1054the handle object and the remaining arguments.
1026 1055
1027The code reference is supposed to return a single octet string that will 1056The function is supposed to return a single octet string that will be
1028be appended to the write buffer. 1057appended to the write buffer, so you cna mentally treat this function as a
1058"arguments to on-the-wire-format" converter.
1029 1059
1030Note that this is a function, and all types registered this way will be 1060Example: implement a custom write type C<join> that joins the remaining
1031global, so try to use unique names. 1061arguments using the first one.
1062
1063 $handle->push_write (My::Type => " ", 1,2,3);
1064
1065 # uses the following package, which can be defined in the "My::Type" or in
1066 # the "My" modules to be auto-loaded, or just about anywhere when the
1067 # My::Type::anyevent_write_type is defined before invoking it.
1068
1069 package My::Type;
1070
1071 sub anyevent_write_type {
1072 my ($handle, $delim, @args) = @_;
1073
1074 join $delim, @args
1075 }
1032 1076
1033=cut 1077=cut
1034 1078
1035############################################################################# 1079#############################################################################
1036 1080
… …
1255 my $cb = pop; 1299 my $cb = pop;
1256 1300
1257 if (@_) { 1301 if (@_) {
1258 my $type = shift; 1302 my $type = shift;
1259 1303
1304 $cb = ($RH{$type} ||= _load_func "$type\::anyevent_read_type"
1260 $cb = ($RH{$type} or Carp::croak "unsupported type passed to AnyEvent::Handle::push_read") 1305 or Carp::croak "unsupported/unloadable type '$type' passed to AnyEvent::Handle::push_read")
1261 ->($self, $cb, @_); 1306 ->($self, $cb, @_);
1262 } 1307 }
1263 1308
1264 push @{ $self->{_queue} }, $cb; 1309 push @{ $self->{_queue} }, $cb;
1265 $self->_drain_rbuf; 1310 $self->_drain_rbuf;
… …
1284 1329
1285=item $handle->unshift_read (type => @args, $cb) 1330=item $handle->unshift_read (type => @args, $cb)
1286 1331
1287Instead of providing a callback that parses the data itself you can chose 1332Instead of providing a callback that parses the data itself you can chose
1288between a number of predefined parsing formats, for chunks of data, lines 1333between a number of predefined parsing formats, for chunks of data, lines
1289etc. 1334etc. You can also specify the (fully qualified) name of a package, in
1335which case AnyEvent tries to load the package and then expects to find the
1336C<anyevent_read_type> function inside (see "custom read types", below).
1290 1337
1291Predefined types are (if you have ideas for additional types, feel free to 1338Predefined types are (if you have ideas for additional types, feel free to
1292drop by and tell us): 1339drop by and tell us):
1293 1340
1294=over 4 1341=over 4
… …
1613 } 1660 }
1614}; 1661};
1615 1662
1616=back 1663=back
1617 1664
1618=item AnyEvent::Handle::register_read_type type => $coderef->($handle, $cb, @args) 1665=item custom read types - Package::anyevent_read_type $handle, $cb, @args
1619 1666
1620This function (not method) lets you add your own types to C<push_read>. 1667Instead of one of the predefined types, you can also specify the name
1668of a package. AnyEvent will try to load the package and then expects to
1669find a function named C<anyevent_read_type> inside. If it isn't found, it
1670progressively tries to load the parent package until it either finds the
1671function (good) or runs out of packages (bad).
1621 1672
1622Whenever the given C<type> is used, C<push_read> will invoke the code 1673Whenever this type is used, C<push_read> will invoke the function with the
1623reference with the handle object, the callback and the remaining 1674handle object, the original callback and the remaining arguments.
1624arguments.
1625 1675
1626The code reference is supposed to return a callback (usually a closure) 1676The function is supposed to return a callback (usually a closure) that
1627that works as a plain read callback (see C<< ->push_read ($cb) >>). 1677works as a plain read callback (see C<< ->push_read ($cb) >>), so you can
1678mentally treat the function as a "configurable read type to read callback"
1679converter.
1628 1680
1629It should invoke the passed callback when it is done reading (remember to 1681It should invoke the original callback when it is done reading (remember
1630pass C<$handle> as first argument as all other callbacks do that). 1682to pass C<$handle> as first argument as all other callbacks do that,
1683although there is no strict requirement on this).
1631 1684
1632Note that this is a function, and all types registered this way will be
1633global, so try to use unique names.
1634
1635For examples, see the source of this module (F<perldoc -m AnyEvent::Handle>, 1685For examples, see the source of this module (F<perldoc -m
1636search for C<register_read_type>)). 1686AnyEvent::Handle>, search for C<register_read_type>)).
1637 1687
1638=item $handle->stop_read 1688=item $handle->stop_read
1639 1689
1640=item $handle->start_read 1690=item $handle->start_read
1641 1691

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines