.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" 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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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 >0, 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
.\" ========================================================================
.\"
.IX Title "POE::Component 3"
.TH POE::Component 3 2024-07-13 "perl v5.38.2" "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
POE::Component \- event driven objects or subsystems
.SH SYNOPSIS
.IX Header "SYNOPSIS"
See specific components.
.SH DESCRIPTION
.IX Header "DESCRIPTION"
POE "components" are event-driven modules that generally encapsulate
mid\- to high-level program features.  For example,
POE::Component::Client::DNS performs message-based asynchronous
resolver lookups.  POE::Component::Server::TCP is a basic asynchronous
network server.
.PP
The POE::Component namespace was started as place for contributors to
publish their POE-based modules without requiring coordination with
the main POE distribution.  The namespace predates the \-X convention,
otherwise you'd be reading about POEx instead.
.PP
As with many things in Perl, there is more than one way to implement
component interfaces.  Newer components sport OO interfaces, and some
even use Moose, but older ones are solely message driven.
.SH "OBJECT ORIENTED COMPONENTS"
.IX Header "OBJECT ORIENTED COMPONENTS"
One way to create object-oriented components is to embed a
POE::Session instance within an object.  This is done by creating the
session during the object's constructor, setting the session's alias
to something unique, and saving a copy of the alias in the object.
.PP
.Vb 1
\&  package Asynchrotron;
\&
\&  my $alias_index = 0;
\&
\&  sub new {
\&    my $class = shift;
\&    my $self = bless {
\&      alias => _\|_PACKAGE_\|_ . " " . ++$alias_index;
\&    }, $class;
\&
\&    POE::Session\->create(
\&      object_states => [
\&        $self => {
\&          _start       => "_poe_start",
\&          do_something => "_poe_do_something",
\&        },
\&      ],
\&    );
\&    return $self;
\&  }
\&
\&  sub _poe_start {
\&    $_[KERNEL]\->alias_set($_[OBJECT]\->{alias});
\&  }
.Ve
.PP
The alias allows object methods to pass events into the session
without having to store something about the session.  The POE::Kernel
\&\fBcall()\fR transfers execution from the caller session's context into the
component's session.
.PP
.Vb 5
\&  sub do_something {
\&    my $self = shift;
\&    print "Inside the caller\*(Aqs session right now: @_\en";
\&    $poe_kernel\->call($self\->{alias}, "do_something", @_);
\&  }
\&
\&  sub _poe_do_something {
\&    my @args = @_[ARG0..$#_];
\&    print "Inside the component\*(Aqs session now: @args\en";
\&    $_[OBJECT]{count}++;
\&  }
.Ve
.PP
Both \f(CW$_\fR[HEAP] and \f(CW$_\fR[OBJECT] are visible within the component's
session.  \f(CW$_\fR[HEAP] can be used for ultra-private encapsulation, while
\&\f(CW$_\fR[OBJECT] may be used for data visible by accessors.
.PP
.Vb 4
\&  sub get_count {
\&    my $self = shift;
\&    return $self\->{count}; # $_[OBJECT]{count} above
\&  }
.Ve
.PP
Too many sessions may bog down object creation and destruction, so
avoid creating them for every object.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
The SEE ALSO section in POE contains a table of contents covering
the entire POE distribution.
.PP
POE::Stage is a nascent project to formalize POE components, make
POE::Kernel more object-oriented, and provide syntactic and semantic
sugar for many common aspects of POE::Component development.  It's
also easier to type.  Please investigate the project.  Ideas and \fItuits\fR
are badly needed to help get the project off the ground.
.SH "TO DO"
.IX Header "TO DO"
Document the customary (but not mandatory!) process of creating and
publishing a component.
.SH "AUTHORS & COPYRIGHTS"
.IX Header "AUTHORS & COPYRIGHTS"
Each component is written and copyrighted separately.
.PP
Please see POE for more information about authors and contributors.