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.184 by root, Thu Sep 3 13:14:38 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.
… …
359C<undef>. 375C<undef>.
360 376
361=item tls => "accept" | "connect" | Net::SSLeay::SSL object 377=item tls => "accept" | "connect" | Net::SSLeay::SSL object
362 378
363When this parameter is given, it enables TLS (SSL) mode, that means 379When this parameter is given, it enables TLS (SSL) mode, that means
364AnyEvent 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
365established and will transparently encrypt/decrypt data afterwards. 381established and will transparently encrypt/decrypt data afterwards.
366 382
367All TLS protocol errors will be signalled as C<EPROTO>, with an 383All TLS protocol errors will be signalled as C<EPROTO>, with an
368appropriate error message. 384appropriate error message.
369 385
… …
871 }; 887 };
872} 888}
873 889
874our %WH; 890our %WH;
875 891
892# deprecated
876sub register_write_type($$) { 893sub register_write_type($$) {
877 $WH{$_[0]} = $_[1]; 894 $WH{$_[0]} = $_[1];
878} 895}
879 896
880sub push_write { 897sub push_write {
881 my $self = shift; 898 my $self = shift;
882 899
883 if (@_ > 1) { 900 if (@_ > 1) {
884 my $type = shift; 901 my $type = shift;
885 902
903 @_ = ($WH{$type} ||= _load_func "$type\::anyevent_write_type"
886 @_ = ($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")
887 ->($self, @_); 905 ->($self, @_);
888 } 906 }
889 907
890 if ($self->{tls}) { 908 if ($self->{tls}) {
891 $self->{_tls_wbuf} .= $_[0]; 909 $self->{_tls_wbuf} .= $_[0];
… …
896 } 914 }
897} 915}
898 916
899=item $handle->push_write (type => @args) 917=item $handle->push_write (type => @args)
900 918
901Instead of formatting your data yourself, you can also let this module do 919Instead of formatting your data yourself, you can also let this module
902the 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).
903 924
904Predefined 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
905drop by and tell us): 926drop by and tell us):
906 927
907=over 4 928=over 4
… …
1019 1040
1020 delete $self->{low_water_mark}; 1041 delete $self->{low_water_mark};
1021 $self->on_drain (sub { shutdown $_[0]{fh}, 1 }); 1042 $self->on_drain (sub { shutdown $_[0]{fh}, 1 });
1022} 1043}
1023 1044
1024=item AnyEvent::Handle::register_write_type type => $coderef->($handle, @args) 1045=item custom write types - Package::anyevent_write_type $handle, @args
1025 1046
1026This 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
1027Whenever 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
1028reference with the handle object and the remaining arguments. 1054the handle object and the remaining arguments.
1029 1055
1030The 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
1031be 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.
1032 1059
1033Note 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
1034global, 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 }
1035 1076
1036=cut 1077=cut
1037 1078
1038############################################################################# 1079#############################################################################
1039 1080
… …
1258 my $cb = pop; 1299 my $cb = pop;
1259 1300
1260 if (@_) { 1301 if (@_) {
1261 my $type = shift; 1302 my $type = shift;
1262 1303
1304 $cb = ($RH{$type} ||= _load_func "$type\::anyevent_read_type"
1263 $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")
1264 ->($self, $cb, @_); 1306 ->($self, $cb, @_);
1265 } 1307 }
1266 1308
1267 push @{ $self->{_queue} }, $cb; 1309 push @{ $self->{_queue} }, $cb;
1268 $self->_drain_rbuf; 1310 $self->_drain_rbuf;
… …
1287 1329
1288=item $handle->unshift_read (type => @args, $cb) 1330=item $handle->unshift_read (type => @args, $cb)
1289 1331
1290Instead 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
1291between a number of predefined parsing formats, for chunks of data, lines 1333between a number of predefined parsing formats, for chunks of data, lines
1292etc. 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).
1293 1337
1294Predefined 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
1295drop by and tell us): 1339drop by and tell us):
1296 1340
1297=over 4 1341=over 4
… …
1616 } 1660 }
1617}; 1661};
1618 1662
1619=back 1663=back
1620 1664
1621=item AnyEvent::Handle::register_read_type type => $coderef->($handle, $cb, @args) 1665=item custom read types - Package::anyevent_read_type $handle, $cb, @args
1622 1666
1623This 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).
1624 1672
1625Whenever 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
1626reference with the handle object, the callback and the remaining 1674handle object, the original callback and the remaining arguments.
1627arguments.
1628 1675
1629The code reference is supposed to return a callback (usually a closure) 1676The function is supposed to return a callback (usually a closure) that
1630that 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.
1631 1680
1632It should invoke the passed callback when it is done reading (remember to 1681It should invoke the original callback when it is done reading (remember
1633pass 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).
1634 1684
1635Note that this is a function, and all types registered this way will be
1636global, so try to use unique names.
1637
1638For examples, see the source of this module (F<perldoc -m AnyEvent::Handle>, 1685For examples, see the source of this module (F<perldoc -m
1639search for C<register_read_type>)). 1686AnyEvent::Handle>, search for C<register_read_type>)).
1640 1687
1641=item $handle->stop_read 1688=item $handle->stop_read
1642 1689
1643=item $handle->start_read 1690=item $handle->start_read
1644 1691

Diff Legend

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