NAME

Redis::CappedCollection - Provides fixed sized collections that have a auto-FIFO age-out feature.

VERSION

This documentation refers to Redis::CappedCollection version 0.16

SYNOPSIS

    use 5.010;
    use strict;
    use warnings;

    #-- Common
    use Redis::CappedCollection qw(
        DEFAULT_SERVER
        DEFAULT_PORT
    );

    my $server = DEFAULT_SERVER.':'.DEFAULT_PORT;
    my $coll = Redis::CappedCollection->new( redis => $server );

    #-- Producer
    my $list_id = $coll->insert( 'Some data stuff' );

    # Change the element of the list with the ID $list_id
    $updated = $coll->update( $list_id, $data_id, 'Some new data stuff' );

    #-- Consumer
    # Get data from a list with the ID $list_id
    @data = $coll->receive( $list_id );
    # or to obtain the data in the order they are received
    while ( my ( $list_id, $data ) = $coll->pop_oldest ) {
        say "List '$list_id' had '$data'";
    }

To see a brief but working code example of the Redis::CappedCollection package usage look at the "An Example" section.

To see a description of the used Redis::CappedCollection data structure (on Redis server) look at the "CappedCollection data structure" section.

ABSTRACT

Redis::CappedCollection module provides fixed sized collections that have a auto-FIFO age-out feature.

DESCRIPTION

The module provides an object oriented API. This makes a simple and powerful interface to these services.

The main features of the package are:

Provides an object oriented model of communication.
Support the work with data structures on the Redis server.
Supports the automatic creation of capped collection, status monitoring, updating the data set, obtaining consistent data from the collection, automatic data removal, the classification of possible errors.
Simple methods for organizing producer and consumer clients.

Capped collections are fixed sized collections that have an auto-FIFO age-out feature (age out is based on the time of the corresponding inserted data). With the built-in FIFO mechanism, you are not at risk of using excessive disk space. Capped collections keep data in their time corresponding inserted data order automatically (in the respective lists of data). Capped collections automatically maintain insertion order for the data lists in the collection.

You may insert new data in the capped collection. If there is a list with the specified ID, the data is inserted into the existing list, otherwise it is inserted into a new list.

You may update the existing data in the collection.

Once the space is fully utilized, newly added data will replace the oldest data in the collection. Limits are specified when the collection is created.

Old data with the same time will be forced out in no specific order.

The collection does not allow deleting data.

Automatic Age Out: If you know you want data to automatically "roll out" over time as it ages, a capped collection can be an easier way to support than writing manual removal via cron scripts.

EXPORT

None by default.

Additional constants are available for import, which can be used to define some type of parameters.

These are the defaults:

`DEFAULT_SERVER`

Default Redis local server - 'localhost'.

`DEFAULT_PORT`

Default Redis server port - 6379.

`NAMESPACE`

Namespace name used keys on the Redis server - 'Capped'.

Error codes are identified: More details about error codes are provided in "DIAGNOSTICS" section.

Possible error codes:

ENOERROR

0 - No error

EMISMATCHARG

1 - Invalid argument.

This means that you didn't give the right argument to a new or to other method.

EDATATOOLARGE

2 - Data is too large.

ENETWORK

3 - Error in connection to Redis server.

EMAXMEMORYLIMIT

4 - Command not allowed when used memory > 'maxmemory'.

This means that the command is not allowed when used memory > maxmemory in the redis.conf file.

EMAXMEMORYPOLICY

5 - Data may be removed by maxmemory-policy all* .

This means that you are using the maxmemory-police all* in the redis.conf file.

ECOLLDELETED

6 - Collection was removed prior to use.

This means that the system part of the collection was removed prior to use.

EREDIS

7 - Redis error message.

This means that other Redis error message detected.

EDATAIDEXISTS

8 - Attempt to add data to an existing ID

This means that you are trying to insert data with an ID that is already in the data list.

