# perldoc > POE::Session

---
type: CommandReference
command: POE::Session
mode: perldoc
section: 
source: perldoc
---

## Quick Reference

- `POE::Session->create(inline_states => { _start => sub { ... } })` — Basic session with inline handlers
- `POE::Session->create(object_states => [ $obj => { event => 'method' } ])` — Dispatch to object methods
- `POE::Session->create(package_states => [ $class => { event => 'method' } ])` — Dispatch to class methods
- `$_[KERNEL]->delay(event => seconds)` — Set a timer within a handler
- `$_[KERNEL]->yield('event', @args)` — Post event to self
- `$_[SESSION]->option(trace => 1)` — Enable session dispatch trace
- `$_[SESSION]->postback('event', @args)` — Create callback that posts event
- `sub handle_default { my ($event, $args) = @_[ARG0, ARG1]; ... }` — Catch unhandled events

## Name

**POE::Session** — a generic event-driven task

## Synopsis

perl
use POE;

POE::Session->create(
  inline_states => {
    _start => sub { $_[KERNEL]->yield("next") },
    next   => sub {
      print "tick...\n";
      $_[KERNEL]->delay(next => 1);
    },
  },
);

POE::Kernel->run();
exit;
Also supports `object_states` and `package_states` for method dispatch.

## Options (Constructor Parameters)

- `args => \@list` — List of parameters passed to the `_start` handler in `@_[ARG0..$#_]`
- `heap => $anything` — Initialize session heap (default: anonymous hashref)
- `inline_states => \%hash` — Maps event names to coderefs
- `object_states => \@array` — Maps object(s) and event names to method names
- `package_states => \@array` — Maps class(es) and event names to method names
- `options => \%hash` — Set session options (debug, default, trace)

## Options (Runtime Methods)

- `->ID()` — Returns unique session integer ID
- `->option(OPTION_NAME [, OPTION_VALUE]...)` — Get/set session options. Options: `debug` (warn on redefines), `default` (warn on unknown events), `trace` (log dispatched events). Returns previous value(s).
- `->postback(EVENT_NAME, @params)` — Returns coderef that posts a POE event. `ARG0` = creation params, `ARG1` = callback params.
- `->callback(EVENT_NAME, @params)` — Like `postback()` but calls synchronously (for use with blocking libraries)
- `->get_heap()` — Returns reference to session's heap (same as `$_[HEAP]`)

## Examples

### Basic inline session

perl
POE::Session->create(
  inline_states => {
    _start => sub {
      $_[HEAP]{ts_start} = time();
      $_[KERNEL]->yield('do_work');
    },
    do_work => sub {
      print "Working...\n";
      $_[KERNEL]->delay(do_work => 1) if $_[HEAP]{count}++ < 5;
    },
    _stop => sub {
      my $elapsed = time() - $_[HEAP]{ts_start};
      print "Ran for $elapsed seconds\n";
    },
  },
);
### Using object_states

perl
my $obj = MyApp->new;
POE::Session->create(
  object_states => [
    $obj => {
      _start => 'start_handler',
      _stop  => 'stop_handler',
    },
  ],
);
### _default handler

perl
POE::Session->create(
  inline_states => {
    _default => sub {
      my ($event, $args) = @_[ARG0, ARG1];
      warn "Unknown event: $event with args (@$args)\n";
    },
    known_event => sub { print "Handled known_event\n" },
  },
);
### Postback for Gtk2

perl
my $btn = Gtk2::Button->new("Clear");
$btn->signal_connect("clicked", $_[SESSION]->postback("ev_clear"));
## See Also

- [POE::Kernel](https://metacpan.org/pod/POE::Kernel)
- [POE::NFA](https://metacpan.org/pod/POE::NFA) (event-driven state machines)
- [POE](https://metacpan.org/pod/POE) (table of contents)

## Exit Codes

None documented.