[ViewVC] Diff of: cvs/AnyEvent/lib/AnyEvent/Handle.pm

Comparing AnyEvent/lib/AnyEvent/Handle.pm (file contents):
Revision 1.9 by root, Fri May 2 16:07:46 2008 UTC vs.
Revision 1.10 by root, Sat May 3 12:17:35 2008 UTC

…		…
70	The filehandle this L<AnyEvent::Handle> object will operate on.	70	The filehandle this L<AnyEvent::Handle> object will operate on.
71		71
72	NOTE: The filehandle will be set to non-blocking (using	72	NOTE: The filehandle will be set to non-blocking (using
73	AnyEvent::Util::fh_nonblocking).	73	AnyEvent::Util::fh_nonblocking).
74		74
75	=item on_error => $cb->($self) [MANDATORY]	75	=item on_eof => $cb->($self) [MANDATORY]
76		76
		77	Set the callback to be called on EOF.
		78
		79	=item on_error => $cb->($self)
		80
77	This is the fatal error callback, that is called when a fatal error ocurs,	81	This is the fatal error callback, that is called when, well, a fatal error
78	such as not being able to resolve the hostname, failure to connect or a	82	ocurs, such as not being able to resolve the hostname, failure to connect
79	read error.	83	or a read error.
80		84
81	The object will not be in a usable state when this callback has been	85	The object will not be in a usable state when this callback has been
82	called.	86	called.
83		87
84	On callback entrance, the value of C<$!> contains the opertaing system	88	On callback entrance, the value of C<$!> contains the operating system
85	error (or C<ENOSPC> or C<EPIPE>).	89	error (or C<ENOSPC> or C<EPIPE>).
86		90
87	=item on_eof => $cb->($self) [MANDATORY]	91	While not mandatory, it is I<highly> recommended to set this callback, as
88		92	you will not be notified of errors otherwise. The default simply calls
89	Set the callback to be called on EOF.	93	die.
90		94
91	=item on_read => $cb->($self)	95	=item on_read => $cb->($self)
92		96
93	This sets the default read callback, which is called when data arrives	97	This sets the default read callback, which is called when data arrives
94	and no read request is in the queue. If the read callback is C<undef>	98	and no read request is in the queue.
95	or has never been set, than AnyEvent::Handle will cease reading from the
96	filehandle.
97		99
98	To access (and remove data from) the read buffer, use the C<< ->rbuf >>	100	To access (and remove data from) the read buffer, use the C<< ->rbuf >>
99	method or acces sthe C<$self->{rbuf}> member directly.	101	method or acces sthe C<$self->{rbuf}> member directly.
100		102
101	When an EOF condition is detected then AnyEvent::Handle will first try to	103	When an EOF condition is detected then AnyEvent::Handle will first try to
…		…
144		146
145	$self->{fh} or Carp::croak "mandatory argument fh is missing";	147	$self->{fh} or Carp::croak "mandatory argument fh is missing";
146		148
147	AnyEvent::Util::fh_nonblocking $self->{fh}, 1;	149	AnyEvent::Util::fh_nonblocking $self->{fh}, 1;
148		150
149	$self->on_error ((delete $self->{on_error}) or Carp::croak "mandatory argument on_error is missing");
150	$self->on_eof ((delete $self->{on_eof} ) or Carp::croak "mandatory argument on_eof is missing");	151	$self->on_eof ((delete $self->{on_eof} ) or Carp::croak "mandatory argument on_eof is missing");
151		152
		153	$self->on_error (delete $self->{on_error}) if $self->{on_error};
152	$self->on_drain (delete $self->{on_drain}) if $self->{on_drain};	154	$self->on_drain (delete $self->{on_drain}) if $self->{on_drain};
153	$self->on_read (delete $self->{on_read} ) if $self->{on_read};	155	$self->on_read (delete $self->{on_read} ) if $self->{on_read};
		156
		157	$self->start_read;