EOLDERTHANALLOWED

9 - Attempt to add data over outdated

This means that you are trying to insert the data with the time less than the time of the data that has been deleted from the data list.

GLOBAL VARIABLES

$REDIS_MEMORY_OVERHEAD

In addition to user-supplied data, Redis uses memory for its metadata and bookkeeping. This overhead may cause significantly higher (e.g. 10x) memory usage than actual amount of your data stored in collection. $REDIS_MEMORY_OVERHEAD is a rough estimate of additional memory usage. Collection multiplies its size by $REDIS_MEMORY_OVERHEAD to estimate how much memory it will use in Redis. Actual usage depends on data item size, average list size and other factors, so default estimate may not work in your case. Adjust $REDIS_MEMORY_OVERHEAD according to your application needs; this may require some experiments to get a good estimate.

By default, the following value is used:

    our $REDIS_MEMORY_OVERHEAD = 3; # 3 times more than actual data

CONSTRUCTOR

`new( redis => $server, ... )`

It generates a Redis::CappedCollection object to communicate with the Redis server and can be called as either a class method or an object method. If invoked with no arguments the constructor new creates and returns a Redis::CappedCollection object that is configured to work with the default settings.

If invoked with the first argument being an object of Redis::CappedCollection class or Redis class, then the new object connection attribute values are taken from the object of the first argument. It does not create a new connection to the Redis server.

According to Redis documentation:

This module consider that any data sent to the Redis server is a raw octets string, even if it has utf8 flag set. And it doesn't do anything when getting data from the Redis server.

UTF-8 data should be serialized before passing to Redis::CappedCollection for storing in Redis.

new optionally takes arguments. These arguments are in key-value pairs.

This example illustrates a new() call with all the valid arguments:

    my $coll = Redis::CappedCollection->new(
        redis   => "$server:$port", # Default Redis local server and port
        name    => 'Some name', # If 'name' is not specified, it creates
                        # a new collection named as UUID.
                        # If specified, the work is done with
                        # a given collection or a collection is
                        # created with the specified name.
        size            => 100_000, # The maximum size, in bytes,
                        # of the capped collection data.
                        # Default 0 - no limit.
                        # Is set for the new collection.
        advance_cleanup_bytes => 50_000, # The minimum size, in bytes,
                        # of the data to be released, if the size
                        # of the collection data after adding new data
                        # may exceed 'size'
                        # Default 0 - additional data should not be released.
        advance_cleanup_num => 1_000, # Maximum number of data
                        # elements to delete, if the size
                        # of the collection data after adding new data
                        # may exceed 'size'
                        # Default 0 - the number of times the deleted data
                        # is not limited.
        max_datasize    => 1_000_000,   # Maximum size, in bytes, of the data.
                        # Default 512MB.
        older_allowed   => 0, # Permission to add data with time is less
                        # than the data time of which was deleted from the list.
                        # Default 0 - insert too old data is prohibited.
                        # Is set for the new collection.
        big_data_threshold => 0, # The maximum number of items of data to store
                        # in an optimized format to reduce memory usage.
                        # Default 0 - storage are separate hashes and
                        # ordered lists.
                        # Is set for the new collection.
                        # To see a description of the used
                        # Redis::CappedCollection data structure
                        # (on Redis server) look at the
                        # "CappedCollection data structure" section.
        check_maxmemory => 1,   # Optional boolean argument (default is true)
                        # defines if attempt is made to find out maximum
                        # available memory from Redis.
                        # In some cases Redis implementation forbids such request,
                        # but setting 'check_maxmemory' to false can be used
                        # as a workaround. In this case we assume that
                        # 'maxmemory-policy' is 'volatile-lru'
                        # (as default in 'redis.conf').
    );

Requirements for arguments name, size, are described in more detail in the sections relating to the methods "name", "size" .

If the value of name is specified, the work is done with a given collection or creates a new collection with the specified name. Do not use the symbol ':' in name.

