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.