GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  ALGORITHM::FLOODCONTROL (3)

.ds Aq ’

NAME

Algorithm::FloodControl - Limit event processing to count/time ratio.

CONTENTS

SYNOPSIS

    Functional interface



    use Algorithm::FloodControl;

    my $wait = flood_check( 5, 60, FLOOD EVENT NAME );

    if( $wait ) {
        print "Please wait $wait sec. before requesting this resource again.";
    } else {
        print "Ok, here you are.";
    }



    Object-oriented interface



    use Algorithm::FloodControl ();

    my $flood_control = Algorithm::FloodControl->new(
        storage => $memd,
        limits => {
            limit_name => [
                {
                    period => 60,
                    attempts => 5,
                }, {
                    period => 3600,
                    attempts => 30,
                }
            ]
        }
    );

    $flood_control->register_attempt( limit_name => vasja_pupkin );

    my $attempt_count = $flood_control->get_attempt_count( limit_name => vasja_pupkin ); # 1

    if ( $flood_control->is_user_overrated( limit_name => vasja_pupkin ) ) {
        die "XXXXXX, XXXXX XXXXX (:";
    }



DESCRIPTION

Flood control method is used to restrict the number of events to happen or to be processed in specific perion of time. Few examples are: web server can limit requsets number to a page or you may want to receive no more than 10 SMS messages on your GSM Phone per hour. Applications of this method are unlimited.

FUNCTIONS

This module exports several functions:
flood_check( $count, $time, $event_name ) This function is the core of the module. It receives 3 arguments: maximum event count, maximum time period (in seconds) for this event count and finally the event name. There is internal storage so flood_check() can track several events by name.

Third argument could be omitted. In this case the event name will be constructed from the package name, file name and line number from the calling point. However this is not recommendet unless you need it for very simple program.

The return value is time in seconds that this event must wait to be processed or 0 if event can be processed immediately.

flood_storage( <$ref> ) If you want to save and restore the internal storage (for example for cgi use), you can get reference to it with flood_storage() function which returns this reference and it can be stored with other module like FreezeThaw or Storable. When restoring you must pass the storage reference as single argument to flood_storage().

METHODS

new( storage => $cache, limits => \%limits ) Creates new object. $cache can be Cache::Memcached or Cache::Memcached::Fast object.
register_attempt( $limit_type, $identifier ) Increments attempt counter for $identifier.
forget_attempts( $limit_type, $identifier ) Sets attempt counter to zero
get_attempt_count( $limit_type, $identifier ) Returns count of attempts
is_user_overrated( $limit_type, $identifier ) If user have reached his limits returns time to unlocking in seconds. Otherwise returns 0

EXAMPLE

CGI script is very usefull as example because it has all elements of Algorithm::FloodControl use:



    #!/usr/bin/perl
    use strict;
    use Storable qw( store retrieve ); # used to save/restore the internal data
    use LockFile::Simple qw( lock unlock ); # used to lock the data file
    use Algorithm::FloodControl;

    my $flood_file = "/tmp/flood-cgi.dat";

    lock( $flood_file );                                   # lock the storage
    my $FLOOD = retrieve( $flood_file ) if -r $flood_file; # read storage data
    flood_storage( $FLOOD ) if $FLOOD;                     # load storage
    my $wait = flood_check( 5, 60, FLOOD TEST CGI );     # check for flood
    store( flood_storage(), $flood_file );                 # save storage data
    unlock( $flood_file );                                 # unlock the file

    print "Content-type: text/plain\n\n";
    if( $wait ) {
        print "Please wait $wait seconds before requesting this page again.\n";
        exit;
    }
    print "Hello, this is main script here\n";



This example is just one of very large number of cases where flood control can be useful. I used it in IRC bots, email notifications, web site updates, etc.

AUTHOR



    Vladi Belperchinov-Shabanski "Cade" - up to 1.00

    <cade@biscom.net> <cade@datamax.bg> <cade@cpan.org>

    http://cade.datamax.bg

    Andrey Kostenko "GuGu" <andrey@kostenko.name> - 1.00 - 2.00

    http://kostenko.name



BUGS

No bugs.

NOTES

COPYRIGHT & LICENSE

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

VERSION



    $Id: FloodControl.pm 7 2008-11-06 12:51:33Z gugu $



POD ERRORS

Hey! <B>The above document had some coding errors, which are explained below:B>
Around line 228: Non-ASCII character seen before =encoding in ’"XXXXXX,’. Assuming UTF-8
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 ALGORITHM::FLOODCONTROL (3) 2011-03-22

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.