The following examples illustrate other uses of the new method:

    $coll = Redis::CappedCollection->new();
    my $next_coll = Redis::CappedCollection->new( $coll );

    my $redis = Redis->new( redis => "$server:$port" );
    $next_coll = Redis::CappedCollection->new( $redis );

An error will cause the program to halt (confess) if an argument is not valid.

METHODS

An error will cause the program to halt (confess) if an argument is not valid.

ATTENTION: In the Redis module the synchronous commands throw an exception on receipt of an error reply, or return a non-error reply directly.

`name`

The method of access to the name attribute (collection ID). The method returns the current value of the attribute. The name attribute value is used in the constructor.

If the value of name is not specified to the constructor, it creates a new collection ID as UUID.

`size`

The method of access to the size attribute - the maximum size, in bytes, of the capped collection data (Default 0 - no limit).

The method returns the current value of the attribute. The size attribute value is used in the constructor.

Is set for the new collection. Otherwise an error will cause the program to halt (confess) if the value is not equal to the value that was used when a collection was created.

`advance_cleanup_bytes`

The method of access to the advance_cleanup_bytes attribute - the minimum size, in bytes, of the data to be released, if the size of the collection data after adding new data may exceed "size". Default 0 - additional data should not be released.

The advance_cleanup_bytes attribute is designed to reduce the release of memory operations with frequent data changes.

The advance_cleanup_bytes attribute value can be used in the constructor. The method returns and sets the current value of the attribute.

The advance_cleanup_bytes value may be less than or equal to "size". Otherwise an error will cause the program to halt (confess).

`advance_cleanup_num`

The method of access to the advance_cleanup_num attribute - maximum number of data elements to delete, if the size of the collection data after adding new data may exceed size. Default 0 - the number of times the deleted data is not limited.

The advance_cleanup_num attribute is designed to reduce the number of deletes data.

The advance_cleanup_num attribute value can be used in the constructor. The method returns and sets the current value of the attribute.

`max_datasize`

The method of access to the max_datasize attribute.

The method returns the current value of the attribute if called without arguments.

Non-negative integer value can be used to specify a new value to the maximum size of the data introduced into the collection (methods "insert" and "update").

The max_datasize attribute value is used in the constructor and operations data entry on the Redis server.

The constructor uses the smaller of the values of 512MB and maxmemory limit from a redis.conf file.

`older_allowed`

The method of access to the older_allowed attribute - permission to add data with time less than the data time which was deleted from the data list. Default 0 - insert too old data is prohibited.

The method returns the current value of the attribute. The older_allowed attribute value is used in the constructor.

`big_data_threshold`

The method of access to the big_data_threshold attribute - determines the maximum data size to store in an optimzed format. Data stored in this way will use less memory but require additional processing to access. Default 0 - storage are separate hashes and ordered lists.

Can be used to save memory. It makes sense to use on small lists of data. Leads to a decrease in performance when using large lists of data.

The method returns the current value of the attribute. The big_data_threshold attribute value is used in the constructor.

To see a description of the used Redis::CappedCollection data structure (on Redis server) look at the "CappedCollection data structure" section.

The effective value of big_data_threshold depends on the conditions the collection: the item size and length of lists, the size of data identifiers, etc.

The effective value of big_data_threshold can be controlled with server settings (hahs-max-ziplist-entries, hash-max-ziplist-value, zset-max-ziplist-entries, zset-max-ziplist-value) in the redis.conf file.

`last_errorcode`

The method of access to the code of the last identified errors.

To see more description of the identified errors look at the "DIAGNOSTICS" section.

`insert( $data, $list_id, $data_id, $data_time )`

Adds data to the capped collection on the Redis server.

Data obtained in the first argument. Data should be a string whose length should not exceed the value available through the method "max_datasize".

