File Coverage

blib/lib/Thrift/XS.pm
Criterion Covered Total %
statement 12 12 100.0
branch n/a
condition n/a
subroutine 4 4 100.0
pod n/a
total 16 16 100.0


line stmt bran cond sub pod time code
1             package Thrift::XS;
2              
3 4     4   536790 use strict;
  4         9  
  4         173  
4              
5 4     4   2041 use Thrift::XS::MemoryBuffer;
  4         13  
  4         118  
6 4     4   1934 use Thrift::XS::BinaryProtocol;
  4         13  
  4         103  
7 4     4   1861 use Thrift::XS::CompactProtocol;
  4         15  
  4         344  
8              
9             our $VERSION = '1.10';
10              
11             require XSLoader;
12             XSLoader::load('Thrift::XS', $VERSION);
13              
14             1;
15              
16             __END__
17              
18             =head1 NAME
19              
20             Thrift::XS - Faster Thrift binary protocol encoding and decoding
21              
22             =head1 SYNOPSIS
23              
24             use Thrift;
25             use Thrift::Socket;
26             use Thrift::FramedTransport;
27             use Thrift::XS::BinaryProtocol;
28             use MyThriftInterface;
29            
30             my $socket = Thrift::Socket->new( $host, $port );
31             my $transport = Thrift::FramedTransport->new($socket);
32             my $protocol = Thrift::XS::BinaryProtocol->new($transport);
33             my $client = MyThriftInterface->new($protocol);
34            
35             $transport->open;
36            
37             $client->api_call( @args );
38            
39             =head1 DESCRIPTION
40              
41             Thrift::XS provides faster versions of Thrift::BinaryProtocol and
42             Thrift::MemoryBuffer.
43              
44             Thrift compact protocol support is also available, just replace
45             Thrift::XS::BinaryProtocol with Thrift::XS::CompactProtocol.
46              
47             To use, simply replace your Thrift initialization code with the appropriate
48             Thrift::XS version.
49              
50             =head1 SPEED
51              
52             For the best performance, you need to use a custom socket layer and both
53             L<Thrift::XS::MemoryBuffer> and one of L<Thrift::XS::BinaryProtocol> or
54             L<Thrift::XS::CompactProtocol>. If using the standard BufferedTransport,
55             FramedTransport, or HttpClient modules, performance will not be as good
56             as it could be. In particular, HttpClient is incredibly bad, making a lot of
57             very small (1-4 byte) sysread() and print() calls. A future version of this
58             module will probably provide XS implementations of these other modules to
59             help with this problem.
60              
61             Here is a breakdown of the performance improvements of the various low-level
62             methods. A given Thrift API call will make many write and read method calls,
63             so your results will be some average of these numbers. For detailed numbers
64             and to run your own benchmarks, see the bench/bench.pl script.
65              
66             XS::MemoryBuffer write + read: 6x faster
67            
68             XS::BinaryProtocol
69             writeMessageBegin + readMessageBegin: 12.0x
70             complex struct/field write+read: 6.6x
71             writeMapBegin + readMapBegin: 24.0x
72             writeListBegin + readListBegin: 20.0x
73             writeSetBegin + readSetBegin: 21.0x
74             writeBool + readBool: 13.5x
75             writeByte + readByte: 13.9x
76             writeI16 + readI16: 14.4x
77             writeI32 + readI32: 12.9x
78             writeI64 + readI64: 29.4x
79             writeDouble + readDouble: 13.5x
80             writeString + readString: 7.5x
81            
82             XS::CompactProtocol
83             writeMessageBegin + readMessageBegin: 11.6x
84             complex struct/field write+read: 6.2x
85             writeMapBegin + readMapBegin: 18.7x
86             writeListBegin + readListBegin: 14.1x
87             writeSetBegin + readSetBegin: 13.3x
88             writeBool + readBool: 13.2x
89             writeByte + readByte: 13.9x
90             writeI16 + readI16: 9.0x
91             writeI32 + readI32: 7.5x
92             writeI64 + readI64: 10.0x
93             writeDouble + readDouble: 13.5x
94             writeString + readString: 7.4x
95              
96             =head1 THANKS
97              
98             Wang Lam, E<lt>wlam@kosmix.comE<gt>, for patches and additional tests.
99              
100             =head1 SEE ALSO
101              
102             Thrift Home L<http://thrift.apache.org/>
103              
104             Thrift Perl code L<http://svn.apache.org/repos/asf/thrift/trunk/lib/perl/>
105              
106             L<AnyEvent::Cassandra>, example usage of this module. This module is not yet
107             on CPAN, but will be available soon.
108              
109             =head1 AUTHOR
110              
111             Andy Grundman, E<lt>andy@hybridized.orgE<gt>
112              
113             =head1 COPYRIGHT AND LICENSE
114              
115             Copyright 2011 Andy Grundman
116              
117             Licensed under the Apache License, Version 2.0 (the "License");
118             you may not use this file except in compliance with the License.
119             You may obtain a copy of the License at
120              
121             http://www.apache.org/licenses/LICENSE-2.0
122              
123             Unless required by applicable law or agreed to in writing, software
124             distributed under the License is distributed on an "AS IS" BASIS,
125             WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
126             See the License for the specific language governing permissions and
127             limitations under the License.
128              
129             =cut