session_id

session_id() is rarely needed, especially since Reflex provides helper classes for working with POE modules. Please see one or more of: Reflex::POE::Event, Reflex::POE::Postback, Reflex::POE::Session, Reflex::POE::Wheel and Reflex::POE::Wheel::Run.

        sub method {
                my $self = shift;
                print(
                        "I, $self, am driven by POE::Sesson ID ",
                        $self->session_id(), "\n"
                );
        }

watch

        use Reflex::Callbacks(cb_method);

        $self->watch(
                watched   => $an_object_maybe_myself,
                event     => "occurrence",
                callback  => cb_method($self, "method_name"),
        );

emit

Emit takes two named parameters so far: "event" names the event being emitted and is required. "args" allows data to be passed along with the event, and it should contain a hashref of named values.

Reflex::Stream emits a "failure" event when things don't go as planned:

        sub _emit_failure {
                my ($self, $errfun) = @_;

                $self->emit(
                        -name  => "failure",
                        data   => undef,
                        errnum => ($!+0),
                        errstr => "$!",
                        errfun => $errfun,
                );

                return;
        }

ignore

Ignore an object entirely:

        $self->ignore($an_object_maybe_myself);

Ignore just specific events:

        my @events = qw(success failure);
        $self->ignore($an_object_maybe_myself, @events);

An object may destruct while it's being watched and/or is watching other objects. DEMOLISH will ensure that all watchers related to the outgoing object are cleaned up. Therefore it's usually more convenient to just destroy things when done with them.

call_gate

POE consumers often return responses to the sessions that made requests. For Reflex objects to receive these responses, they must first send their requests from the right sessions. call_gate() helps by ensuring the proper session is active.

call_gate() takes one required positional parameter: the name of the method calling call_gate(). Any other parameters are passed back to the method, re-creating @_ as it was originally.

call_gate() immediately returns 1 if it's called from the correct session. Otherwise it re-invokes the method in the proper session and returns 0.

It's important to put call_gate() first in methods that need it, and for them to return immediately fi call_gate() returns false.

This method from Reflex::Signal makes sure the signal is watched by the same session that owns the object doing the watching:

        sub start_watching {
                my $self = shift;
                return unless $self->call_gate("start_watching");
                $POE::Kernel::poe_kernel->sig($self->name(), "signal_happened");
        }

run_within_session

For example the IRC bot in eg/eg-13-irc-bot.pl wants to register callbacks with POE::Component::IRC. It calls a couple $bot->yield() methods within the object's session. This helps the component know where to send its responses:

        sub BUILD {
                my $self = shift;

                # Set up $self->component() to contain
                # a POE::Component::IRC object.

                ...;

                # Register this object's interest in the component,
                # via the session that owns this object.
                $self->run_within_session(
                        sub {
                                $self->component()->yield(register => "all");
                                $self->component()->yield(connect  => {});
                        }
                )
        }

next

next() returns the next event emitted by an object. Objects cease to run while your code processes the event, so be quick about it.

Here's most of eg/eg-32-promise-tiny.pl, which shows how to next() on events from a Reflex::Interval.

        use Reflex::Interval;

        my $t = Reflex::Interval->new(
                interval    => 1,
                auto_repeat => 1,
        );

        while (my $event = $t->next()) {
                print "next() returned event '$event->{name}'...\n";
        }

It's tempting to rename this method next().

run_all

run_all() is useful when you don't care to next() on objects individually. You just want the program to run 'til it's done.