Author: bdonlan
Date: 2004-08-17 14:16:23 -0400 (Tue, 17 Aug 2004)
New Revision: 350
Modified:
trunk/main/client/lib/Haver/Client/POE.pm
Log:
Make a ->register and ->unregister function for broadcast events.
Modified: trunk/main/client/lib/Haver/Client/POE.pm
===================================================================
--- trunk/main/client/lib/Haver/Client/POE.pm 2004-08-12 02:37:29 UTC (rev
349)
+++ trunk/main/client/lib/Haver/Client/POE.pm 2004-08-17 18:16:23 UTC (rev
350)
@@ -401,7 +401,7 @@
$type is the type of event, $name is the event name, and $args is an array ref
of arguments for the event.
-If $handled is 0 when the handler returns, the next handler in the chain will
+If $$handled is 0 when the handler returns, the next handler in the chain will
be called. Any changes to the contents of $args will be passed on.
If no handler in a chain handles the event, an event with the same type and
@@ -409,7 +409,7 @@
to @args. If no handler in the _default chain handles the event, it will be
discarded.
-=head2 METHODS FOR EVENT MANIPULATION
+=head2 METHODS FOR HANDLER MANIPULATION
=head3 register_handler($Z<>type, $Z<>event, $Z<>handler)
@@ -476,7 +476,7 @@
}
for my $handler (@{$ev->{forward}}) {
my $handled = 0;
- $handler->($handled, $type, $event, [EMAIL PROTECTED]);
+ $handler->(\$handled, $type, $event, [EMAIL PROTECTED]);
return if $handled;
}
if ($event ne '_default') {
@@ -489,11 +489,11 @@
1;
__END__
-=head2 TYPES OF EVENTS
+=head2 TYPES OF HANDLERS
=head3 want
-Events of type 'want' are sent when the server sends a S: WANT message. The
+Handlers of type 'want' are invoked when the server sends a S: WANT message.
The
first argument of the S: WANT is the event name, the rest are used as
arguments for the first handler.
@@ -502,28 +502,78 @@
=head3 smsg
-Events of type 'smsg' are sent whenever a command is received from the server.
+Handlers of type 'smsg' are invoked whenever a command is received from the
server.
The command name is used for the event name, and the arguments are passed for
the first handler's @args.
Note that adding a handler with $type of smsg, and $event of 'WANT' may
prevent handlers of $type want from being called.
-=head3 client
+=head1 EVENTS
+Events are sent to inform multiple handlers of some happening on the server.
+Any number of event callbacks may be registered to an event, and they will all
+be invoked in an undefined order when the event is dispatched.
+
+=cut
+
+# implementation notes:
+# events are implemented with handlers, with type 'event'
+# register and unregister create an anonymous wrapper closure to hide the
+# details. These subs are stored in %{$self->{evwrap}}
+# TODO: expire evwrap entries
+
+=head2 EVENT MANIPULATION FUNCTIONS
+
+=head3 register(event => handler)
+
+Registers to receive a specified event with the specified handler function.
+The special event 'all' may be used to receive all events.
+
+=cut
+
+sub register {
+ my ($self, @events) = @_;
+ while (@events) {
+ my ($ev, $handler) = splice @events, 0, 2;
+ my $wrap = $self->{evwrap}{$handler} || sub {
+ my ($handled, $type, $name, $args) = @_[1..3];
+ if ($type ne 'event') {
+ die "Impossible: event handler on non-event
type!";
+ }
+ $handler->($name, @$args);
+ };
+ $self->{evwrap}{$handler} = $wrap;
+ $self->register_handler('event', $ev, $wrap);
+ }
+}
+
+=head3 unregister(event => handler)
+
+Unregisters the given handler for the specified event.
+
+=cut
+
+sub unregister {
+ my ($self, @events) = @_;
+ while (@events) {
+ my ($ev, $handler) = splice @events, 0, 2;
+ my $wrap = $self->{evwrap}{$handler} or next;
+ $self->unregister_handler('event', $ev, $wrap);
+ }
+}
+
+
+=head2 TYPES OF EVENTS
+
Client events have the following prototype:
- sub handler {
- my ($handled, $type, $event, $_args) = @_;
- my ($context, @evargs) = @$_args;
+ sub event {
+ my ($type, $event, @args) = @_;
# ...
}
-$context is a hash reference with the following arguments:
-* IN - Indicates the channel set by S: IN
-* ON - Indicated the UID set by S: ON
-
-The contents of @evargs vary depending on the event name, and are documented
+The contents of @args vary depending on the event name, and are documented
below.
=head4 connected(Z<>)
