[sr-dev] git:master: htable: documentation for iterator functions
Elena-Ramona Modroiu
ramona at rosdev.ro
Tue Sep 9 15:26:01 CEST 2014
Module: sip-router
Branch: master
Commit: 4776b44ea9c5546c37fea9f3886148a17c735fe5
URL: http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=4776b44ea9c5546c37fea9f3886148a17c735fe5
Author: Elena-Ramona Modroiu <ramona at asipto.com>
Committer: Elena-Ramona Modroiu <ramona at asipto.com>
Date: Tue Sep 9 15:24:47 2014 +0200
htable: documentation for iterator functions
---
modules/htable/README | 73 ++++++++++++++++++++++++++++
modules/htable/doc/htable_admin.xml | 91 +++++++++++++++++++++++++++++++++++
2 files changed, 164 insertions(+), 0 deletions(-)
diff --git a/modules/htable/README b/modules/htable/README
index 7a7c3cf..5a27593 100644
--- a/modules/htable/README
+++ b/modules/htable/README
@@ -61,6 +61,9 @@ Ovidiu Sas
4.4. sht_reset(htable)
4.5. sht_lock(htable=>key)
4.6. sht_unlock(htable=>key)
+ 4.7. sht_iterator_start(iname, hname)
+ 4.8. sht_iterator_end(iname)
+ 4.9. sht_iterator_next(iname)
5. Exported pseudo-variables
6. MI Commands
@@ -109,6 +112,9 @@ Ovidiu Sas
1.20. sht_reset usage
1.21. sht_lock usage
1.22. sht_unlock usage
+ 1.23. sht_iterator_start usage
+ 1.24. sht_iterator_end usage
+ 1.25. sht_iterator_next usage
Chapter 1. Admin Guide
@@ -145,6 +151,9 @@ Chapter 1. Admin Guide
4.4. sht_reset(htable)
4.5. sht_lock(htable=>key)
4.6. sht_unlock(htable=>key)
+ 4.7. sht_iterator_start(iname, hname)
+ 4.8. sht_iterator_end(iname)
+ 4.9. sht_iterator_next(iname)
5. Exported pseudo-variables
6. MI Commands
@@ -606,6 +615,9 @@ modparam("htable", "enable_dmq", 1)
4.4. sht_reset(htable)
4.5. sht_lock(htable=>key)
4.6. sht_unlock(htable=>key)
+ 4.7. sht_iterator_start(iname, hname)
+ 4.8. sht_iterator_end(iname)
+ 4.9. sht_iterator_next(iname)
4.1. sht_print()
@@ -682,6 +694,67 @@ $sht(ha=>test) = $sht(ha=>test) + 10;
sht_unlock("ha=>test");
...
+4.7. sht_iterator_start(iname, hname)
+
+ Start an iterator for hash table named by the value of parameter hname.
+ The parameter iname is used to identify the iterator. There can be up
+ to 4 iterators at the same time, with different name.
+
+ Both parameters can be dynamic strings with variables.
+
+ IMPORTANT: the slot of the hash table is left locked when retrieving in
+ item. Therefore be sure you do not update the content of the hash table
+ in between sht_iterator_start() and sht_iterator_end(), because it may
+ end up in dead lock.
+
+ This function can be used from ANY_ROUTE.
+
+ Example 1.23. sht_iterator_start usage
+...
+sht_iterator_start("i1", "h1");
+...
+
+4.8. sht_iterator_end(iname)
+
+ Close the iterator identified by iname parameter and release the hash
+ table slot aquired by the iterator. The iname value must be the same
+ used for sht_iterator_start().
+
+ The parameter can be dynamic string with variables.
+
+ This function can be used from ANY_ROUTE.
+
+ Example 1.24. sht_iterator_end usage
+...
+sht_iterator_end("i1");
+...
+
+4.9. sht_iterator_next(iname)
+
+ Move the iterator to the next item in hash table. It must be called
+ also after sht_iterator_start() to get the first item in the hash
+ table. Items are returned as they are found in the hash table slot,
+ starting with the first slot.
+
+ The return code is false when there is no (more) item in the hash
+ table.
+
+ The item name and value are accessible via variables: $shtitkey(iname)
+ and $shtitval(iname).
+
+ The parameter can be dynamic string with variables.
+
+ This function can be used from ANY_ROUTE.
+
+ Example 1.25. sht_iterator_next usage
+...
+ sht_iterator_start("i1", "h1");
+ while(sht_iterator_next("i1")) {
+ xlog("h1[$shtitkey(i1)] is: $shtitval(i1)\n");
+ }
+ sht_iterator_end("i1");
+...
+
5. Exported pseudo-variables
* $sht(htable=>key)
diff --git a/modules/htable/doc/htable_admin.xml b/modules/htable/doc/htable_admin.xml
index 6427a28..bfba088 100644
--- a/modules/htable/doc/htable_admin.xml
+++ b/modules/htable/doc/htable_admin.xml
@@ -770,6 +770,97 @@ sht_unlock("ha=>test");
</programlisting>
</example>
</section>
+ <section id="htable.f.sht_iterator_start">
+ <title>
+ <function moreinfo="none">sht_iterator_start(iname, hname)</function>
+ </title>
+ <para>
+ Start an iterator for hash table named by the value of parameter
+ hname. The parameter iname is used to identify the iterator. There
+ can be up to 4 iterators at the same time, with different name.
+ </para>
+ <para>
+ Both parameters can be dynamic strings with variables.
+ </para>
+ <para>
+ IMPORTANT: the slot of the hash table is left locked when
+ retrieving in item. Therefore be sure you do not update the
+ content of the hash table in between sht_iterator_start()
+ and sht_iterator_end(), because it may end up in dead lock.
+ </para>
+ <para>
+ This function can be used from ANY_ROUTE.
+ </para>
+ <example>
+ <title><function>sht_iterator_start</function> usage</title>
+ <programlisting format="linespecific">
+...
+sht_iterator_start("i1", "h1");
+...
+</programlisting>
+ </example>
+ </section>
+ <section id="htable.f.sht_iterator_end">
+ <title>
+ <function moreinfo="none">sht_iterator_end(iname)</function>
+ </title>
+ <para>
+ Close the iterator identified by iname parameter and release
+ the hash table slot aquired by the iterator. The iname value
+ must be the same used for sht_iterator_start().
+ </para>
+ <para>
+ The parameter can be dynamic string with variables.
+ </para>
+ <para>
+ This function can be used from ANY_ROUTE.
+ </para>
+ <example>
+ <title><function>sht_iterator_end</function> usage</title>
+ <programlisting format="linespecific">
+...
+sht_iterator_end("i1");
+...
+</programlisting>
+ </example>
+ </section>
+ <section id="htable.f.sht_iterator_next">
+ <title>
+ <function moreinfo="none">sht_iterator_next(iname)</function>
+ </title>
+ <para>
+ Move the iterator to the next item in hash table. It must
+ be called also after sht_iterator_start() to get the first
+ item in the hash table. Items are returned as they are found
+ in the hash table slot, starting with the first slot.
+ </para>
+ <para>
+ The return code is false when there is no (more) item in the
+ hash table.
+ </para>
+ <para>
+ The item name and value are accessible via variables:
+ $shtitkey(iname) and $shtitval(iname).
+ </para>
+ <para>
+ The parameter can be dynamic string with variables.
+ </para>
+ <para>
+ This function can be used from ANY_ROUTE.
+ </para>
+ <example>
+ <title><function>sht_iterator_next</function> usage</title>
+ <programlisting format="linespecific">
+...
+ sht_iterator_start("i1", "h1");
+ while(sht_iterator_next("i1")) {
+ xlog("h1[$shtitkey(i1)] is: $shtitval(i1)\n");
+ }
+ sht_iterator_end("i1");
+...
+</programlisting>
+ </example>
+ </section>
</section>
<section>
<title>Exported pseudo-variables</title>
More information about the sr-dev
mailing list