Data is added to the existing list, if the second argument is specified and the corresponding queue already exists. Otherwise, the data is added to a new queue for which ID is the second argument. ID in the second argument must be a non-empty string (if specified). Do not use the symbol ':' in $list_id.

If the second argument is not specified, the data is added to a new list with automatically generated ID (UUID).

The data may be given a unique ID and a unique time. If the ID is not specified (or an empty string), it will be automatically generated in the form of sequential integer. Data ID must be unique for a list of data.

Time must be a non-negative number. If time is not specified, it will be automatically generated as the result of a function time.

For measuring time in better granularity than one second, use the Time::HiRes module. In this case, time value is stored on the server as a floating point number within 4 decimal places.

The following examples illustrate uses of the insert method:

In a scalar context, the method returns the ID of the data list to which you add the data.

    $list_id = $coll->insert( 'Some data stuff', 'Some_id' );
    # or
    $list_id = $coll->insert( 'Some data stuff' );

In a list context, the method returns the ID of the data list to which your adding the data and the data ID corresponding to your data.

    ( $list_id, $data_id ) = $coll->insert( 'Some data stuff', 'Some_id' );
    # or
    ( $list_id, $data_id ) = $coll->insert( 'Some data stuff' );

`update( $list_id, $data_id, $data )`

Updates the data in the queue identified by the first argument. $list_id must be a non-empty string.

The updated data ID given as the second argument. The $data_id must be a non-empty string.

New data should be included in the third argument. Data should be a string whose length should not exceed the value available through the method "max_datasize".

The following examples illustrate uses of the update method:

    if ( $coll->update( $list_id, 0, 'Some new data stuff' ) ) {
        say "Data updated successfully";
    } else {
        say "The data is not updated";
    }

Method returns true if the data is updated or false if the queue with the given ID does not exist or is used an invalid data ID.

`receive( $list_id, $data_id )`

If the $data_id argument is not specified or is an empty string:

In a list context, the method returns all the data from the list given by the $list_id identifier. If the $data_id argument is an empty string then it returns all data IDs and data values of the data list. These returns are not ordered.

Method returns an empty list if the list with the given ID does not exist.
In a scalar context, the method returns the length of the data list given by the $list_id identifier.

If the $data_id argument is specified:

The method returns the specified element of the data list. If the data with $data_id ID does not exists, undef is returned.

$list_id must be a non-empty string. $data_id must be a normal string.

The following examples illustrate uses of the receive method:

    my @data = $coll->receive( $list_id );
    say "List '$list_id' has '$_'" foreach @data;
    # or
    my $list_len = $coll->receive( $list_id );
    say "List '$list_id' has '$list_len' item(s)";
    # or
    my $data = $coll->receive( $list_id, 0 );
    say "List '$list_id' has '$data' in 'zero' position";

`pop_oldest`

The method is designed to retrieve the oldest data stored in the collection.

Returns a list of two elements. The first element contains the identifier of the list from which the data was retrieved. The second element contains the extracted data. When retrieving data, it is removed from the collection.

If you perform a pop_oldest on the collection, the data will always be returned in order of the time corresponding inserted data.

Method returns an empty list if the collection does not contain any data.

The following examples illustrate uses of the pop_oldest method:

    while ( my ( $list_id, $data ) = $coll->pop_oldest ) {
        say "List '$list_id' had '$data'";
    }

`collection_info`

The method is designed to obtain information on the status of the collection and to see how much space an existing collection uses.

Returns a reference to a hash with the following elements:

length - Size in bytes of all the data stored in all the collection lists.
lists - Number of lists of data stored in a collection.
items - Number of data items stored in the collection.
oldest_time - Time corresponding to the oldest data in the collection. undef if the collection does not contain data.

The following examples illustrate uses of the collection_info method:

    my $info = $coll->collection_info;
    say 'An existing collection uses ', $info->{length}, ' byte of data, ',
        'in ', $info->{items}, ' items are placed in ',
        $info->{lists}, ' lists';

