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.237 by root, Tue Jul 30 23:14:32 2013 UTC vs.
Revision 1.238 by root, Tue Dec 10 15:54:51 2013 UTC

… …
496callback. 496callback.
497 497
498This callback will only be called on TLS shutdowns, not when the 498This callback will only be called on TLS shutdowns, not when the
499underlying handle signals EOF. 499underlying handle signals EOF.
500 500
501=item json => JSON or JSON::XS object 501=item json => L<JSON> or L<JSON::XS> object
502 502
503This is the json coder object used by the C<json> read and write types. 503This is the json coder object used by the C<json> read and write types.
504 504
505If you don't supply it, then AnyEvent::Handle will create and use a 505If you don't supply it, then AnyEvent::Handle will create and use a
506suitable one (on demand), which will write and expect UTF-8 encoded JSON 506suitable one (on demand), which will write and expect UTF-8 encoded JSON
507texts. 507texts.
508 508
509Note that you are responsible to depend on the JSON module if you want to 509Note that you are responsible to depend on the L<JSON> module if you want
510use this functionality, as AnyEvent does not have a dependency itself. 510to use this functionality, as AnyEvent does not have a dependency on it
511itself.
512
513=item cbor => L<CBOR::XS> object
514
515This is the cbor coder object used by the C<cbor> read and write types.
516
517If you don't supply it, then AnyEvent::Handle will create and use a
518suitable one (on demand), which will write CBOR without using extensions,
519if possible. texts.
520
521Note that you are responsible to depend on the L<CBOR::XS> module if you
522want to use this functionality, as AnyEvent does not have a dependency on
523it itself.
511 524
512=back 525=back
513 526
514=cut 527=cut
515 528
… …
1053 1066
1054The generated JSON text is guaranteed not to contain any newlines: While 1067The generated JSON text is guaranteed not to contain any newlines: While
1055this module doesn't need delimiters after or between JSON texts to be 1068this module doesn't need delimiters after or between JSON texts to be
1056able to read them, many other languages depend on that. 1069able to read them, many other languages depend on that.
1057 1070
1058A simple RPC protocol that interoperates easily with others is to send 1071A simple RPC protocol that interoperates easily with other languages is
1059JSON arrays (or objects, although arrays are usually the better choice as 1072to send JSON arrays (or objects, although arrays are usually the better
1060they mimic how function argument passing works) and a newline after each 1073choice as they mimic how function argument passing works) and a newline
1061JSON text: 1074after each JSON text:
1062 1075
1063 $handle->push_write (json => ["method", "arg1", "arg2"]); # whatever 1076 $handle->push_write (json => ["method", "arg1", "arg2"]); # whatever
1064 $handle->push_write ("\012"); 1077 $handle->push_write ("\012");
1065 1078
1066An AnyEvent::Handle receiver would simply use the C<json> read type and 1079An AnyEvent::Handle receiver would simply use the C<json> read type and
… …
1069 $handle->push_read (json => sub { my $array = $_[1]; ... }); 1082 $handle->push_read (json => sub { my $array = $_[1]; ... });
1070 1083
1071Other languages could read single lines terminated by a newline and pass 1084Other languages could read single lines terminated by a newline and pass
1072this line into their JSON decoder of choice. 1085this line into their JSON decoder of choice.
1073 1086
1087=item cbor => $perl_scalar
1088
1089Encodes the given scalar into a CBOR value. Unless you provide your own
1090L<CBOR::XS> object, this means it will be encoded to a CBOR string not
1091using any extensions, if possible.
1092
1093CBOR values are self-delimiting, so you can write CBOR at one end of
1094a handle and read them at the other end without using any additional
1095framing.
1096
1097A simple nd very very fast RPC protocol that interoperates with
1098other languages is to send CBOR and receive CBOR values (arrays are
1099recommended):
1100
1101 $handle->push_write (cbor => ["method", "arg1", "arg2"]); # whatever
1102
1103An AnyEvent::Handle receiver would simply use the C<cbor> read type:
1104
1105 $handle->push_read (cbor => sub { my $array = $_[1]; ... });
1106
1074=cut 1107=cut
1075 1108
1076sub json_coder() { 1109sub json_coder() {
1077 eval { require JSON::XS; JSON::XS->new->utf8 } 1110 eval { require JSON::XS; JSON::XS->new->utf8 }
1078 || do { require JSON; JSON->new->utf8 } 1111 || do { require JSON; JSON->new->utf8 }
1079} 1112}
1080 1113
1081register_write_type json => sub { 1114register_write_type json => sub {
1082 my ($self, $ref) = @_; 1115 my ($self, $ref) = @_;
1083 1116
1084 my $json = $self->{json} ||= json_coder; 1117 ($self->{json} ||= json_coder)
1085
1086 $json->encode ($ref) 1118 ->encode ($ref)
1119};
1120
1121sub cbor_coder() {
1122 require CBOR::XS;
1123 CBOR::XS->new
1124}
1125
1126register_write_type cbor => sub {
1127 my ($self, $scalar) = @_;
1128
1129 ($self->{cbor} ||= cbor_coder)
1130 ->encode ($scalar)
1087}; 1131};
1088 1132
1089=item storable => $reference 1133=item storable => $reference
1090 1134
1091Freezes the given reference using L<Storable> and writes it to the 1135Freezes the given reference using L<Storable> and writes it to the
… …
1684 my ($self, $cb) = @_; 1728 my ($self, $cb) = @_;
1685 1729
1686 my $json = $self->{json} ||= json_coder; 1730 my $json = $self->{json} ||= json_coder;
1687 1731
1688 my $data; 1732 my $data;
1689 my $rbuf = \$self->{rbuf};
1690 1733
1691 sub { 1734 sub {
1692 my $ref = eval { $json->incr_parse ($_[0]{rbuf}) }; 1735 my $ref = eval { $json->incr_parse ($_[0]{rbuf}) };
1693 1736
1694 if ($ref) { 1737 if ($ref) {
… …
1708 1751
1709 () 1752 ()
1710 } else { 1753 } else {
1711 $_[0]{rbuf} = ""; 1754 $_[0]{rbuf} = "";
1712 1755
1756 ()
1757 }
1758 }
1759};
1760
1761=item cbor => $cb->($handle, $scalar)
1762
1763Reads a CBOR value, decodes it and passes it to the callback. When a parse
1764error occurs, an C<EBADMSG> error will be raised.
1765
1766If a L<CBOR::XS> object was passed to the constructor, then that will be
1767used for the final decode, otherwise it will create a CBOR coder without
1768enabling any options.
1769
1770You have to provide a dependency to L<CBOR::XS> on your own: this module
1771will load the L<CBOR::XS> module, but AnyEvent does not depend on it
1772itself.
1773
1774Since CBOR values are fully self-delimiting, the C<cbor> read and write
1775types are an ideal simple RPC protocol: just exchange CBOR datagrams. See
1776the C<cbor> write type description, above, for an actual example.
1777
1778=cut
1779
1780register_read_type cbor => sub {
1781 my ($self, $cb) = @_;
1782
1783 my $cbor = $self->{cbor} ||= cbor_coder;
1784
1785 my $data;
1786
1787 sub {
1788 my (@value) = eval { $cbor->incr_parse ($_[0]{rbuf}) };
1789
1790 if (@value) {
1791 $cb->($_[0], @value);
1792
1793 1
1794 } elsif ($@) {
1795 # error case
1796 $cbor->incr_reset;
1797
1798 $_[0]->_error (Errno::EBADMSG);
1799
1800 ()
1801 } else {
1713 () 1802 ()
1714 } 1803 }
1715 } 1804 }
1716}; 1805};
1717 1806

Diff Legend

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