NAME
Event::Lite - Distributed Event Broadcast System for Perl
SYNOPSIS
NOTE: - The synopses are subject to drastic change, as this code is still alpha.
WARNING: - More extensive testing is still underway. For example, repeated subscribe/disconnect scenarios have not been thoroughly tested yet.
Server
use Event::Lite::Server;
my $server = Event::Lite::Server->new(
# Required params:
address => '127.0.0.1',
port => 34343,
# Optional params:
on_authenticate_publisher => sub {
my ($socket, $event_type, $username, $password) = @_;
# If the publisher is ok, then return true:
return 1;
},
on_authenticate_subscriber => sub {
my ($socket, $event_type, $username, $password) = @_;
# If the subscriber is ok, then return true:
return 1;
},
);
# Install some signal handlers:
$SIG{INT} = $SIG{TERM} = sub {
return unless $server->running;
warn "Shutting down...\n";
$server->stop();
};
$SIG{HUP} = sub {
warn "Restarting server on port $port...\n";
$server->stop();
$server->run();
};
warn "Starting server on port $port...\n";
$server->run();
sleep(1) while 1;
# Fell out of loop:
$server->stop();Subscribing to Events
# Import the addEventListener and dispatchEvent functions:
use Event::Lite;
# Just tell Event::Lite where the server is:
Event::Lite->server( '127.0.0.1:34343', 'username', 'password' );
addEventListener(
event => 'foo',
callback => sub {
my $event = shift;
warn "$event->{event} happened: $event->{bar}"; # 'foo happened: Hello World'
}
);Publishing Events
# Import the addEventListener and dispatchEvent functions:
use Event::Lite;
# Just tell Event::Lite where the server is:
Event::Lite->server( '127.0.0.1:34343', 'username', 'password' );
# Then, someplace else, in the same program, different program, same machine or different machine:
dispatchEvent(
event => 'foo',
bar => 'Hello World'.
);DESCRIPTION
Event::Lite aims to provide a distributed event broadcast system for Perl.
This means that an event (i.e. Price of Tea in China (PTC) changes) can occur in one system, and any number of "subscriber" systems can be instantly notified, regardless of whether they are on the same system or network (or even written in Perl).
Since sending and receiving events requires only sockets, base64-encoding/decoding and JSON, Event::Lite is language-agnostic.
Architecture
Event::Lite basically has 4 components:
Server
The part responsible for connecting subscribers and publishers.
Publisher
The where events are generated.
Subscriber
Something that cares about a specific kind of event. It can expect the server to let it know when that kind of event happens.
Event
An object that describes the Who, What, When, Where, Why and How of what happened.
Events are just simple hashrefs - not even blessed.
Protocol
Subscribe
A subscribe request looks like this:
subscribe/event-name:username|passwordSo, to subscribe to events named "foo" you would send:
subscribe/foo:admin|swordfishPublish
A publish request looks like this:
publish/event-name:username|password
<base64-encoded JSON>So, to publish an event named "foo" you would send:
publish/foo:admin|swordfish
AB384dsd93jk4j2h3g4jh23g4jh2g34jhg234jhg23jh4g==PERFORMANCE
As of version 0.003 Event::Lite offers approximately 500 events per second when sending 100 small events (i.e. "hello world" events) to 10 subscribers on the same machine.
The size of the event data, the number of subscribers, and network latency will slow that number down.
BEST PRACTICES
Use Small Events
Try to keep your events - when serialized - less than 1024**2 bytes.
Send Events, Not Data
Event::Lite is intended for near-real-time message broadcasts, not multicast of large datasets.
Security
By default, all events go over the wire encoded, but not encrypted. Don't send sensitive data within the arguments of an event.
AUTHENTICATION
You can grant or deny access to publishers and subscribers.
The two authenticated types - publishers and subscribers - can be authenticated separately. Authentication can be based on the username, password and event type.
Authenticating Publishers and Subscribers
When the Server is instantiated, one of the optional arguments is on_authenticate_publisher which whould be a code reference.
An example of how to do this is as follows:
my $server = Event::Lite::Server->new(
address => '127.0.0.1',
port => '34343',
on_authenticate_publisher => \&authenticate_publisher,
on_authenticate_subscriber => \&authenticate_subscriber,
);
# Authenticate a publisher:
sub authenticate_publisher {
my ($socket, $event_type, $username, $password) = @_;
if( is authenticated ) {
return 1;
}
else {
return 0;
}
}
# Authenticate a subscriber:
sub authenticate_subscriber {
my ($socket, $event_type, $username, $password) = @_;
if( is authenticated ) {
return 1;
}
else {
return 0;
}
}Once the server is configured as shown above, publishers and subscribers will always be authenticated.
PUBLIC METHODS
Event::Lite->server( address:port, [username, password ])
See synopsis for usage examples.
Defines the connection to the event server.
EXPORTED FUNCTIONS
addEventListener( event => event_name, callback => sub {...} )
See the synopsis for usage examples.
NOTE: The callback will be executed in a separate thread or process and may not have access to variables in the local context.
Using forks::shared to share variables will get around this limitation.
dispatchEvent( event => event_name, %misc_args )
The only required parameter is event.
Any other parameters in the hash will be sent just as they are.
NOTE: - Sending of blessed objects, sockets or file handles is not supported.
SUPPORT
Visit http://www.devstack.com/contact/ or email the author at <jdrago_999@yahoo.com>
Commercial support and installation is available.
AUTHOR
John Drago <jdrago_999@yahoo.com>
COPYRIGHT AND LICENSE
Copyright (C) 2008 by John Drago
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.0 or, at your option, any later version of Perl 5 you may have available.