ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/JSON-XS/XS.pm
(Generate patch)

Comparing JSON-XS/XS.pm (file contents):
Revision 1.46 by root, Mon Jun 25 04:21:14 2007 UTC vs.
Revision 1.50 by root, Mon Jul 2 00:29:38 2007 UTC

… …
9 # exported functions, they croak on error 9 # exported functions, they croak on error
10 # and expect/generate UTF-8 10 # and expect/generate UTF-8
11 11
12 $utf8_encoded_json_text = to_json $perl_hash_or_arrayref; 12 $utf8_encoded_json_text = to_json $perl_hash_or_arrayref;
13 $perl_hash_or_arrayref = from_json $utf8_encoded_json_text; 13 $perl_hash_or_arrayref = from_json $utf8_encoded_json_text;
14
15 # objToJson and jsonToObj aliases to to_json and from_json
16 # are exported for compatibility to the JSON module,
17 # but should not be used in new code.
18 14
19 # OO-interface 15 # OO-interface
20 16
21 $coder = JSON::XS->new->ascii->pretty->allow_nonref; 17 $coder = JSON::XS->new->ascii->pretty->allow_nonref;
22 $pretty_printed_unencoded = $coder->encode ($perl_scalar); 18 $pretty_printed_unencoded = $coder->encode ($perl_scalar);
… …
88use strict; 84use strict;
89 85
90our $VERSION = '1.4'; 86our $VERSION = '1.4';
91our @ISA = qw(Exporter); 87our @ISA = qw(Exporter);
92 88
93our @EXPORT = qw(to_json from_json objToJson jsonToObj); 89our @EXPORT = qw(to_json from_json);
94 90
95use Exporter; 91use Exporter;
96use XSLoader; 92use XSLoader;
97 93
98=head1 FUNCTIONAL INTERFACE 94=head1 FUNCTIONAL INTERFACE
… …
393given character in a string. 389given character in a string.
394 390
395Setting the maximum depth to one disallows any nesting, so that ensures 391Setting the maximum depth to one disallows any nesting, so that ensures
396that the object is only a single hash/object or array. 392that the object is only a single hash/object or array.
397 393
398The argument to C<max_depth> will be rounded up to the next nearest power 394The argument to C<max_depth> will be rounded up to the next highest power
399of two. 395of two. If no argument is given, the highest possible setting will be
396used, which is rarely useful.
397
398See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
399
400=item $json = $json->max_size ([$maximum_string_size])
401
402Set the maximum length a JSON text may have (in bytes) where decoding is
403being attempted. The default is C<0>, meaning no limit. When C<decode>
404is called on a string longer then this number of characters it will not
405attempt to decode the string but throw an exception. This setting has no
406effect on C<encode> (yet).
407
408The argument to C<max_size> will be rounded up to the next B<highest>
409power of two (so may be more than requested). If no argument is given, the
410limit check will be deactivated (same as when C<0> is specified).
400 411
401See SECURITY CONSIDERATIONS, below, for more info on why this is useful. 412See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
402 413
403=item $json_text = $json->encode ($perl_scalar) 414=item $json_text = $json->encode ($perl_scalar)
404 415
… …
696It shows the number of encodes/decodes per second (JSON::XS uses 707It shows the number of encodes/decodes per second (JSON::XS uses
697the functional interface, while JSON::XS/2 uses the OO interface 708the functional interface, while JSON::XS/2 uses the OO interface
698with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables 709with pretty-printing and hashkey sorting enabled, JSON::XS/3 enables
699shrink). Higher is better: 710shrink). Higher is better:
700 711
712 Storable | 15779.925 | 14169.946 |
713 -----------+------------+------------+
701 module | encode | decode | 714 module | encode | decode |
702 -----------|------------|------------| 715 -----------|------------|------------|
703 JSON | 7645.468 | 4208.613 | 716 JSON | 4990.842 | 4088.813 |
704 JSON::DWIW | 40721.398 | 77101.176 | 717 JSON::DWIW | 51653.990 | 71575.154 |
705 JSON::PC | 65948.176 | 78251.940 | 718 JSON::PC | 65948.176 | 74631.744 |
706 JSON::Syck | 22844.793 | 26479.192 | 719 JSON::PP | 8931.652 | 3817.168 |
720 JSON::Syck | 24877.248 | 27776.848 |
707 JSON::XS | 388361.481 | 199728.762 | 721 JSON::XS | 388361.481 | 227951.304 |
708 JSON::XS/2 | 218453.333 | 192399.266 | 722 JSON::XS/2 | 227951.304 | 218453.333 |
709 JSON::XS/3 | 338250.323 | 192399.266 | 723 JSON::XS/3 | 338250.323 | 218453.333 |
710 Storable | 15779.925 | 14169.946 | 724 Storable | 16500.016 | 135300.129 |
711 -----------+------------+------------+ 725 -----------+------------+------------+
712 726
713That is, JSON::XS is about five times faster than JSON::DWIW on encoding, 727That is, JSON::XS is about five times faster than JSON::DWIW on encoding,
714about three times faster on decoding, and over fourty times faster 728about three times faster on decoding, and over fourty times faster
715than JSON, even with pretty-printing and key sorting. It also compares 729than JSON, even with pretty-printing and key sorting. It also compares
… …
718Using a longer test string (roughly 18KB, generated from Yahoo! Locals 732Using a longer test string (roughly 18KB, generated from Yahoo! Locals
719search API (http://nanoref.com/yahooapis/mgPdGg): 733search API (http://nanoref.com/yahooapis/mgPdGg):
720 734
721 module | encode | decode | 735 module | encode | decode |
722 -----------|------------|------------| 736 -----------|------------|------------|
723 JSON | 254.685 | 37.665 | 737 JSON | 55.260 | 34.971 |
724 JSON::DWIW | 843.343 | 1049.731 | 738 JSON::DWIW | 825.228 | 1082.513 |
725 JSON::PC | 3602.116 | 2307.352 | 739 JSON::PC | 3571.444 | 2394.829 |
740 JSON::PP | 210.987 | 32.574 |
726 JSON::Syck | 505.107 | 787.899 | 741 JSON::Syck | 552.551 | 787.544 |
727 JSON::XS | 5747.196 | 3690.220 | 742 JSON::XS | 5780.463 | 4854.519 |
728 JSON::XS/2 | 3968.121 | 3676.634 | 743 JSON::XS/2 | 3869.998 | 4798.975 |
729 JSON::XS/3 | 6105.246 | 3662.508 | 744 JSON::XS/3 | 5862.880 | 4798.975 |
730 Storable | 4417.337 | 5285.161 | 745 Storable | 4445.002 | 5235.027 |
731 -----------+------------+------------+ 746 -----------+------------+------------+
732 747
733Again, JSON::XS leads by far (except for Storable which non-surprisingly 748Again, JSON::XS leads by far (except for Storable which non-surprisingly
734decodes faster). 749decodes faster).
735 750
… …
752Second, you need to avoid resource-starving attacks. That means you should 767Second, you need to avoid resource-starving attacks. That means you should
753limit the size of JSON texts you accept, or make sure then when your 768limit the size of JSON texts you accept, or make sure then when your
754resources run out, thats just fine (e.g. by using a separate process that 769resources run out, thats just fine (e.g. by using a separate process that
755can crash safely). The size of a JSON text in octets or characters is 770can crash safely). The size of a JSON text in octets or characters is
756usually a good indication of the size of the resources required to decode 771usually a good indication of the size of the resources required to decode
757it into a Perl structure. 772it into a Perl structure. While JSON::XS can check the size of the JSON
773text, it might be too late when you already have it in memory, so you
774might want to check the size before you accept the string.
758 775
759Third, JSON::XS recurses using the C stack when decoding objects and 776Third, JSON::XS recurses using the C stack when decoding objects and
760arrays. The C stack is a limited resource: for instance, on my amd64 777arrays. The C stack is a limited resource: for instance, on my amd64
761machine with 8MB of stack size I can decode around 180k nested arrays but 778machine with 8MB of stack size I can decode around 180k nested arrays but
762only 14k nested JSON objects (due to perl itself recursing deeply on croak 779only 14k nested JSON objects (due to perl itself recursing deeply on croak
… …
785still relatively early in its development. If you keep reporting bugs they 802still relatively early in its development. If you keep reporting bugs they
786will be fixed swiftly, though. 803will be fixed swiftly, though.
787 804
788=cut 805=cut
789 806
790our $true = do { bless \(my $dummy = 1), "JSON::XS::Boolean" }; 807our $true = do { bless \(my $dummy = "1"), "JSON::XS::Boolean" };
791our $false = do { bless \(my $dummy = 0), "JSON::XS::Boolean" }; 808our $false = do { bless \(my $dummy = "0"), "JSON::XS::Boolean" };
792 809
793sub true() { $true } 810sub true() { $true }
794sub false() { $false } 811sub false() { $false }
795 812
796sub is_bool($) { 813sub is_bool($) {

Diff Legend

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