/ 
Process-0.26
River stage two • 10 direct dependents • 12 total dependents
/ Process::Role::Serializable

NAME

Process::Role::Serializable - Indicates that a Process can be frozen to a string

SYNOPSIS

my $object = MyFreezer->new( foo => 'bar' );

# Freeze to various things
$object->serialize( 'filename.dat' );
$object->serialize( \$string       );
$object->serialize( \*FILEHANDLE   );
$object->serialize( $io_handle     );

# Thaw from various things
$object = MyFreezer->deserialize( 'filename.dat' );
$object = MyFreezer->deserialize( \$string       );
$object = MyFreezer->deserialize( \*FILEHANDLE   );
$object = MyFreezer->deserialize( $io_handle     );

# Prepare and run as normal
$object->prepare
$object->run;

DESCRIPTION

Process::Role::Serializable provides a role (an additional interface and set of rules) that allow for Process objects to be converted to be "frozen" to a string, moved around, and then be "thawed" back into an object again.

It does not dictate a specific serialization/deserialization mechanism for you, only dictates that the new API rules be followed. For a good default implementation that should work with almost any class see Process::Storable, which is an implementation using Storable.

No default implementations of the two methods are provided for you.

When a Process can be Serialized

The Process::Role::Serializable API dictates 4 specific conditions at which your object must be serializable. This means you shouldn't be connected to any database, have no locked files, and so on. You should have cleaned up any weird things and be self-contained again.

Following a successful new

When created successfully, your object must be serializable. This point is the primary reason we have seperate new and prepare functions.

With this seperation available, the most common case in distributed systems is to call new to create the object, and then pass the created object to some other interpreter for processing.

Following a failed prepare

When an object fails a prepare call, it is generally for a reason, and often this reasons is saved in the object. This result needs to be transported back to the requestor.

As such, your object must be serializable after prepare in the case that it fails. If you have partly set up before some error occurs, you should ensure that any cleaning up is done before you return false.

Following a successful run

When an object completes run, it will often have data to send back to the requestor. As a result your object must be serializable after run returns. Any cleaning up from the process should be done before you return.

Following a failed run

As well as after a successful run, and for similar reasons as after a failed prepare, you should ensure that your object is serializable after a failed run call.

This means you should including some form of cleaning up even on error, and that you should be the one trapping exceptions in your run, so that this can be done. (but then you should be doing that anyway).

METHODS

serialize

$object->serialize( 'filename.dat' );
$object->serialize( \$string       );
$object->serialize( \*FILEHANDLE   );
$object->serialize( $io_handle     );

The serialize method converts your object to a string, and writes it to a destination.

All implementations are required to accept three different param types, a string that is to be seen as a filename, a SCALAR reference to a string, or a file handle (either a raw GLOB reference, or any IO::Handle object).

All three should have identical information written to them, and in a network-transparent order (if relevant for the serialization mechanism)

Should return true on success, or fail on failure.

deserialize

$object = MyFreezer->deserialize( 'filename.dat' );
$object = MyFreezer->deserialize( \$string       );
$object = MyFreezer->deserialize( \*FILEHANDLE   );
$object = MyFreezer->deserialize( $io_handle     );

The deserialize method takes a filename, string or file handle (GLOB reference or IO::Handle object) and creates a new object, returning it. The same assumptions stated above apply for deserialization.

Returns a new object of your class, or false on error.

SUPPORT

Bugs should be reported via the CPAN bug tracker at

http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Process

For other issues, contact the author.

AUTHOR

Adam Kennedy <adamk@cpan.org>

SEE ALSO

http://ali.as/

COPYRIGHT

Copyright 2006 - 2009 Adam Kennedy.

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

The full text of the license can be found in the LICENSE file included with this module.