Stories
Slash Boxes
Comments
NOTE: use Perl; is on undef hiatus. You can read content, but you can't post it. More info will be forthcoming forthcomingly.

All the Perl that's Practical to Extract and Report

use Perl Log In

Log In

[ Create a new account ]

rhesa (5696)

rhesa
  (email not shown publicly)

Journal of rhesa (5696)

Wednesday April 13, 2005
06:26 PM

RFC: DBIx::Counter - persistent counter class

[ #24172 ]

Hi,

I've been a CPAN consumer for so long, I thought it's about time to start contributing.
I wrote a little module that does exactly the same as File::CounterFile, but with a database as storage engine.
It came into this world after a thread on www.experts-exchange.com; so there's at least one interested user for it.

Granted, it's nothing earth-shattering, but it's simple and generic enough to be useful outside my usual work, and it presents me with a manageable package to start my CPAN career.
Before I go all the way by applying for a PAUSE account and uploading it, I would like to put it to public scrutiny first. I'd like to know I'm doing things properly from the start.

Here's my list of questions:
- what about the module name? is it good?
- code review would be nice
- documentation: clear enough?
- tests: for a module this simple?
- exception handling: should I do this myself, or let DBI throw them?

The archive is here: http://www.rhesa.com/DBIx-Counter-0.01.tar.gz

Thanks for your attention!

Rhesa

Here's the pod:

NAME
        DBIx::Counter - Manipulate named counters stored in a database

SYNOPSIS
                use DBIx::Counter;
                $c = new DBIx::Counter('my counter',
                                                                dsn => 'dbi:mysql:mydb',
                                                                login => 'username',
                                                                password => 'secret'
                                                            );
                print $c->value;
                $c->inc;

DESCRIPTION
        This module creates and maintains named counters in a database. It has a
        simple interface, with methods to increment and decrement the counter by
        one, and a method for retrieving the value. It supports operator
        overloading for increment (++), decrement (--) and stringification ("").
        It should perform well in persistent environments, since it uses the
        connect_cached and prepare_cached methods of DBI. The biggest advantage
        over its main inspiration - File::CounterFile - is that it allows
        distributed, concurrent access to the counters and isn't tied to a
        single file system.

        Connection settings can be set in the constructor, or by using the
        package variables $DSN, $LOGIN and $PASSWORD and $TABLENAME. The table
        name is configurable, but the column names are currently hard-coded to
        counter_id and value. The following SQL statement can be used to create
        the table:

                CREATE TABLE counters (
                        counter_id varchar(64) primary key,
                        value int not null default 0
                );

        This module attempts to mimick the File::CounterFile interface, except
        currently it only supports integer counters. The locking functions in
        File::CounterFile are present for compatibility only: they always return
        0.

METHODS
        new Creates a new counter instance. First parameter is the required
                counter name. Second, optional, argument is an initial value for the
                counter on its very first use. It also accepts named parameters for
                the dbi connection string, dbi login and dbi password, and the table
                name:

                        dsn - overrides $DBIx::Counter::DSN
                        login - overrides $DBIx::Counter::LOGIN
                        password - overrides $DBIx::Counter::PASSWORD
                        tablename - overrides $DBIx::Counter::TABLENAME

                        Examples:
                        $c = new DBIx::Counter('my counter');
                        $c = new DBIx::Counter('my counter',
                                                                        dsn => 'dbi:mysql:mydb',
                                                                        login => 'username',
                                                                        password => 'secret'
                                                                    );
                        $c = new DBIx::Counter('my counter',
                                                                        42,
                                                                        dsn => 'dbi:mysql:mydb',
                                                                        tablename => 'gauges'
                                                                    );

        inc increases the counter by one.

                        $c->inc;
                        # or using overload:
                        $c++;

        dec decreases the counter by one.

                        $c->dec;
                        # or using overload:
                        $c--;

        value
                returns the current value of the counter.

                        print $c->value;
                        # or using overload:
                        print $c;

SEE ALSO
        File::CounterFile

AUTHOR
        Rhesa Rozendaal, .

COPYRIGHT AND LICENSE
        Copyright (C) 2005 by Rhesa Rozendaal

        This library is free software; you can redistribute it and/or modify it
        under the same terms as Perl itself, either Perl version 5.8.2 or, at
        your option, any later version of Perl 5 you may have available.

The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.
 Full
 Abbreviated
 Hidden
More | Login | Reply
Loading... please wait.
  • How is this different from a SQL sequence?
    • I suppose it could be used for sequences in databases that do not have those (such as Mysql, SQLLite and SQL Server), but the main difference is that this module doesn't care if you decrement a counter.

      The fact that it uses a database for storage, doesn't mean that it can only be used in a database context. You can count things, that's it.

      It's meant as a (drop in) replacement of File::CounterFile. My module gives you an (well, almost) identical API, but the storage is centralised. That means you can acces