cachedb_local_admin.xml

<!-- Module User's Guide -->

<chapter>

	<title>&adminguide;</title>

	<section>
	<title>Overview</title>
	<para>
		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.
	</para>
	<para>
	</para>
	</section>

	<section>
	<title>Dependencies</title>
	<section>
		<title>&osips; Modules</title>
		<para>
		None.
		</para>
	</section>

	<section>
		<title>External Libraries or Applications</title>
		<para>
		The following libraries or applications must be installed before running
		&osips; with this module loaded:
		</para>
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>none</emphasis>
			</para>
			</listitem>
			</itemizedlist>
	</section>
	</section>

	<section>
		<title>Exported Parameters</title>

		<section>
		<title><varname>cachedb_url</varname> (string)</title>
		<para>
			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
		<emphasis>cachedb_collection</emphasis> 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.
		</para>
		<para>
			<emphasis><quote>If no URL defined, the url with no group name and collection "default"
					will be used.</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>cachedb_url</varname> parameter</title>
		<programlisting format="linespecific">
...
### for this example, if no collection is defined, the default collection named
### "default" shall be used
modparam("cachedb_local", "cachedb_url", "local://")
### this URL will use the collection named collection1; it will overwrite 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", ...)
...
	</programlisting>
		</example>
	</section>

		<section>
		<title><varname>cache_collections</varname> (string)</title>
		<para>
			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 <emphasis>SHOULD</emphasis> be
			used in at least one URL, else you'll receive a WARNING.
		</para>
		<para>
			<emphasis><quote>If no collection is defined, the collection with name "default" will be
				created.</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>cache_collections</varname> parameter</title>
		<programlisting format="linespecific">
...
## creating collection1 with default size (512) and collection2 with custom size
## 2^5 (32); we also changed the size of the default collection, which would have been
## created anyway from 2^9 - 512 (default value) to 2^4 - 16
modparam("cachedb_local", "cache_collections", "collection1; collection2=5; default=4")
...
	</programlisting>
		</example>
	</section>

	<section>
		<title><varname>cache_clean_period</varname> (int)</title>
		<para>
			The time interval in seconds at which to go through all the
			records and delete the expired ones.
		</para>
		<para>
		<emphasis>Default value is <quote>600 (10 minutes)</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>cache_clean_period</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("cachedb_local", "cache_clean_period", 1200)
...
	</programlisting>
		</example>
	</section>
	</section>

	<section>
		<title>Exported Functions</title>

		<section>
			<title>
			<function moreinfo="none">cache_remove_chunk([collection,] glob)</function>
			</title>
			<para>
				Remove all keys from local cache that match the <emphasis>glob</emphasis> pattern
			corresponding to a certain <emphasis>collection</emphasis> 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.
			</para>
			<para>
			This function can be used from all routes
			</para>
			<example>
			<title><function>cache_remove_chunk</function> usage</title>
			<programlisting format="linespecific">
	...
	cache_remove_chunk("myinfo_*");
	cache_remove_chunk("collection1", "myinfo_*");
	...
	</programlisting>
			</example>
		</section>

	</section>

	<section>
	<title>Exported MI Functions</title>

		<section>
		<title><varname>cache_remove_chunk</varname></title>
		<para>
		Removes all local cache entries that match the provided glob param.
		</para>

		<para>Parameters :</para>
		<itemizedlist>
			<listitem><para>
				<emphasis>collection(optional)</emphasis> - collection from which the keys shall
					be removed; if no collection set, the default collection will be used;
			</para></listitem>
			<listitem><para>
				<emphasis>glob</emphasis> - keys that match glob will be removed
			</para></listitem>
		</itemizedlist>

		<para>
		MI FIFO Command Format:
		</para>
		<programlisting  format="linespecific">
		:cache_remove_chunk:_reply_fifo_file_
		collection*
		keyprefix*
		_empty_line_
		</programlisting>
		</section>
	</section>

</chapter>