NAME

AnyEvent::POE_Reference - AnyEvent talking to POE::Filter::Reference

SYNOPSIS

  use AnyEvent::POE_Reference;

  ...

  $handle->push_write(poe_reference => [ 1, 2, 3 ]);
  $handle->push_read(poe_reference => sub
		     {
		         my($handle, $ref_data) = @_;
			 ...
		     });
  ...

  # Change the default serializer to YAML
  $handle->push_write(poe_reference => 'YAML', sub { a => 123 });
  $handle->push_read(poe_reference => 'YAML', sub { ... });

  ...

  # Enable compression
  $handle->push_write(poe_reference => 'YAML', 1 => sub { a => 123 });
  $handle->push_read(poe_reference => 'YAML', 1 => sub { ... });

  ...

  # Create a serializer instance to use later
  my $serializer = AnyEvent::POE_Reference->new('YAML', 1);

  $handle->push_write(poe_reference => $serializer, $any_perl_ref);
  $handle->push_read(poe_reference => $serializer,
		       sub { my($hdl, $ref) = @_; ... });

DESCRIPTION

AnyEvent::POE_Reference allows an AnyEvent program to talk to a POE one using serialized references as POE formats them.

POE can use any serializer/deserializer by specifying it when building the POE::ReadWrite::Wheel. It is encapsulated into a POE::Filter::Reference. It defaults to use Storable.

In POE a POE::Wheel::ReadWrite can receive a POE::Filter object. In our case it is more precisely a POE::Filter::Reference instance. Like this:

    my $wheel = POE::Wheel::ReadWrite->new(
	Handle	   => $socket,
	InputEvent => "client_input",
	ErrorEvent => "client_error",
	Filter	   => POE::Filter::Reference->new('YAML', 1),
	);

Here 'YAML' and 1 are optional (by default 'Storable' and 0 are used). The first argument is the serializer and the second specify whether the serialization has to be compressed or not.

In the AnyEvent counterpart, we will have:

    $handle->push_write(poe_reference => 'YAML', 1, $any_perl_ref);
    $handle->push_read(poe_reference => 'YAML', 1,
		       sub { my($hdl, $ref) = @_; ... });

As in POE, here 'YAML' and 1 are optional with the same defaults ('Storable' and 0).

    $handle->push_write(poe_reference => 'YAML', $any_perl_ref);
    $handle->push_read(poe_reference => 'YAML',
		       sub { my($hdl, $ref) = @_; ... });

Will use YAML as serializer but with compression disabled.

$handle->push_write(poe_reference => $any_perl_ref);
$handle->push_read(poe_reference => sub { my($hdl, $ref) = @_; ...});

Will use the default serializer Storable with compression disabled.

To activate compression with the default serializer, just pass undef as the serializer as in:

    $handle->push_write(poe_reference => undef, 1, $any_perl_ref);
    $handle->push_read(poe_reference => undef, 1,
		       sub { my($hdl, $ref) = @_; ... });

To avoid passing the same serializer with its compression flag at each call, you can create a special serializer object at the beginning of your code, and use it each time you need to call push_write or push_read:

    my $serializer = AnyEvent::POE_Reference->new('YAML', 1);
    ...
    $handle->push_write(poe_reference => $serializer, $any_perl_ref);
    $handle->push_read(poe_reference => $serializer,
		       sub { my($hdl, $ref) = @_; ... });

It is useless to create several serializer instances with the same serializer and compression flag. Indeed, the constructor will return the same instance because there is no need to have many identical objects...

Note that, as in the POE::Filter::Reference constructor, the serializer and the compression flag are optional.

If the serializer can not be found, AnyEvent::POE_Reference croaks.

The maximum size of serialized (and possibly compressed) data is specified by the variable $AnyEvent::POE_Reference::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.

In all other error cases (like wrong serializer for example), an error Errno::EBADMSG is given to the error handler.

SERIALIZER FORMAT

The format used is very simple. The length of the serialized data in human form followed by a NUL byte then by the data. Like:

12\0xxxxxxxxxxxx

See POE::Filter::Reference for more details.

DEVELOPMENT

Repository

http://github.com/maxatome/p5-AnyEvent-POE_Reference

SEE ALSO

Test t/POE.t gives an example of an AnyEvent client interracting with a POE server.

AnyEvent, AnyEvent::Handle, POE, POE::Filter::Reference.

AUTHOR

Maxime Soule, <btik-cpan@scoubidou.com>

COPYRIGHT AND LICENSE

Copyright 2011 by Ijenko.

http://www.ijenko.com

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

cpanm AnyEvent::POE_Reference

perl -MCPAN -e shell
install AnyEvent::POE_Reference