.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Message::Passing::Role::ConnectionManager 3pm"
.TH Message::Passing::Role::ConnectionManager 3pm "2012-09-06" "perl v5.18.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Message::Passing::Role::ConnectionManager \- A simple manager for inputs and outputs that need to make network connections.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This role is for components which make network connections, and need to handle the connection not starting,
timeouts, disconnects etc.
.PP
It provides a simple abstraction for multiple other classes to be able to use the same connection manager, and
a notifies
.SH "REQUIRED METHODS"
.IX Header "REQUIRED METHODS"
.SS "_build_connection"
.IX Subsection "_build_connection"
Build and return the connection we're managing, start the connection
process.
.PP
Your connection should use the \s-1API\s0 as documented below to achieve notification of connect and disconnect events.
.SH "API FOR CONNECTIONS"
.IX Header "API FOR CONNECTIONS"
.SS "_set_connected (1)"
.IX Subsection "_set_connected (1)"
Notify clients that the connection is now ready for use.
.SS "_set_connected (0)"
.IX Subsection "_set_connected (0)"
Notify clients that the connection is no longer ready for use.
.PP
Will cause the connection to be terminated and retried.
.SH "API FOR CLIENTS"
.IX Header "API FOR CLIENTS"
To use a connection manager, you should register yourself like this:
.PP
.Vb 1
\&    $manager\->subscribe_to_connect($self);
.Ve
.PP
The manager will call \f(CW\*(C`$self\->connected($connection)\*(C'\fR and \f(CW\*(C`$self\->disconnected()\*(C'\fR when appropriate.
.PP
If the manager is already connected when you subscribe, it will immediately call back into your
\&\f(CW\*(C`connected\*(C'\fR method, if it is not already connected then this will happen at a later point
once the connection is established.
.PP
See Message::Passing::Role::HasAConnection for a role to help with dealing with a connection manager.
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
.SS "connected"
.IX Subsection "connected"
A Boolean indicating if the connection is currently considered fully connected
.SS "connection"
.IX Subsection "connection"
The connection object (if we are connected, or connecting currently) \- can
be undefined if we are during a reconnect timeout.
.SS "timeout"
.IX Subsection "timeout"
Connections will be timed out and aborted after this time if they haven't
successfully connected.
.PP
Defaults to 30s
.SS "reconnect_after"
.IX Subsection "reconnect_after"
The number of seconds to wait before starting a reconnect after a connection has timed out
or been aborted.
.PP
Defaults to 2s
.SH "METHODS"
.IX Header "METHODS"
.SS "subscribe_to_connect ($subscriber)"
.IX Subsection "subscribe_to_connect ($subscriber)"
This is called by your Input or Output, as \f(CW\*(C`$self\->connection_manager\->subscribe_to_connect($self)\*(C'\fR.
.PP
This is done for you by Message::Passing::Role::HasAConnection usually..
.PP
This arranges to store a weak reference to your component, allowing the 
connection manager to call the \f(CW\*(C`\->connect\*(C'\fR
or \f(CW\*(C`\->disconnect\*(C'\fR methods for any components registered when a connection is established or destroyed.
.PP
Note that if the connection manager is already connected, it will \fBimmediately\fR call the \f(CW\*(C`\->connect\*(C'\fR method.
.SH "SPONSORSHIP"
.IX Header "SPONSORSHIP"
This module exists due to the wonderful people at Suretec Systems Ltd.
<http://www.suretecsystems.com/> who sponsored its development for its
VoIP division called SureVoIP <http://www.surevoip.co.uk/> for use with
the SureVoIP \s-1API \- \s0
<http://www.surevoip.co.uk/support/wiki/api_documentation>
.PP
==head1 \s-1AUTHOR, COPYRIGHT AND LICENSE\s0
.PP
See Message::Passing.