cachedb_local Module
     __________________________________________________________

   Table of Contents

   1. Admin Guide

        1.1. Overview
        1.2. Dependencies

              1.2.1. OpenSIPS Modules
              1.2.2. External Libraries or Applications

        1.3. Exported Parameters

              1.3.1. cachedb_url (string)
              1.3.2. cache_collections (string)
              1.3.3. cache_clean_period (int)

        1.4. Exported Functions

              1.4.1. cache_remove_chunk([collection,] glob)

        1.5. Exported MI Functions

              1.5.1. cache_remove_chunk

   2. Frequently Asked Questions
   3. Contributors

        3.1. By Commit Statistics
        3.2. By Commit Activity

   4. Documentation

        4.1. Contributors

   List of Tables

   3.1. Top contributors by DevScore^(1), authored commits^(2) and
          lines added/removed^(3)

   3.2. Most recently active contributors^(1) to this module

   List of Examples

   1.1. Set cachedb_url parameter
   1.2. Set cache_collections parameter
   1.3. Set cache_clean_period parameter
   1.4. cache_remove_chunk usage

Chapter 1. Admin Guide

1.1. Overview

   This module is an implementation of a local cache system
   designed as a hash table. It uses the Key-Value interface
   exported by OpenSIPS core. Starting with version 2.3, the
   module can have multiple hash tables, called collections. Each
   url for cachedb_local module points to one collection. One
   collection can be shared between multiple urls.

1.2. Dependencies

1.2.1. OpenSIPS Modules

   None.

1.2.2. External Libraries or Applications

   The following libraries or applications must be installed
   before running OpenSIPS with this module loaded:
     * none

1.3. Exported Parameters

1.3.1. cachedb_url (string)

   URL parameter used to define cachedb_local collections. One
   collection can belong to multiple URLs, but one URL can have
   only one collection. Redefining an URL with the same schema and
   group name will result in overwriting that URL. Each collection
   used in URL definition must be defined using cachedb_collection
   parameter. The collection shall be defined as a normal
   database, at the end of the URL as in the examples. In the
   script the collection shall be identified using the schema and,
   if exists, the group name.

   “If no URL defined, the url with no group name and collection
   "default" will be used.”.

   Example 1.1. Set cachedb_url parameter
...
### for this example, if no collection is defined, the default collectio
n named
### "default" shall be used
modparam("cachedb_local", "cachedb_url", "local://")
### this URL will use the collection named collection1; it will overwrit
e the
### previous url definition which was using the "default" collection
modparam("cachedb_local", "cachedb_url", "local:///collection1")
### this URL will use collection2; it will be referenced from the script
### with "local:group2"
modparam("cachedb_local", "cachedb_url", "local:group2:///collection2")

## how to use the URLs from the script
## as defined above, this call will use collection1
cache_store("local", ...)
## as defined above, this call will use collection2
cache_store("local:group2", ...)
...

1.3.2. cache_collections (string)

   Using this parameter collections(hash tables) and their sizes
   can be defined. Each collection definition must be separated
   one from another using ';'. Default size for a hash is 512. The
   size must be separated from the name of the collection using
   '='. Every collection that is defined in this parameter SHOULD
   be used in at least one URL, else you'll receive a WARNING.

   “If no collection is defined, the collection with name
   "default" will be created.”.

   Example 1.2. Set cache_collections parameter