`info( $list_id )`

The method is designed to obtain information on the status of the data list and to see how many items it contains.

$list_id must be a non-empty string.

Returns a reference to a hash with the following elements:

items - Number of data items stored in the data list.
oldest_time - Time corresponding to the oldest data in the list. undef if the data list does not exists.
last_removed_time - time corresponding to the latest data deleted from the list. undef if the data list does not exists.

`exists( $list_id )`

The method is designed to test whether there is a list in the collection with ID $list_id. Returns true if the list exists and false otherwise.

The following examples illustrate uses of the exists method:

    say "The collection has '$list_id' list" if $coll->exists( 'Some_id' );

`lists( $pattern )`

Returns a list of identifiers stored in a collection. Returns all list IDs matching $pattern if $pattern is not empty. $patten must be a non-empty string.

Supported glob-style patterns:

h?llo matches hello, hallo and hxllo
h*llo matches hllo and heeeello
h[ae]llo matches hello and hallo, but not hillo

Use '\' to escape special characters if you want to match them verbatim.

The following examples illustrate uses of the lists method:

    say "The collection has '$_' list" foreach $coll->lists;

Warning: consider lists as a command that should only be used in production environments with extreme care. It may ruin performance when it is executed against large databases. This command is intended for debugging and special operations. Don't use lists in your regular application code.

Methods lists can cause an exception (confess) if the collection contains a very large number of lists ('Error while reading from Redis server').

`drop_collection`

Use the drop_collection method to remove the entire collection. Method removes all the structures on the Redis server associated with the collection. After using drop_collection you must explicitly recreate the collection.

Before use, make sure that the collection is not being used by other customers.

The following examples illustrate uses of the drop_collection method:

    $coll->drop_collection;

Warning: consider drop_collection as a command that should only be used in production environments with extreme care. It may ruin performance when it is executed against large databases. This command is intended for debugging and special operations. Don't use drop_collection in your regular application code.

Methods drop_collection can cause an exception (confess) if the collection contains a very large number of lists ('Error while reading from Redis server').

`drop( $list_id )`

Use the drop method to remove the entire specified list. Method removes all the structures on the Redis server associated with the specified list.

$list_id must be a non-empty string.

Method returns true if the list is removed, or false otherwise.

`ping`

This command is used to test if a connection is still alive.

Returns 1 if a connection is still alive or 0 otherwise.

The following examples illustrate uses of the ping method:

    $is_alive = $coll->ping;

`quit`

Ask the Redis server to close the connection.

The following examples illustrate uses of the quit method:

    $coll->quit;

DIAGNOSTICS

The method for the possible error to analyse: "last_errorcode".

A Redis error will cause the program to halt (confess). In addition to errors in the Redis module, detected errors are "EMISMATCHARG", "EDATATOOLARGE", "EMAXMEMORYPOLICY", "ECOLLDELETED", "EDATAIDEXISTS", "EOLDERTHANALLOWED".

All recognizable errors in Redis::CappedCollection lead to the installation of the corresponding value in the "last_errorcode" and cause an exception (confess). Unidentified errors cause an exception ("last_errorcode" remains equal to 0). The initial value of $@ is preserved.

The user has the choice:

Use the module methods and independently analyze the situation without the use of "last_errorcode".
Piece of code wrapped in eval {...}; and analyze "last_errorcode" (look at the "An Example" section).

An Example

