[SCM] libmessage-passing-perl Debian packaging branch, master, updated. debian/0.111-3-14-g44f6e88

[Tomas Doran]

The following commit has been merged in the master branch:
commit c201d6a6c3afb8014f8bb8b5b1e3499957f38a8a
Author: Tomas Doran <bobtfish at bobtfish.net>
Date:   Mon May 21 10:37:39 2012 +0100

    ConnectionManager role docs

diff --git a/lib/Log/Stash/Role/ConnectionManager.pm b/lib/Log/Stash/Role/ConnectionManager.pm
index a087a4d..2702cb4 100644
--- a/lib/Log/Stash/Role/ConnectionManager.pm
+++ b/lib/Log/Stash/Role/ConnectionManager.pm
@@ -62,3 +62,51 @@ after _set_connected => sub {
 };
 
 1;
+
+=head1 NAME
+
+Log::Stash::Role::ConnectionManager - A simple manager for inputs and outputs that need to make network connections.
+
+=head1 DESCRIPTION
+
+This role is for components which make network connections, and need to handle the connection not starting,
+timeouts, disconnects etc.
+
+It provides a simple abstraction for multiple other classes to be able to use the same connection manager, and
+a notifies
+
+=head1 REQUIRED METHODS
+
+=head2 _build_connection
+
+Build and return the underlieing connection, start the connection process and return it.
+
+Your connection should use the API as documented below to achieve notification of connect and disconnect events.
+
+=head1 API FOR CONNECTIONS
+
+=head2 _set_connected (1)
+
+Notify clients that the connection is now ready for use.
+
+=head2 _set_connected (0)
+
+Notify clients that the connection is no longer ready for use.
+
+Will cause the connection to be terminated and retried.
+
+=head1 API FOR CLIENTS
+
+To use a connection manager, you should register yourself like this:
+
+    $manager->subscribe_to_connect($self);
+
+The manager will call C<< $self->connected($connection) >> and C<< $self->disconnected() >> when appropriate.
+
+If the manager is already connected when you subscribe, it will immediately call back into your
+C<< connected >> method, if it is not already connected then this will happen at a later point
+once the connection is established.
+
+See L<Log::Stash::Role::HasAConnection> for a role to help with dealing with a connection manager.
+
+=cut

-- 
libmessage-passing-perl Debian packaging