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.44 by root, Mon Jun 25 04:08:17 2007 UTC vs.
Revision 1.47 by root, Mon Jun 25 06:57:42 2007 UTC

… …
341 341
342The C<TO_JSON> method may safely call die if it wants. If C<TO_JSON> 342The C<TO_JSON> method may safely call die if it wants. If C<TO_JSON>
343returns other blessed objects, those will be handled in the same 343returns other blessed objects, those will be handled in the same
344way. C<TO_JSON> must take care of not causing an endless recursion cycle 344way. C<TO_JSON> must take care of not causing an endless recursion cycle
345(== crash) in this case. The name of C<TO_JSON> was chosen because other 345(== crash) in this case. The name of C<TO_JSON> was chosen because other
346methods called by the Perl core (== not the user of the object) are 346methods called by the Perl core (== not by the user of the object) are
347usually in upper case letters and to avoid collisions with the C<to_json> 347usually in upper case letters and to avoid collisions with the C<to_json>
348function. 348function.
349
350This setting does not yet influence C<decode> in any way, but in the
351future, global hooks might get installed that influence C<decode> and are
352enabled by this setting.
349 353
350If C<$enable> is false, then the C<allow_blessed> setting will decide what 354If C<$enable> is false, then the C<allow_blessed> setting will decide what
351to do when a blessed object is found. 355to do when a blessed object is found.
352 356
353=item $json = $json->shrink ([$enable]) 357=item $json = $json->shrink ([$enable])
… …
389given character in a string. 393given character in a string.
390 394
391Setting the maximum depth to one disallows any nesting, so that ensures 395Setting the maximum depth to one disallows any nesting, so that ensures
392that the object is only a single hash/object or array. 396that the object is only a single hash/object or array.
393 397
394The argument to C<max_depth> will be rounded up to the next nearest power 398The argument to C<max_depth> will be rounded up to the next highest power
395of two. 399of two. If no argument is given, the highest possible setting will be
400used, which is rarely useful.
401
402See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
403
404=item $json = $json->max_size ([$maximum_string_size])
405
406Set the maximum length a JSON text may have (in bytes) where decoding is
407being attempted. The default is C<0>, meaning no limit. When C<decode>
408is called on a string longer then this number of characters it will not
409attempt to decode the string but throw an exception. This setting has no
410effect on C<encode> (yet).
411
412The argument to C<max_size> will be rounded up to the next B<highest>
413power of two (so may be more than requested). If no argument is given, the
414limit check will be deactivated (same as when C<0> is specified).
396 415
397See SECURITY CONSIDERATIONS, below, for more info on why this is useful. 416See SECURITY CONSIDERATIONS, below, for more info on why this is useful.
398 417
399=item $json_text = $json->encode ($perl_scalar) 418=item $json_text = $json->encode ($perl_scalar)
400 419
… …
748Second, you need to avoid resource-starving attacks. That means you should 767Second, you need to avoid resource-starving attacks. That means you should
749limit 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
750resources 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
751can 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
752usually 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
753it 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.
754 775
755Third, JSON::XS recurses using the C stack when decoding objects and 776Third, JSON::XS recurses using the C stack when decoding objects and
756arrays. 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
757machine 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
758only 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

Diff Legend

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