The example shows a possible treatment for possible errors.

    use 5.010;
    use strict;
    use warnings;

    #-- Common ---------------------------------------------------------
    use Redis::CappedCollection qw(
        DEFAULT_SERVER
        DEFAULT_PORT

        ENOERROR
        EMISMATCHARG
        EDATATOOLARGE
        ENETWORK
        EMAXMEMORYLIMIT
        EMAXMEMORYPOLICY
        ECOLLDELETED
        EREDIS
    );

    # A possible treatment for possible errors
    sub exception {
        my $coll    = shift;
        my $err     = shift;

        die $err unless $coll;
        if ( $coll->last_errorcode == ENOERROR ) {
            # For example, to ignore
            return unless $err;
        } elsif ( $coll->last_errorcode == EMISMATCHARG ) {
            # Necessary to correct the code
        } elsif ( $coll->last_errorcode == EDATATOOLARGE ) {
            # You must use the control data length
        } elsif ( $coll->last_errorcode == ENETWORK ) {
            # For example, sleep
            #sleep 60;
            # and return code to repeat the operation
            #return 'to repeat';
        } elsif ( $coll->last_errorcode == EMAXMEMORYLIMIT ) {
            # For example, return code to restart the server
            #return 'to restart the redis server';
        } elsif ( $coll->last_errorcode == EMAXMEMORYPOLICY ) {
            # For example, return code to reinsert the data
            #return "to reinsert look at $err";
        } elsif ( $coll->last_errorcode == ECOLLDELETED ) {
            # For example, return code to ignore
            #return "to ignore $err";
        } elsif ( $coll->last_errorcode == EREDIS ) {
            # Independently analyze the $err
        } elsif ( $coll->last_errorcode == EDATAIDEXISTS ) {
            # For example, return code to reinsert the data
            #return "to reinsert with new data ID";
        } elsif ( $coll->last_errorcode == EOLDERTHANALLOWED ) {
            # Independently analyze the situation
        } else {
            # Unknown error code
        }
        die $err if $err;
    }

    my ( $list_id, $coll, @data );

    eval {
        $coll = Redis::CappedCollection->new(
            redis   => DEFAULT_SERVER.':'.DEFAULT_PORT,
            name    => 'Some name',
            size    => 100_000,
        );
    };
    exception( $coll, $@ ) if $@;
    say "'", $coll->name, "' collection created.";
    say 'Restrictions: ', $coll->size, ' size;

    #-- Producer -------------------------------------------------------
    #-- New data

    eval {
        $list_id = $coll->insert(
            'Some data stuff',
            'Some_id',      # If not specified, it creates
                            # a new items list named as UUID
        );
        say "Added data in a list with '", $list_id, "' id" );

        # Change the "zero" element of the list with the ID $list_id
        if ( $coll->update( $list_id, 0, 'Some new data stuff' ) ) {
            say 'Data updated successfully';
        } else {
            say 'The data is not updated';
        }
    };
    exception( $coll, $@ ) if $@;

    #-- Consumer -------------------------------------------------------
    #-- Fetching the data

    eval {
        @data = $coll->receive( $list_id );
        say "List '$list_id' has '$_'" foreach @data;
        # or to obtain the data in the order they are received
        while ( my ( $list_id, $data ) = $coll->pop_oldest ) {
            say "List '$list_id' had '$data'";
        }
    };
    exception( $coll, $@ ) if $@;

    #-- Utility --------------------------------------------------------
    #-- Getting statistics

    my ( $length, $lists, $items );
    eval {
        my $info = $coll->collection_info;
        say 'An existing collection uses ', $info->{length}, ' byte of data, ',
            'in ', $info->{items}, ' items are placed in ',
            $info->{lists}, ' lists';

        say "The collection has '$list_id' list"
            if $coll->exists( 'Some_id' );
    };
    exception( $coll, $@ ) if $@;

    #-- Closes and cleans up -------------------------------------------

    eval {
        $coll->quit;

        # Before use, make sure that the collection
        # is not being used by other customers
        #$coll->drop_collection;
    };
    exception( $coll, $@ ) if $@;

CappedCollection data structure

Using the currently selected database (default = 0).

