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

NAME

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

VERSION

This document describes version 0.100, released on April 02, 2017.

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(
		-name  => "failure",
		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

Please see those modules/websites for more information related to this module.

BUGS AND LIMITATIONS

You can make new bug reports, and view existing ones, through the web interface at http://rt.cpan.org/Public/Dist/Display.html?Name=Reflex.

AUTHOR

Rocco Caputo <rcaputo@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2017 by Rocco Caputo.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

AVAILABILITY

The latest version of this module is available from the Comprehensive Perl Archive Network (CPAN). Visit http://www.perl.com/CPAN/ to find a CPAN site near you, or see https://metacpan.org/module/Reflex/.

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.