The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Net-MessageBus-0.08
River stage zero No dependents
++
/ Net::MessageBus

NAME

Net::MessageBus - Pure Perl simple message bus

VERSION

Version 0.08

SYNOPSIS

This module implements the client side of the Message Bus.

    use Net::MessageBus;
    my $MessageBus = Net::MessageBus->new(
                        server => '127.0.0.1',
                        group => 'backend',
                        sender => 'machine1',
                        username => 'user',
                        password => 'password',
                        logger  => $logger_object,
                        blocking => 0,
                        timeout => 0.01
                    );

On initialization the client authenticates with the Net::MessageBus::Server after which it can start pushing messages to the bus.

In order to receive any messages from the bus the client must subscribe to :

  • one or more groups

  • one or more senders

  • one or more message types

  • all messages

    #each can be called multiple times
    $MessageBus->subscribe(group => 'test');
    $MessageBus->subscribe(sender => 'test_process_1');
    $MessageBus->subscribe(type => 'test_message_type');
    
    or
    
    $MessageBus->subscribe_to_all();

The client can unsubscribe at any time by calling the unsubscribe method

    $MessageBus->unsubscribe();

To retrive the messages received from the bus, the client can call one of this methods :

    my @messages = $MessageBus->pending_messages();
    
    or
    
    my $message = $MessageBus->next_message();

EXAMPLE

    use Net::MessageBus;

    my $MessageBus = Net::MessageBus->new(server => '127.0.0.1',
                          group => 'backend',
                          sender => 'machine1');
    
    $MessageBus->subscribe_to_all();
    or
    $MessageBus->subscribe(group => 'test');
    $MessageBus->subscribe(sender => 'test_process_1');
    ...
    
    my @messages = $MessageBus->pending_messages();
    or
    while (my $message = $MessageBus->next_message()) {
        print $message->type();
    }

SUBROUTINES/METHODS

new

Creates a new New::MessageBus object

Arguments

  • server = The ip address of the server

  • port = The port on which the server is listening for connections

  • group = The group to which this client belogs to

  • sender = A name for the current client

  • username = User name that will be sent to the server for authentication

  • password = The password that will be sent to the server for authentication

  • logger = A object on which we can call the fallowing methods debug,info,warn,error

  • block = if we don't have any unread messages from the server we will block until the server sends something. If block is true timeout will be ignored.

  • timeout = the maximum ammount of time we should wait for a message from the server before returning undef for next_message() or an empty list for pending_messages()

Example

    my $MessageBus = Net::MessageBus->new(
                        server => '127.0.0.1',
                        group => 'backend',
                        sender => 'machine1',
                        username => 'user',
                        password => 'password',
                        logger  => $logger_object,
                    );

subscribe

Subscribes the current Net::MessageBus client to the messages from the specified category. It can be called multiple times

Example :

    $MessageBus->subscribe(group => 'test');
    or 
    $MessageBus->subscribe(sender => 'test_process_1');

subscribe_all

Subscribes the current Net::MessageBus client to all the messages the server receives

Example :

    $MessageBus->subscribe_all;

unsubscribe

Unsubscribes current Net::MessageBus client from all the messages it previously subscribed to

Example :

    $MessageBus->unsubscribe();

send

Send a new messge to the message queue. It has two forms in which it can be called :

1. With a Net::MessageBus::Message object as argument
2. With a hash ref containing the fallowing two keys :

  • type = The message type

  • payload = The actual information we want to send with the message. It can be a scalar, array ref or hash ref and it cannot contain any objects

Example :

    $MessageBus->send( $message ); #message must be a Net::MessageBus::Message object
    or
    $MessageBus->send( type => 'alert', payload => { a => 1, b => 2 }  );

next_message

Returns the next message from the queue of messages we received from the server. The message is a Net::MessageBus::Message object.

pending_messages

Returns all the messages received until now from the server. Each message is a Net::MessageBus::Message object.

Argumens :

  • force_read_queue = forces a read of everyting the server might have sent and we have't processed yet

    Note: Forcing a read of the message queue when block mode is on will block the call until we received something from the server

blocking

Getter/Setter for the blocking setting of the client. If set to true, when waiting for server messages, the client will block until it receives something

Examples : my $blocking = $MessageBus->blocking(); or $MessageBus->blocking(1);

timeout

Getter/Setter for the timeout when waiting for server messages. It can have subunitary value (eg. 0.01).

Note1 : When blocking is set to a true value, the timeout is ignored Note2 : When timeout is set to 0 the effect is the same as setting blocking to a true value.

Example : my $timeout = $MessageBus->timeout(); or $MessageBus->timeout(0.01);

Private methods

This methods are for internal use and should not be called manually

connect_to_server

Creates a connection to the Net::MessageBus server and authenticates the user

send_to_server

Handles the actual comunication with the server

authenticate

Sends a authenication request to the server and waits for the response

get_response

Returns the response received from the server for the last request

read_server_messages

Reads all the messages received from the server and adds the to the internal message queue

SEE ALSO

Check out Net::MessageBus::Server which implements the server of the MessageBus and Net::MessageBus::Message which is the OO inteface for the messages passwed between the client and the server

AUTHOR

Horea Gligan, <gliganh at gmail.com>

BUGS

Please report any bugs or feature requests to bug-net-MessageBus at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Net-MessageBus. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Net::MessageBus

You can also look for information at:

ACKNOWLEDGEMENTS

Thanks to Manol Roujinov for helping to improve this module

LICENSE AND COPYRIGHT

Copyright 2012 Horea Gligan.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.