Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
POE::Component::SyndicUser(Contributed Perl DocumPOE::Component::Syndicator(3)

NAME
       POE::Component::Syndicator - A POE component base class which
       implements the Observer pattern

SYNOPSIS
	package	POE::Component::IRC;

	use strict;
	use warnings;
	use POE;
	use base 'POE::Component::Syndicator';

	# our constructor
	sub spawn {
	    my ($package, %args) = @_;

	    # process arguments...

	    my $self = bless \%args, $package;

	    # set up our plugin	system and POE session
	    $self->_syndicator_init(
		prefix	      => 'irc_',
		reg_prefix    => 'PCI_',
		types	      => [SERVER => 'S', USER => 'U'],
		object_states => [qw(
		    syndicator_started
		    shutdown
		)],
	    );

	    return $self;
	}

	sub syndicator_started {
	    my ($kernel, $self)	= @_[KERNEL, OBJECT];

	    # connect to a server, etc...
	}

	# plugin handler for SERVER event 'hlagh'
	sub S_hlagh {
	    # ...
	}

	sub shutdown {
	    my ($kernel, $self)	= @_[KERNEL, OBJECT];

	    # disconnect from a	server,	etc...

	    # shut down	the syndicator
	    $self->_syndicator_destroy();
	}

DESCRIPTION
       POE::Component::Syndicator is a base class for POE components which
       need to handle a	persistent resource (e.g. a connection to an IRC
       server) for one or more sessions	in an extendable way.

       This module (as well as Object::Pluggable, which	this module inherits
       from) was born out of POE::Component::IRC, the guts of which quickly
       spread to other POE components. Now they	can all	inherit	from this
       module instead.

       The component provides an event queue, which can	be managed with	the
       methods documented below. It handles delivery of	events to the object
       itself, all interested plugins, and all interested sessions.

   Component lifetime
       You start by calling "_syndicator_init",	which will create a POE
       session with your object	as its heap, and a few event handlers
       installed. The events described in "Local events" delimit the start and
       end of the session's lifetime. In between those,	interested plugins and
       sessions	will receive various events, usually starting with
       "syndicator_registered".	In this	phase, your subclass and plugins can
       call the	methods	and send the events documented below. When the
       component has been shut down, sessions (but not plugins)	will receive a
       "syndicator_shutdown" event. After this,	the component will become
       unusable.

   A note on events
       In this document, an event (unless explicitly referred to as a POE
       event) is defined as a message originating from
       POE::Component::Syndicator, delivered to	plugins	(and the subclass) via
       plugin methods and to registered	sessions as POE	events.

       Interested sessions are considered consumers only, so they always
       receive copies of event arguments, whereas interested plugins and
       subclasses receive scalar references to them. This allows them to
       alter, add, or remove event arguments before sessions (or even other
       plugins)	receive	them. For more information about plugins, see
       Object::Pluggable's documentation. A subclass does not have to register
       for plugin events.

       Two event types are supported: SERVER and USER, though their names can
       be overriden (see "_syndicator_init").

       SERVER events

       These represent data received from the network or some other outside
       resource	(usually a server, hence the default name).

       SERVER events are generated by the "send_event*"	methods.  These	events
       are delivered to	the subclass and plugins (method "S_foo") and
       interested sessions (event "syndicator_foo").

       USER events

       These represent commands	about to be sent to a server or	some other
       resource.

       USER events are generated by "send_user_event". In addition, all	POE
       events sent to this component's session (e.g. with "yield") which do
       not have	a handler will generate	corresponding USER events. USER	events
       are considered more private, so they are	only delivered to the subclass
       and plugins, not	to sessions.

PRIVATE	METHODS
       The following methods should only be called by a	subclass.

   "_syndicator_init"
       You should call this in your constructor. It initializes
       Object::Pluggable, creates the Syndicator's POE session,	and calls the
       "syndicator_started" POE	events.	It takes the following arguments:

       'prefix', a prefix for all your event names, when sent to interested
       sessions. If you	don't supply this, Object::Pluggable's default
       ('pluggable') will be used.

       'reg_prefix', the prefix	for the	"register()"/"unregister()" plugin
       methods	If you don't supply this, Object::Pluggable's default
       ('plugin_') will	be used.

       'debug',	a boolean, if true, will cause a warning to be printed every
       time a plugin event handler raises an exception.

       'types',	a 2-element arrayref of	the types of events that your
       component will support, or a 4-element (2 pairs)	arrayref where the
       event types are keys and	their abbrevations (used as plugin event
       method prefixes)	are values (see	"A note	on events" and
       Object::Pluggable for more information).	The two	event types are
       fundamentally different,	so make	sure you supply	them in	the right
       order. If you don't provide this	argument, "[ SERVER => 'S', USER =>
       'U' ]" will be used.

       'register_signal', the name of the register signal (see "SIGNALS").
       Defaults	to 'SYNDICATOR_REGISTER'.

       'shutdown_signal', the name of the shutdown signal (see "SIGNALS").
       Defaults	to 'SYNDICATOR_SHUTDOWN'.

       'object_states' an arrayref of additional object	states to add to the
       POE session. Same as the	'object_states'	argument to POE::Session's
       "create"	method.	You'll want to add a handler for at least the
       "syndicator_started" event.

       'options', a hash of options for	POE::Session's constructor.

       If you call "_syndicator_init" from inside another POE session, the
       component will automatically register that session as wanting all
       events.	That session will first	receive	a "syndicator_registered"
       event.

   "_syndicator_destroy"
       Call this method	when you want Syndicator to clean up (delete all
       plugins,	etc) and make sure it won't keep the POE session alive after
       all remaining events have been processed. A "syndicator_shutdown" event
       (or similar, depending on the prefix you	chose) will be generated.  Any
       argument	passed to "_syndicator_destroy"	will be	passed along with that
       event.

       Note: this method will clear all	alarms for the POE session.