While working on the Redis server creates and uses these data structures:

    #-- To store the collection status:
    # HASH    Namespace:status:Collection_id
    # For example:
    $ redis-cli
    redis 127.0.0.1:6379> KEYS Capped:status:*
    1) "Capped:status:89116152-C5BD-11E1-931B-0A690A986783"
    #      |      |                       |
    #  Namespace  |                       |
    #  Fixed symbol of a properties hash  |
    #                         Capped Collection id (UUID)
    ...
    redis 127.0.0.1:6379> HGETALL Capped:status:89116152-C5BD-11E1-931B-0A690A986783
    1) "size"                   # hash key
    2) "0"                      # the key value
    3) "length"                 # hash key
    4) "15"                     # the key value
    5) "lists"                  # hash key
    6) "1"                      # the key value
    7) "items"                  # hash key
    8) "1"                      # the key value
    9) "older_allowed"          # hash key
    10) "0"                     # the key value
    11) "big_data_threshold"    # hash key
    12) "0"                     # the key value

    #-- To store the collection queue:
    # ZSET    Namespace:queue:Collection_id
    # For example:
    redis 127.0.0.1:6379> KEYS Capped:queue:*
    1) "Capped:queue:89116152-C5BD-11E1-931B-0A690A986783"
    #      |     |                       |
    #  Namespace |                       |
    #  Fixed symbol of a queue           |
    #                        Capped Collection id (UUID)
    ...
    redis 127.0.0.1:6379> ZRANGE Capped:queue:89116152-C5BD-11E1-931B-0A690A986783 0 -1 WITHSCORES
    1) "478B9C84-C5B8-11E1-A2C5-D35E0A986783"
    2) "1348252575.6651001"     |
    #           |               |
    #  Score: oldest data_time  |
    #                   Member: Data List id (UUID)
    ...

    #-- To store the CappedCollection data:
    # HASH    Namespace:I:Collection_id:DataList_id
    # HASH    Namespace:D:Collection_id:DataList_id
    # ZSET    Namespace:T:Collection_id:DataList_id
    # For example:
    redis 127.0.0.1:6379> KEYS Capped:?:*
    1) "Capped:I:89116152-C5BD-11E1-931B-0A690A986783:478B9C84-C5B8-11E1-A2C5-D35E0A986783"
    # If big_data_threshold = 0 or big_data_threshold > 0 and items on the list more than big_data_threshold
    2) "Capped:D:89116152-C5BD-11E1-931B-0A690A986783:478B9C84-C5B8-11E1-A2C5-D35E0A986783"
    3) "Capped:T:89116152-C5BD-11E1-931B-0A690A986783:478B9C84-C5B8-11E1-A2C5-D35E0A986783"
    #     |    |                     |                       |
    # Namespace|                     |                       |
    # Fixed symbol of a list of data |                       |
    #                    Capped Collection id (UUID)         |
    #                                                Data list id (UUID)
    ...
    redis 127.0.0.1:6379> HGETALL Capped:I:89116152-C5BD-11E1-931B-0A690A986783:478B9C84-C5B8-11E1-A2C5-D35E0A986783
    1) "n"                      # hash key (next_data_id)
    2) "1"                      # the key value
    3) "l"                      # hash key (last_removed_time)
    4) "0"                      # the key value
    5) "t"                      # hash key (oldest_time)
    6) "1348252575.5906"        # the key value
    7) "i"                      # hash key (oldest_data_id)
    8) "0"                      # the key value
    # If big_data_threshold > 0 and items on the list no more than big_data_threshold
    9) "0"                      # hash key
    10) "3"                     # the key value (items in the list)
    11) "1.i"                   # hash key
    12) "0"                     # the key value (Data id)
    13) "1.d"                   # hash key
    14) "Sume stuff"            # the key value (Data)
    15) "1.t"                   # hash key
    16) "1348252575.5906"       # the key value (data_time)
    ...
    # If big_data_threshold = 0 or big_data_threshold > 0 and items on the list more than big_data_threshold
    redis 127.0.0.1:6379> HGETALL Capped:D:89116152-C5BD-11E1-931B-0A690A986783:478B9C84-C5B8-11E1-A2C5-D35E0A986783
    1) "0"                      # hash key: Data id
    2) "Some stuff"             # the key value: Data
    ...
    # If big_data_threshold = 0 or big_data_threshold > 0 and items on the list more than big_data_threshold
    redis 127.0.0.1:6379> ZRANGE Capped:T:89116152-C5BD-11E1-931B-0A690A986783:478B9C84-C5B8-11E1-A2C5-D35E0A986783 0 -1 WITHSCORES
    1) "0" ---------------+
    2) "1348252575.5906"  |
    #           |         |
    #   Score: data_time  |
    #              Member: Data id
    ...

