Components as you may (or may not) know are the "Top-Level Pieces" of POE. The should all reside in the POE::Component:: namespace and in the docs you will find the abbreviated a PoCo::

From what I have seen and heard, there is no specific interface that you must comply with, Some components will return undef, other will return the session and others return objects. As long as it is well documented it should be ok to implement as you like. Nevertheless, after personally having a rough time with other people's modules, may I suggest the following:

1) Always define a way to set up aliases to every POE::Session you create. This will allow the people that implement your component to have some control over these sessions.

2) It is a good idea to create a $self object and place it in the current session's HEAP. This can be easily done in your _start sub like so:

# your constructor
  sub new {

    # this seems to be very standard practice
    my $class = shift;
    my $args  = shift;

    # this also
    my $alias;
    ...
      if (ref($args) eq 'HASH') {
      $alias = $args->{alias};
      ...;
    }
    ...

      # your own object
      my $self = {
      alias => $alias,
      ...
      };
    bless $self, $class;
    ...

      # in the session definition:
      inline_states => {
      _start => sub {
        $_[KERNEL]->alias_set($self->{alias});
        $_[HEAP]->{self} = $self;
      },
      ...

        # example component returning object
        return $self;

3) Store the alias in object reference for easy point to that session

4) VERY IMPORTANT PLEASE: provide a graceful shutdown event method.

NOTE: that event can be called shutdown but if you must write a sub to shutdown use shut_down instead to prevent namespace corruption with the standard shutdown socket function of Perl.

All this also requires that you keep track of the sessions you spawn and be able to deliver the shutdown event to them. Since you are shutting down, you can call them instead of post to make sure that you shutdown in the correct order. This practice will also let you identify any possible resource (or downright memory leaks) in your or other's people programs. Include a test in your test harness that loads and then shut downs your component. If it does not shutdown (i.e. the test just hangs, you can trace all the sessions with POE::Kernel tracing features like so:

In your test file:

#!/usr/bin/perl
use Test::More tests => X;
use Test::Output;
use Data::Dumper;

# this activates TRACE SESSIONS it must be called before using POE
sub POE::Kernel::TRACE_SESSIONS () { 1 }

# basic load of your component
BEGIN { use_ok('POE::Component::YOURS') }

# server loadaded an unloaded ok
diag("Testing startup and shudown of YOURS...");
diag("May take several seconds (X tops) to shut down....");
diag("If it takes forever, probably YOURS is broken!");
diag("Hit ctrl-c and abort to fix and retry the installation");
isa_ok($yours, 'POE::Component::YOURS');

# this is why it's good idea to save the alias in the object!
POE::Kernel->post($yours->{alias}, 'shutdown');
POE::Kernel->run();

# test should continue here if your shutdown method works

You will see a lot of diagnostic info from the kernel. Things to look for are:

Sessions starting:

<ss> session 2 (POE::Session=ARRAY(0x8308718)) has parent session ctlt1-47406ac000003f1f (POE::Kernel=ARRAY(0x83117e8)) at /usr/local/share/perl/5.8.8/POE/Resource/Sessions.pm line 91 <ss> session 3 (POE::Session=ARRAY(0x8308ca0)) has parent session ctlt1-47406ac000003f1f (POE::Kernel=ARRAY(0x83117e8)) at /usr/local/share/perl/5.8.8/POE/Resource/Sessions.pm line 91 <ss> session 4 (POE::Session=ARRAY(0x8c1cc48)) has parent session ctlt1-47406ac000003f1f (POE::Kernel=ARRAY(0x83117e8)) at /usr/local/share/perl/5.8.8/POE/Resource/Sessions.pm line 91 <ss> session 5 (POE::Session=ARRAY(0x8c8aa00)) has parent session ctlt1-47406ac000003f1f (POE::Kernel=ARRAY(0x83117e8)) at /usr/local/share/perl/5.8.8/POE/Resource/Sessions.pm line 91 <ss> session 6 (POE::Session=ARRAY(0x8c8a124)) has parent session ctlt1-47406ac000003f1f (POE::Kernel=ARRAY(0x83117e8)) at /usr/local/share/perl/5.8.8/POE/Resource/Sessions.pm line 91 <ss> session 7 (POE::Session=ARRAY(0x8c96c0c)) has parent session ctlt1-47406ac000003f1f (POE::Kernel=ARRAY(0x83117e8)) at /usr/local/share/perl/5.8.8/POE/Resource/Sessions.pm line 91 <ss> session 8 (POE::Session=ARRAY(0x8c97290)) has parent session ctlt1-47406ac000003f1f (POE::Kernel=ARRAY(0x83117e8)) at /usr/local/share/perl/5.8.8/POE/Resource/Sessions.pm line 91

And sessions ending:

<ss> stopping session 3 () at /usr/local/share/perl/5.8.8/POE/Resource/Sessions.pm line 467 <ss> freeing session 3 () at /usr/local/share/perl/5.8.8/POE/Resource/Sessions.pm line 115 <ss> removed session 3 () from session ctlt1-47406ac000003f1f (POE::Kernel=ARRAY(0x83117e8)) at /usr/local/share/perl/5.8.8/POE/Resource/Sessions.pm line 151

There is a lot of blurb in between the ending sessions but you will be able to spot them with ease.

If you are unable to shutdown other people's sessions (those that don't provide a shutdown method) you can kill them by sending a signal. The Logger is a good example of a popular PoCo that does not provide a shutdown method:

$_[KERNEL]->signal($self->{logger_alias}, "KILL");

Again, a good example of keeping references to all your sessions.

If the author did not provide a ref to session or a way to alias them, you will have to hack the code and send a mail to them with your hack. I have been told to send a mail to the appropiate RT bug address also. Check out the POE IRC channel which seemed to me very active and people helpful there.

I guess this wraps up my lessons learned in my first PoCo and I hope that it helps other lost noobs into creating their own Components. Nevertheless, bieng myself a noob to POE, please use this information with caution and don't hold me responsible of any inaccuracies stated regarding POE or if am contradicting any other established POE Best Practices. I would urge POE gurus here to revise, comment and fix this article before I make someone do something stupid :-)