view release on metacpan or  search on metacpan

lib/POE/Kernel.pm  view on Meta::CPAN

  unless ($self->_data_ses_exists($session_id)) {
    $self->_explain_return("session id $session_id does not exist");
    $! = ESRCH;
    return;
  }

  my $refcount = $self->_data_extref_inc($session_id, $tag);
  # TODO trace it here
  return $refcount;
}

sub refcount_decrement {
  my ($self, $session_id, $tag) = ($poe_kernel, @_[1..$#_]);

  if (ASSERT_USAGE) {
    _confess "<us> undefined session ID in refcount_decrement()"
      unless defined $session_id;
    _confess "<us> undefined reference count tag in refcount_decrement()"
      unless defined $tag;
  };

  unless ($self->_data_ses_exists($session_id)) {
    $self->_explain_return("session id $session_id does not exist");
    $! = ESRCH;
    return;
  }

  my $refcount = $self->_data_extref_dec($session_id, $tag);

  # TODO trace it here
  return $refcount;
}

#==============================================================================
# HANDLERS
#==============================================================================

# Add or remove event handlers from sessions.
sub state {
  my ($self, $event, $state_code, $state_alias) = ($poe_kernel, @_[1..$#_]);
  $state_alias = $event unless defined $state_alias;

  if (ASSERT_USAGE) {
    _confess "<us> must call state() from a running session"
      if $kr_active_session == $self;
    _confess "<us> undefined event name in state()" unless defined $event;
    _confess "<us> can't call state() outside a session" if (
      $kr_active_session == $self
    );
  };

  if (
    (ref($kr_active_session) ne '') &&
    (ref($kr_active_session) ne 'POE::Kernel')
  ) {
    $kr_active_session->_register_state($event, $state_code, $state_alias);
    return 0;
  }

  # TODO A terminal signal (such as UIDESTROY) kills a session.  The
  # Kernel deallocates the session, which cascades destruction to its
  # HEAP.  That triggers a Wheel's destruction, which calls
  # $kernel->state() to remove a state from the session.  The session,
  # though, is already gone.  If TRACE_RETVALS and/or ASSERT_RETVALS
  # is set, this causes a warning or fatal error.

  $self->_explain_return("session ($kr_active_session) does not exist");
  return ESRCH;
}

1;

__END__

=head1 NAME

POE::Kernel - an event-based application kernel in Perl

=head1 SYNOPSIS

  use POE; # auto-includes POE::Kernel and POE::Session

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

  POE::Kernel->run();
  exit;

In the spirit of Perl, there are a lot of other ways to use POE.

=head1 DESCRIPTION

POE::Kernel is the heart of POE.  It provides the lowest-level
features: non-blocking multiplexed I/O, timers, and signal watchers
are the most significant.  Everything else is built upon this
foundation.

POE::Kernel is not an event loop in itself.  For that it uses one of
several available POE::Loop interface modules.  See CPAN for modules
in the POE::Loop namespace.

POE's documentation assumes the reader understands the @_ offset
constants (KERNEL, HEAP, ARG0, etc.).  The curious or confused reader
will find more detailed explanation in L<POE::Session>.

=head1 USING POE

=head2 Literally Using POE

POE.pm is little more than a class loader.  It implements some magic
to cut down on the setup work.

Parameters to C<use POE> are not treated as normal imports.  Rather,
they're abbreviated modules to be included along with POE.