DEPENDENCIES

In order to install and use this package you will need Perl version 5.010 or better. The Redis::CappedCollection module depends on other packages that are distributed separately from Perl. We recommend that you have the following packages installed before you install Redis::CappedCollection :

    Data::UUID
    Digest::SHA1
    Mouse
    Params::Util
    Redis

The Redis::CappedCollection module has the following optional dependencies:

    Net::EmptyPort
    Test::Distribution
    Test::Exception
    Test::Kwalitee
    Test::Perl::Critic
    Test::Pod
    Test::Pod::Coverage
    Test::RedisServer

If the optional modules are missing, some "prereq" tests are skipped.

The installation of the missing dependencies can either be accomplished through your OS package manager or through CPAN (or downloading the source for all dependencies and compiling them manually).

BUGS AND LIMITATIONS

Need a Redis server version 2.6 or higher as module uses Redis Lua scripting.

The use of maxmemory-police all* in the redis.conf file could lead to a serious (but hard to detect) problem as Redis server may delete the collection element. Therefore the Redis::CappedCollection does not work with mode maxmemory-police all* in the redis.conf.

It may not be possible to use this module with the cluster of Redis servers because full name of some Redis keys may not be known at the time of the call the Redis Lua script ('EVAL' or 'EVALSHA' command). So the Redis server may not be able to correctly forward the request to the appropriate node in the cluster.

We strongly recommend using the option maxmemory in the redis.conf file if the data set may be large.

WARNING: According to initServer() function in redis.c :

    /* 32 bit instances are limited to 4GB of address space, so if there is
     * no explicit limit in the user provided configuration we set a limit
     * at 3 GB using maxmemory with 'noeviction' policy'. This avoids
     * useless crashes of the Redis instance for out of memory. */

The Redis::CappedCollection module was written, tested, and found working on recent Linux distributions.

There are no known bugs in this package.

Please report problems to the "AUTHOR".

Patches are welcome.

SOURCE CODE

Redis::CappedCollection is hosted on GitHub: https://github.com/TrackingSoft/Redis-CappedCollection

AUTHOR

Sergey Gladkov, <sgladkov@trackingsoft.com>

CONTRIBUTORS

Alexander Solovey

Jeremy Jordan

Vlad Marchenko

COPYRIGHT AND LICENSE

This package is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic at http://dev.perl.org/licenses/artistic.html.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

To install Redis::CappedCollection, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Redis::CappedCollection

CPAN shell

perl -MCPAN -e shell
install Redis::CappedCollection

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

ABSTRACT

DESCRIPTION

EXPORT

DEFAULT_SERVER

DEFAULT_PORT

NAMESPACE

GLOBAL VARIABLES

CONSTRUCTOR

new( redis => $server, ... )

METHODS

name

size

advance_cleanup_bytes

advance_cleanup_num

max_datasize

older_allowed

big_data_threshold

last_errorcode

insert( $data, $list_id, $data_id, $data_time )

update( $list_id, $data_id, $data )

receive( $list_id, $data_id )

pop_oldest

collection_info

info( $list_id )

exists( $list_id )

lists( $pattern )

drop_collection

drop( $list_id )

ping

quit