/ 
Reflex-0.071
River stage one • 7 direct dependents • 7 total dependents
/ Reflex::Role::Reactive

NAME

Reflex::Role::Reactive - Make an object reactive (aka, event driven).

VERSION

version 0.071

SYNOPSIS

With Moose:

package Object;
use Moose;
with 'Reflex::Role::Reactive';

...;

1;

Without Moose:

# Sorry, roles are defined and composed using Moose.
# However, Reflex::Base may be used the old fashioned way.

DESCRIPTION

Reflex::Role::Reactive provides Reflex's event-driven features to other objects. It provides public methods that help use reactive objects and to write them.

Public Attributes

session_id

Each Reflex object is associated with a POE session, although a single session may (and usually does) drive several objects. Reflex objects expose session_id() for times where it's important to know which session owns them. Usually when interfacing between Reflex and POE.

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

watch() allows one object (the watcher) to register interest in events emitted by another. It takes three named parameters: "watched" must contain a Reflex object (either a Reflex::Role::Reactive consumer, or a Reflex::Base subclass). "event" contains the name of an event that the watched object emits. Finally, "callback" contains a Reflex::Callback that will be invoked when the event occurs.

use Reflex::Callbacks(cb_method);

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

emit

Emit an event. This triggers callbacks for anything waiting for the event from the object that emitted it. Callback invocation is often synchronous, but this isn't guaranteed. Later versions of Reflex will support remote objects, where the emitter and callback may not be in the same room.

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(
		event => "failure",
		args  => {
			data    => undef,
			errnum  => ($!+0),
			errstr  => "$!",
			errfun  => $errfun,
		},
	);

	return;
}

ignore

The ignore() method tells Reflex that one object has lost interest in events from another. It requires at least one parameter, the object to be ignored. Additional parameters may name specific events to 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

call_gate() is a helper that ensures a method is called from the same POE::Session instance that owns its object. It's mainly of interest to authors of POE modules and their Reflex interfaces. Other users may never need it.

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

run_within_session() is another helper method to ensure some code is running in the POE session that POE modules may expect. It takes one required positional parameter, a code reference to invoke or the name of a method to call on $self. Any other parameters are passed to the code that will be executed.

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

Wait for the next event promised by an object. Requires the object to emit an event that isn't already explicitly handled. All Reflex objects will run in the background while next() blocks.

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 active Reflex objects until they destruct. This will not return discrete events, like next() does. It will not return at all before the program is done. It returns no meaningful value yet.

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.

EXAMPLES

Many of the examples in the distribution's eg directory use Reflex objects. Explore and enjoy!

SEE ALSO

Moose::Manual::Concepts

Reflex Reflex::Base

"ACKNOWLEDGEMENTS" in Reflex "ASSISTANCE" in Reflex "AUTHORS" in Reflex "BUGS" in Reflex "BUGS" in Reflex "CONTRIBUTORS" in Reflex "COPYRIGHT" in Reflex "LICENSE" in Reflex "TODO" in Reflex