PUBLIC METHODS
   "session_id"
       Returns the component's POE session id.

   "session_alias"
       Returns the component's POE session alias.

   "yield"
       This method provides an alternative, object-based means of posting
       events to the component.	First argument is the event to post, following
       arguments are sent as arguments to the resultant	post.

   "call"
       This method provides an alternative, object-based means of calling
       events to the component.	First argument is the event to call, following
       arguments are sent as arguments to the resultant	call.

   "send_event"
       Adds a new SERVER event onto the	end of the queue. The event will be
       processed after other pending events, if	any. First argument is an
       event name, the rest are	the event arguments.

	$component->send_event('irc_public, 'foo!bar@baz.com', ['#mychan'], 'message');

   "send_event_next"
       Adds a new SERVER event to the start of the queue. The event will be
       the next	one to be processed. First argument is an event	name, the rest
       are the event arguments.

   "send_event_now"
       Sends a new SERVER event	immediately. Execution of the current POE
       event will be suspended (i.e. this call will block) until the new event
       has been	processed by the component class and all plugins. First
       argument	is an event name, the rest are the event arguments.

   "send_user_event"
       Sends a new USER	event immediately. You should call this	before every
       command you send	to your	remote server/resource.	Only the subclass and
       plugins will see	this event. Takes two arguments, an event name and an
       arrayref	of arguments. Returns one of the "EAT" constants listed	in
       Object::Pluggable::Constants. After this	method returns,	the arrayref's
       contents	may have been modified by the subclass or plugins.

	$component->send_user_event('PRIVMSG', '#mychan', 'message');

   "delay"
       This method provides a way of posting delayed events to the component.
       The first argument is an	arrayref consisting of the delayed command to
       post and	any command arguments. The second argument is the time in
       seconds that one	wishes to delay	the command being posted.

	my $alarm_id = $component->delay(['mode', $channel, '+o', $dude], 60);

   "delay_remove"
       This method removes a previously	scheduled delayed event	from the
       component.  Takes one argument, the "alarm_id" that was returned	by a
       "delay" method call. Returns an arrayref	of arguments to	the event that
       was originally requested	to be delayed.

	my $arrayref = $component->delay_remove($alarm_id);

EVENTS
   Local events
       The component will send the following POE events	to its session.

       "syndicator_started"

       Called after the	session	has been started (like "_start"	in
       POE::Kernel. This is where you should do	your POE-related setup work
       such as adding new event	handlers to the	session.

       "syndicator_stopped"

       Called right before the session is about	to die (like "_stop" in
       POE::Kernel).

   Input events
       Other POE sessions can send the following POE events to the
       Syndicator's session.

       "register"

       Takes any amount	of arguments: a	list of	event names that your session
       wants to	listen for, minus the prefix (specified	in "_syndicator_init"
       in "syndicator_init").

	$kernel->post('my syndicator', 'register', qw(join part	quit kick));

       Registering for the special event 'all' will cause it to	send all
       events to your session. Calling it with no event	names is equivalent to
       calling it with 'all' as	an argumente.

       Registering will	generate a "syndicator_registered" event that your
       session can trap.

       Registering with	multiple component sessions can	be tricky, especially
       if one wants to marry up	sessions/objects, etc. Check the SIGNALS
       section for an alternative method of registering	with multiple
       components.

       "unregister"

       Takes any amount	of arguments: a	list of	event names which you don't
       want to receive.	If you've previously done a "register" for a
       particular event	which you no longer care about,	this event will	tell
       the component to	stop sending them to you. (If you haven't, it just
       ignores you. No big deal.) Calling it with no event names is equivalent
       to calling it with 'all'	as an argument.

       If you have registered for the special event 'all', attempting to
       unregister individual events will not work. This	is a 'feature'.

       "shutdown"

       By default, POE::Component::Syndicator sessions never go	away. You can
       send its	session	a "shutdown" event manually to make it delete itself.
       Terminating multiple Syndicators	can be tricky. Check the "SIGNALS"
       section for a method of doing that.

       "_default"

       Any POE events sent to the Syndicator's session which do	not have a
       handler will go to the Syndicator's "_default" handler, will generate
       "USER events" of	the same name. If you install your own "_default"
       handler,	make sure you do the same thing	before you handle an event:

	use Object::Pluggable::Constants 'PLUGIN_EAT_ALL';

	$poe_kernel->state('_default', $self, '__default');

	sub __default {
	    my ($self, $event, $args) =	@_[OBJECT, ARG0, ARG1];

	    # do nothing if a plugin eats the event
	    return if $self->send_user_event($event, [@$args]) == PLUGIN_EAT_ALL;

	    # handle the event
	    # ...
	}

       Note that the handler for the "_default"	event must be named something
       other than '_default', because that name	is reserved for	the plugin-
       type default handler (see the Object::Pluggable docs).

   Output events
       The Syndicator will send	the following events at	various	times. The
       'syndicator_' prefix in these event names can be	customized with	a
       'prefix'	argument to "_syndicator_init" in "_syndicator_init".

       "syndicator_registered"

       Sent once to the	requesting session on registration (see	"register").
       "ARG0" is a reference to	the component's	object.

       "syndicator_shutdown"

       Sent to all interested sessions when the	component has been shut	down.
       See "_syndicator_destroy".

       "syndicator_delay_set"

       Sent to the subclass, plugins, and all interested sessions on a
       successful addition of a	delayed	event using the	"delay"	method.	"ARG0"
       will be the alarm_id which can be used later with "delay_remove".
       Subsequent parameters are the arguments that were passed	to "delay".

       "syndicator_delay_removed"

       Sent to the subclass, plugins, and all interested sessions when a
       delayed event is	successfully removed. "ARG0" will be the alarm_id that
       was removed.  Subsequent	parameters are the arguments that were passed
       to "delay".

       All other events

       All other events	sent by	the Syndicator are USER	events (generated with
       "send_user_event") and SERVER events (generated with "send_event*")
       which will be delivered normally. Your subclass and plugins are
       responsible for generating them.

SIGNALS
       The component will handle a number of custom signals that you may send
       using POE::Kernel's "signal" method. They allow any session to
       communicate with	every instance of the component	in certain ways
       without having references to their objects or knowing about their
       sessions. The names of these signals can	be customized with
       "_syndicator_init".

   "SYNDICATOR_REGISTER"
       Registers for an	event with the component. See "register".

   "SYNDICATOR_SHUTDOWN"
       Causes a	'shutdown' event to be sent to your session. Any arguments to
       the signal will be passed along to the event. That's where you should
       clean up	and call "_syndicator_destroy".

AUTHOR
       Hinrik Arn SigurA<degree>sson, hinrik.sig@gmail.com, Chris "BinGOs"
       Williams	chris@bingosnet.co.uk, Apocalypse apocal@cpan.org, and
       probably	others.

LICENSE	AND COPYRIGHT
       Copyright 2011 Hinrik Arn SigurA<degree>sson

       This program is free software, you can redistribute it and/or modify it
       under the same terms as Perl itself.

perl v5.32.0			  2011-06-20	 POE::Component::Syndicator(3)

NAME | SYNOPSIS | DESCRIPTION | PRIVATE METHODS | PUBLIC METHODS | EVENTS | SIGNALS | AUTHOR | LICENSE AND COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=POE::Component::Syndicator&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help