Bob Maccione asked:

When a session disconnects from POE, it should throw the _stop event (or call the _stop callback). At least that is what I'm seeing.

What 'cleanup' should be done to ensure that that session and any events/alarms/etc are cleanly destroyed? Currently I'm doing a: 

delete $_[HEAP]->{readwrite};

however this isn't taking care of any alarms that may be still pending.

Philp Gwyn replied:

If you are in a _stop event, all alarms, handles, wheels and so on have already been cleaned up. _stop is just a very last "go away" state.

If you want an event that explicitly kills a session, you create an event called 'shutdown' (or anything else). Then explicitly post it. You then put all clean up code in there. 

sub shutdown {
  my ($kernel, $session, $heap) = @_[KERNEL, SESSION, HEAP];

  # delete all wheels.
  delete $heap->{wheel};

  # clear your alias
  $kernel->alias_remove($heap->{alias});

  # clear all alarms you might have set
  $kernel->alarm_remove_all();

  # get rid of external ref count
  $kernel->refcount_decrement($session, 'my ref name');

  # propagate the message to children
  $kernel->post($heap->{child_session}, 'shutdown');
  return;
}

Rocco Caputo adds:

Some components require shutdown to end in a timely fashion. For example, POE::Component::Client::HTTP uses keep-alive sockets by default, which linger up to 15 seconds by default. A program using this component will sit around for a while after most people expect it to exit. The resolution? Shut down POE::Component::Client::HTTP when the program is done with it.

Related sections:

What keeps sessions alive?