...
## creating collection1 with default size (512) and collection2 with cus
tom size
## 2^5 (32); we also changed the size of the default collection, which w
ould have been
## created anyway from 2^9 - 512 (default value) to 2^4 - 16
modparam("cachedb_local", "cache_collections", "collection1; collection2
=5; default=4")
...

1.3.3. cache_clean_period (int)

   The time interval in seconds at which to go through all the
   records and delete the expired ones.

   Default value is “600 (10 minutes)”.

   Example 1.3. Set cache_clean_period parameter
...
modparam("cachedb_local", "cache_clean_period", 1200)
...

1.4. Exported Functions

1.4.1.  cache_remove_chunk([collection,] glob)

   Remove all keys from local cache that match the glob pattern
   corresponding to a certain collection or the 'default'
   collection if none defined. Keep in mind that collection name
   is different than group name, which identifies the engine in
   cachedb operations.

   This function can be used from all routes

   Example 1.4. cache_remove_chunk usage
        ...
        cache_remove_chunk("myinfo_*");
        cache_remove_chunk("collection1", "myinfo_*");
        ...

1.5. Exported MI Functions

1.5.1.  cache_remove_chunk

   Removes all local cache entries that match the provided glob
   param.

   Parameters :
     * collection(optional) - collection from which the keys shall
       be removed; if no collection set, the default collection
       will be used;
     * glob - keys that match glob will be removed

   MI FIFO Command Format:
                :cache_remove_chunk:_reply_fifo_file_
                collection*
                keyprefix*
                _empty_line_

Chapter 2. Frequently Asked Questions

   2.1.

       What happened with old cache_table_size parameter?

       The parameter was removed because it was redundant. Since the
       addition of collections, the old hash now belongs to the
       default collection. This collection is created every time and
       it has a default size of 512. The size can be changed by
       setting the default collection size using cache_collections
       paramter.

Chapter 3. Contributors

3.1. By Commit Statistics

   Table 3.1. Top contributors by DevScore^(1), authored
   commits^(2) and lines added/removed^(3)
     Name DevScore Commits Lines ++ Lines --
   1. Vlad Paiu (@vladpaiu) 33 10 1155 693
   2. Bogdan-Andrei Iancu (@bogdan-iancu) 15 13 41 47
   3. Anca Vamanu 12 5 739 54
   4. Liviu Chircu (@liviuchircu) 11 8 23 61
   5. Andrei Dragus 10 4 182 181
   6. Ionut Ionita (@ionutrazvanionita) 9 3 513 55
   7. Razvan Crainea (@razvancrainea) 4 2 5 5
   8. Vlad Patrascu (@rvlad-patrascu) 4 2 3 2
   9. Dusan Klinec 3 1 4 4
   10. Ryan Bullock (@rrb3942) 3 1 2 4

   All remaining contributors: Julián Moreno Patiño.

   (1) DevScore = author_commits + author_lines_added /
   (project_lines_added / project_commits) + author_lines_deleted
   / (project_lines_deleted / project_commits)

   (2) including any documentation-related commits, excluding
   merge commits. Regarding imported patches/code, we do our best
   to count the work on behalf of the proper owner, as per the
   "fix_authors" and "mod_renames" arrays in
   opensips/doc/build-contrib.sh. If you identify any
   patches/commits which do not get properly attributed to you,
   please submit a pull request which extends "fix_authors" and/or
   "mod_renames".

   (3) ignoring whitespace edits, renamed files and auto-generated
   files

3.2. By Commit Activity

   Table 3.2. Most recently active contributors^(1) to this module
                      Name                   Commit Activity
   1.  Bogdan-Andrei Iancu (@bogdan-iancu) Jan 2009 - Aug 2018
   2.  Liviu Chircu (@liviuchircu)         Mar 2014 - Jun 2018
   3.  Vlad Patrascu (@rvlad-patrascu)     Jan 2017 - May 2017
   4.  Razvan Crainea (@razvancrainea)     Aug 2015 - Apr 2017
   5.  Ionut Ionita (@ionutrazvanionita)   Jan 2017 - Jan 2017
   6.  Julián Moreno Patiño                Feb 2016 - Feb 2016
   7.  Dusan Klinec                        Dec 2015 - Dec 2015
   8.  Ryan Bullock (@rrb3942)             Jan 2014 - Jan 2014
   9.  Vlad Paiu (@vladpaiu)               Oct 2011 - Nov 2013
   10. Andrei Dragus                       Jul 2009 - Jul 2009

   All remaining contributors: Anca Vamanu.

   (1) including any documentation-related commits, excluding
   merge commits

Chapter 4. Documentation

4.1. Contributors

   Last edited by: Bogdan-Andrei Iancu (@bogdan-iancu), Liviu
   Chircu (@liviuchircu), Ionut Ionita (@ionutrazvanionita), Vlad
   Paiu (@vladpaiu).

   doc copyrights:

   Copyright © 2009 Anca-Maria Vamanu
