[sr-dev] git:master: htable: documentation for iterator functions

Module: sip-router Branch: master Commit: 4776b44ea9c5546c37fea9f3886148a17c735fe5 URL: http://git.sip-router.org/cgi-bin/gitweb.cgi/sip-router/?a=commit;h=4776b44… Author: Elena-Ramona Modroiu &lt;ramona(a)asipto.com&gt; Committer: Elena-Ramona Modroiu &lt;ramona(a)asipto.com&gt; 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>