NAME

Number::YAUID - A decentralized unique ID generator (int64)

SYNOPSIS

 use Number::YAUID;
 
 my $object = Number::YAUID->new("/tmp/lock.file", "/etc/node.id");
 # OR
 #my $object = Number::YAUID->new("/tmp/lock.file", undef, node_id => 321);
 die get_error_text_by_code($object) unless ref $object;
 
 print "Max inc on sec: ", get_max_inc(), "\n";
 print "Max node id: ", get_max_node_id(), "\n";
 print "Max timestamp: ", get_max_timestamp(), "\n";
 
 foreach (0..5000)
 {
        my $key = $object->get_key();
        die get_error_text_by_code($object->get_error_code()) if $object->get_error_code();
        
        print "key: ", $key, "\n";
        print "\ttimestamp: ", timestamp_to_datetime( $object->get_timestamp_by_key($key) ), "\n";
        print "\tnode id: "  , $object->get_node_id_by_key($key)  , "\n";
        print "\tinc id: "   , $object->get_inc_id_by_key($key)   , "\n";
 }
 

DESCRIPTION

Id generation at a node should not require coordination with other nodes. Ids should be roughly time-ordered when sorted lexicographically.

METHODS

new

 my $object = Number::YAUID->new(<file path to lockfile>, <file path to node id>[, params args]);

 my %p_args = (
        try_count  => 0,     # count of key get attempts, 0 = unlimited
        sleep_usec => 35000, # sleep 0.35 sec if limit key inc expired on current second
        node_id    => 321    # current node id
 );
 
 my $object = Number::YAUID->new("/tmp/lock.file", undef, %p_args);
 

Create and prepare base structure. Return object or undef if something went wrong.

get_key

 my $key = $object->get_key();

Return a unique ID

get_period_key_by_datetime

 my $key = get_period_key_by_datetime(<from datetime>, <to datetime>, <from node ID>, <to node ID>);

from datetime

YYYY-MM-DD hh:mm:ss

to datetime

YYYY-MM-DD hh:mm:ss if <to datetime> = 0, then <to datetime> = <from datetime>

from node ID

1 to get_max_node_id() if <from node ID> = 0, then <from node ID> = 1

to node ID

1 to get_max_node_id() if <to node ID> = 0, then <to node ID> = get_max_node_id()

Return arrey ref where [0] = min, [1] = max unique ID

get_period_key_by_timestamp

 my $key = get_period_key_by_timestamp(<from timestamp>, <to timestamp>, <from node ID>, <to node ID>);

from timestamp

timestamp

to timestamp

timestamp if <to timestamp> = 0, then <to timestamp> = <from timestamp>

from node ID

1 to get_max_node_id() if <from node ID> = 0, then <from node ID> = 1

to node ID

1 to get_max_node_id() if <to node ID> = 0, then <to node ID> = get_max_node_id()

Return arrey ref where [0] = min, [1] = max unique ID

get_error_code

 $object->get_error_code();

Return error code.

get_error_text_by_code

 get_error_text_by_code(<error code>);

Return description by error code

get_timestamp_by_key

 $object->get_timestamp_by_key(<key>);

Return timestamp from a key

get_node_id_by_key

 $object->get_node_id_by_key(<key>);

Return node id from a key

get_inc_id_by_key

 $object->get_inc_id_by_key(<key>);

Return inc id from a key

timestamp_to_datetime

 timestamp_to_datetime(<timestamp>);

Convert timestamp to datetime (YYYY-MM-DD hh:mm:ss)

DESTROY

 undef $obj;

Free mem and destroy object.

AUTHOR

Alexander Borisov <lex.borisov@gmail.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by Alexander Borisov.

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

cpanm Number::YAUID

perl -MCPAN -e shell
install Number::YAUID