/ 
AnyEvent-Sereal-0.004
River stage zero No dependents
/ AnyEvent::Sereal

NAME

AnyEvent::Sereal - Sereal stream serializer/deserializer for AnyEvent

SYNOPSIS

use AnyEvent::Sereal;
use AnyEvent::Handle;

my $hdl = AnyEvent::Handle->new(
    # settings...
);
$hdl->push_write(sereal => [ 1, 2, 3 ]);
$hdl->push_read(sereal => sub {
    my($hdl, $data) = @_;
      # $data is [ 1, 2, 3 ]
});

# Can pass L<Sereal::Encoder> options to C<push_write>
$hdl->push_write(sereal => 'a' x 1_000, { snappy => 1 });

# And pass L<Sereal::Decoder> options to C<push_read>
$hdl->push_read(sereal => { refuse_snappy => 1 }, sub { ... });

DESCRIPTION

AnyEvent::Sereal is Sereal serializer/deserializer for AnyEvent.

The maximum size of serialized (and possibly compressed) data is specified by the variable $AnyEvent::Sereal::SERIALIZED_MAX_SIZE. It defaults to 1_000_000 bytes. In case received data seems to contain more than this number of bytes, an error Errno::E2BIG is given to the error handler.

The serializer options has to be passed for the first push_write call only, otherwise a new serializer will be instanciated internally and a performance penalty will occur.

The same applies for the deserializer options and the first push_read or unshift_read calls.

See Implementation below for details.

IMPLEMENTATION

To be fast, the serializer stores a Sereal::Encoder instance in the _sereal_encoder attribute of the AnyEvent::Handle instance.

Each time the serializer receives options via push_write, a new Sereal::Encoder object is instanciated and the previous one is destroyed. When push_write is called without an options hash, the existing Sereal::Encoder instance is re-used. To reset options, by instanciating a new Sereal::Encoder instance, simply pass them to {}.

$hdl->push_write(sereal => [ 1, 2, 3 ]);
# Here $hdl->{_sereal_encoder} is a Sereal::Encoder instance
$hdl->push_write(sereal => 42);
# Here $hdl->{_sereal_encoder} is still the same
$hdl->push_write(sereal => { a => 1 }, { snappy => 1 });
# Here $hdl->{_sereal_encoder} contains a *new* Sereal::Encoder instance
# with snappy option enabled
$hdl->push_write(sereal => 42);
# Here $hdl->{_sereal_encoder} is still the same, so with snappy
# option enabled
$hdl->push_write(sereal => 42, {});
# Here $hdl->{_sereal_encoder} contains a *new* Sereal::Encoder instance,
# without any option
...

The same applies for the deserializer:

Still to be fast, a Sereal::Decoder instance is stored in the _sereal_decoder attribute of the AnyEvent::Handle instance.

Each time the deserializer receives options via push_read or unshift_read, a new Sereal::Decoder object is instanciated and the previous one is destroyed. When push_read or unshift_read are called without options, the existing Sereal::Decoder instance is re-used. To reset options, by instanciating a new Sereal::Decoder instance, simply pass them to {}.

$hdl->push_read(sereal => \&cb1);
# When cb1 is called, $hdl->{_sereal_decoder} contains a
# Sereal::Decoder instance
$hdl->push_read(sereal => \&cb2);
# When cb2 is called, $hdl->{_sereal_decoder} is still the same
$hdl->push_read(sereal => { refuse_snappy => 1 }, \&cb3);
# When cb3 is called, $hdl->{_sereal_decoder} contains a *new*
# Sereal::Decoder instance with refuse_snappy option enabled
$hdl->push_read(sereal => \&cb4);
# When cb4 is called, $hdl->{_sereal_decoder} is still the same,
# so with refuse_snappy option enabled
$hdl->push_read(sereal => {}, \&cb5);
# When cb5 is called, $hdl->{_sereal_decoder} contains a *new*
# Sereal::Decoder instance, without any option
...

Note that the Sereal::{De,En}coder instances are re-instanciated each time an options hash is passed, even if the options do not change.

SEE ALSO

AnyEvent::Handle and storable filter.

Sereal::Encoder and Sereal::Decoder.

AUTHOR

Maxime Soulé, <btik-cpan@scoubidou.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2012 by Ijenko.

http://www.ijenko.com

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.