154		158
155	$self	159	$self
156	}	160	}
157		161
158	sub _shutdown {	162	sub _shutdown {
…		…
169	{	173	{
170	local $!;	174	local $!;
171	$self->_shutdown;	175	$self->_shutdown;
172	}	176	}
173		177
		178	if ($self->{on_error}) {
174	$self->{on_error}($self);	179	$self->{on_error}($self);
		180	} else {
		181	die "AnyEvent::Handle uncaught fatal error: $!";
		182	}
175	}	183	}
176		184
177	=item $fh = $handle->fh	185	=item $fh = $handle->fh
178		186
179	This method returns the filehandle of the L<AnyEvent::Handle> object.	187	This method returns the filehandle of the L<AnyEvent::Handle> object.
…		…
349	...	357	...
350	});	358	});
351		359
352	=over 4	360	=over 4
353		361
		362	=cut
		363
354	sub _drain_rbuf {	364	sub _drain_rbuf {
355	my ($self) = @_;	365	my ($self) = @_;
356		366
357	return if exists $self->{in_drain};	367	return if exists $self->{in_drain};
358	local $self->{in_drain} = 1;	368	local $self->{in_drain} = 1;
359		369
360	while (my $len = length $self->{rbuf}) {	370	while (my $len = length $self->{rbuf}) {
361	no strict 'refs';	371	no strict 'refs';
362	if (@{ $self->{queue} }) {	372	if (my $cb = shift @{ $self->{queue} }) {
363	if ($self->{queue}[0]($self)) {	373	if (!$cb->($self)) {
364	shift @{ $self->{queue} };
365	} elsif ($self->{eof}) {	374	if ($self->{eof}) {
366	# no progress can be made (not enough data and no data forthcoming)	375	# no progress can be made (not enough data and no data forthcoming)
367	$! = &Errno::EPIPE; return $self->error;	376	$! = &Errno::EPIPE; return $self->error;
368	} else {	377	}
		378
		379	unshift @{ $self->{queue} }, $cb;
369	return;	380	return;
370	}	381	}
371	} elsif ($self->{on_read}) {	382	} elsif ($self->{on_read}) {
372	$self->{on_read}($self);	383	$self->{on_read}($self);
373		384
…		…
403		414
404	sub on_read {	415	sub on_read {
405	my ($self, $cb) = @_;	416	my ($self, $cb) = @_;
406		417
407	$self->{on_read} = $cb;	418	$self->{on_read} = $cb;
		419	}
		420
		421	=item $handle->rbuf
		422
		423	Returns the read buffer (as a modifiable lvalue).
		424
		425	You can access the read buffer directly as the C<< ->{rbuf} >> member, if
		426	you want.
		427
		428	NOTE: The read buffer should only be used or modified if the C<on_read>,
		429	C<push_read> or C<unshift_read> methods are used. The other read methods
		430	automatically manage the read buffer.
		431
		432	=cut
		433
		434	sub rbuf : lvalue {
		435	$_[0]{rbuf}
		436	}
		437
		438	=item $handle->push_read ($cb)
		439
		440	=item $handle->unshift_read ($cb)
		441
		442	Append the given callback to the end of the queue (C<push_read>) or
		443	prepend it (C<unshift_read>).
		444
		445	The callback is called each time some additional read data arrives.
		446
		447	It must check wether enough data is in the read buffer already.
		448
		449	If not enough data is available, it must return the empty list or a false
		450	value, in which case it will be called repeatedly until enough data is
		451	available (or an error condition is detected).
		452
		453	If enough data was available, then the callback must remove all data it is
		454	interested in (which can be none at all) and return a true value. After returning
		455	true, it will be removed from the queue.
		456
		457	=cut
		458
		459	sub push_read {
		460	my ($self, $cb) = @_;
		461
		462	push @{ $self->{queue} }, $cb;
		463	$self->_drain_rbuf;
		464	}
		465
		466	sub unshift_read {
		467	my ($self, $cb) = @_;
		468
		469	push @{ $self->{queue} }, $cb;
		470	$self->_drain_rbuf;
		471	}
		472
		473	=item $handle->push_read_chunk ($len, $cb->($self, $data))
		474
		475	=item $handle->unshift_read_chunk ($len, $cb->($self, $data))
		476
		477	Append the given callback to the end of the queue (C<push_read_chunk>) or
		478	prepend it (C<unshift_read_chunk>).
		479
		480	The callback will be called only once C<$len> bytes have been read, and
		481	these C<$len> bytes will be passed to the callback.
		482
		483	=cut
		484
		485	sub _read_chunk($$) {
		486	my ($self, $len, $cb) = @_;
		487
		488	sub {
		489	$len <= length $_[0]{rbuf} or return;
		490	$cb->($self, $_[0], substr $_[0]{rbuf}, 0, $len, "");
		491	1
		492	}
		493	}
		494
		495	sub push_read_chunk {
		496	$_[0]->push_read (&_read_chunk);
		497	}
		498
		499
		500	sub unshift_read_chunk {
		501	$_[0]->unshift_read (&_read_chunk);
		502	}
		503
		504	=item $handle->push_read_line ([$eol, ]$cb->($self, $line, $eol))
		505
		506	=item $handle->unshift_read_line ([$eol, ]$cb->($self, $line, $eol))
		507
		508	Append the given callback to the end of the queue (C<push_read_line>) or
		509	prepend it (C<unshift_read_line>).
		510
		511	The callback will be called only once a full line (including the end of
		512	line marker, C<$eol>) has been read. This line (excluding the end of line
		513	marker) will be passed to the callback as second argument (C<$line>), and
		514	the end of line marker as the third argument (C<$eol>).
		515
		516	The end of line marker, C<$eol>, can be either a string, in which case it
		517	will be interpreted as a fixed record end marker, or it can be a regex
		518	object (e.g. created by C<qr>), in which case it is interpreted as a
		519	regular expression.
		520
		521	The end of line marker argument C<$eol> is optional, if it is missing (NOT
		522	undef), then C<qr\|\015?\012\|> is used (which is good for most internet
		523	protocols).
		524
		525	Partial lines at the end of the stream will never be returned, as they are
		526	not marked by the end of line marker.
		527
		528	=cut
		529
		530	sub _read_line($$) {
		531	my $self = shift;
		532	my $cb = pop;
		533	my $eol = @_ ? shift : qr\|(\015?\012)\|;
		534	my $pos;
		535
		536	$eol = qr\|(\Q$eol\E)\| unless ref $eol;
		537	$eol = qr\|^(.*?)($eol)\|;
		538
		539	sub {
		540	$_[0]{rbuf} =~ s/$eol// or return;
		541
		542	$cb->($self, $1, $2);
		543	1
		544	}
		545	}
		546
		547	sub push_read_line {
		548	$_[0]->push_read (&_read_line);
		549	}
		550
		551	sub unshift_read_line {
		552	$_[0]->unshift_read (&_read_line);
		553	}
		554
		555	=item $handle->stop_read
		556
		557	=item $handle->start_read
		558
		559	In rare cases you actually do not want to read anything form the
		560	socket. In this case you can call C<stop_read>. Neither C<on_read> no
		561	any queued callbacks will be executed then. To start readign again, call
		562	C<start_read>.
		563
		564	=cut
		565
		566	sub stop_read {
		567	my ($self) = @_;
		568
		569	delete $self->{rw};
		570	}
		571
		572	sub start_read {
		573	my ($self) = @_;
408		574
409	unless ($self->{rw} \|\| $self->{eof}) {	575	unless ($self->{rw} \|\| $self->{eof}) {
410	Scalar::Util::weaken $self;	576	Scalar::Util::weaken $self;
411		577
412	$self->{rw} = AnyEvent->io (fh => $self->{fh}, poll => "r", cb => sub {	578	$self->{rw} = AnyEvent->io (fh => $self->{fh}, poll => "r", cb => sub {
…		…
430	$self->_drain_rbuf;	596	$self->_drain_rbuf;
431	});	597	});
432	}	598	}
433	}	599	}
434		600
435	=item $handle->rbuf
436
437	Returns the read buffer (as a modifiable lvalue).
438
439	You can access the read buffer directly as the C<< ->{rbuf} >> member, if
440	you want.
441
442	NOTE: The read buffer should only be used or modified if the C<on_read>,
443	C<push_read> or C<unshift_read> methods are used. The other read methods
444	automatically manage the read buffer.
445
446	=cut
447
448	sub rbuf : lvalue {
449	$_[0]{rbuf}
450	}
451
452	=item $handle->push_read ($cb)
453
454	=item $handle->unshift_read ($cb)
455
456	Append the given callback to the end of the queue (C<push_read>) or
457	prepend it (C<unshift_read>).
458
459	The callback is called each time some additional read data arrives.
460
461	It must check wether enough data is in the read buffer already.
462
463	If not enough data is available, it must return the empty list or a false
464	value, in which case it will be called repeatedly until enough data is
465	available (or an error condition is detected).
466
467	If enough data was available, then the callback must remove all data it is
468	interested in (which can be none at all) and return a true value. After returning
469	true, it will be removed from the queue.
470
471	=cut
472
473	sub push_read {
474	my ($self, $cb) = @_;
475
476	push @{ $self->{queue} }, $cb;
477	$self->_drain_rbuf;
478	}
479
480	sub unshift_read {
481	my ($self, $cb) = @_;
482
483	push @{ $self->{queue} }, $cb;
484	$self->_drain_rbuf;
485	}
486
487	=item $handle->push_read_chunk ($len, $cb->($self, $data))
488
489	=item $handle->unshift_read_chunk ($len, $cb->($self, $data))
490
491	Append the given callback to the end of the queue (C<push_read_chunk>) or
492	prepend it (C<unshift_read_chunk>).
493
494	The callback will be called only once C<$len> bytes have been read, and
495	these C<$len> bytes will be passed to the callback.
496
497	=cut
498
499	sub _read_chunk($$) {
500	my ($len, $cb) = @_;
501
502	sub {
503	$len <= length $_[0]{rbuf} or return;
504	$cb->($_[0], substr $_[0]{rbuf}, 0, $len, "");
505	1
506	}
507	}
508
509	sub push_read_chunk {
510	my ($self, $len, $cb) = @_;
511
512	$self->push_read (_read_chunk $len, $cb);
513	}
514
515
516	sub unshift_read_chunk {
517	my ($self, $len, $cb) = @_;
518
519	$self->unshift_read (_read_chunk $len, $cb);
520	}
521
522	=item $handle->push_read_line ([$eol, ]$cb->($self, $line, $eol))
523
524	=item $handle->unshift_read_line ([$eol, ]$cb->($self, $line, $eol))
525
526	Append the given callback to the end of the queue (C<push_read_line>) or
527	prepend it (C<unshift_read_line>).
528
529	The callback will be called only once a full line (including the end of
530	line marker, C<$eol>) has been read. This line (excluding the end of line
531	marker) will be passed to the callback as second argument (C<$line>), and
532	the end of line marker as the third argument (C<$eol>).
533
534	The end of line marker, C<$eol>, can be either a string, in which case it
535	will be interpreted as a fixed record end marker, or it can be a regex
536	object (e.g. created by C<qr>), in which case it is interpreted as a
537	regular expression.
538
539	The end of line marker argument C<$eol> is optional, if it is missing (NOT
540	undef), then C<qr\|\015?\012\|> is used (which is good for most internet
541	protocols).
542
543	Partial lines at the end of the stream will never be returned, as they are
544	not marked by the end of line marker.
545
546	=cut
547
548	sub _read_line($$) {
549	my $cb = pop;
550	my $eol = @_ ? shift : qr\|(\015?\012)\|;
551	my $pos;
552
553	$eol = qr\|(\Q$eol\E)\| unless ref $eol;
554	$eol = qr\|^(.*?)($eol)\|;
555
556	sub {
557	$_[0]{rbuf} =~ s/$eol// or return;
558
559	$cb->($1, $2);
560	1
561	}
562	}
563
564	sub push_read_line {
565	my $self = shift;
566
567	$self->push_read (&_read_line);
568	}
569
570	sub unshift_read_line {
571	my $self = shift;
572
573	$self->unshift_read (&_read_line);
574	}
575
576	=back	601	=back
577		602
578	=head1 AUTHOR	603	=head1 AUTHOR
579		604
580	Robin Redeker C<< <elmex at ta-sa.org> >>, Marc Lehmann <schmorp@schmorp.de>.	605	Robin Redeker C<< <elmex at ta-sa.org> >>, Marc Lehmann <schmorp@schmorp.de>.

Diff Legend

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

Comparing AnyEvent/lib/AnyEvent/Handle.pm (file contents): Revision 1.9 by root, Fri May 2 16:07:46 2008 UTC vs. Revision 1.10 by root, Sat May 3 12:17:35 2008 UTC

Diff Legend

Comparing AnyEvent/lib/AnyEvent/Handle.pm (file contents):
Revision 1.9 by root, Fri May 2 16:07:46 2008 UTC vs.
Revision 1.10 by root, Sat May 3 12:17:35 2008 UTC