commit dd174c64d5f91debf561a0266b18989696d3eaf8
parent 6bae0b3d69c7968586afc73827b5844c6a23873f
Author: Laurent Bercot <ska-skaware@skarnet.org>
Date: Fri, 16 Mar 2018 13:25:03 +0000
Add genqdyn doc
Diffstat:
5 files changed, 139 insertions(+), 4 deletions(-)
diff --git a/NEWS b/NEWS
@@ -5,6 +5,7 @@ In 2.6.4.0
- Bugfixes.
- New functions: execvep_loose(), byte_zzero(), openb_read()
+ - New function family: skalibs/genqdyn.h
In 2.6.3.1
diff --git a/doc/libdatastruct/genqdyn.html b/doc/libdatastruct/genqdyn.html
@@ -0,0 +1,127 @@
+<html>
+ <head>
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+ <meta http-equiv="Content-Language" content="en" />
+ <title>skalibs: the genqdyn library interface</title>
+ <meta name="Description" content="skalibs: the genqdyn library interface" />
+ <meta name="Keywords" content="skalibs c unix genqdyn library queue libdatastruct" />
+ <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
+ </head>
+<body>
+
+<p>
+<a href="index.html">libdatastruct</a><br />
+<a href="../libskarnet.html">libskarnet</a><br />
+<a href="../index.html">skalibs</a><br />
+<a href="//skarnet.org/software/">Software</a><br />
+<a href="//skarnet.org/">skarnet.org</a>
+</p>
+
+<h1> The <tt>genqdyn</tt> library interface </h1>
+
+<p>
+ The following functions are declared in the <tt>skalibs/genqdyn.h</tt> header,
+and implemented in the <tt>libskarnet.a</tt> or <tt>libskarnet.so</tt> library.
+</p>
+
+<h2> General information </h2>
+
+<p>
+ <tt>genqdyn</tt> is a set of functions implementing simple queues on
+generic objects. The <em>dyn</em> prefix means the queues are dynamically
+allocated (and live in heap memory): it is possible to enqueue an arbitrary
+number of objects, up to the available memory.
+</p>
+
+<h2> Data structures </h2>
+
+<p>
+ A <tt>genqdyn</tt> structure holds the information necessary to implement
+a queue. It can be declared anywhere (including in the stack). All genqdyn
+functions take a pointer to this structure as an argument.
+</p>
+
+<h2> Macros </h2>
+
+<p>
+<code> genqdyn GENQDYN_INIT(type, num, den) </code> <br />
+Returns an anonymous genqdyn structure suitable for holding objects of
+type <em>type</em>. The <em>num</em> and <em>den</em> arguments are integers,
+used to tune the amount of memory needed / management overhead balance.
+<em>num</em>/<em>den</em> must be a fractional value between 0 and 1.
+The closer to 0, the longer genqdyn will wait before performing a
+cleanup (and the more memory it can consume). At 0, genqdyn can only
+recycle memory when the queue becomes totally empty. The closer to 1,
+the more genqdyn optimizes its memory usage (and the more often it
+performs maintenance on its queue). At 1, it performs maintenance
+every time an object is popped.
+ Anything between 1/4 and 3/4 is a reasonable value for <em>num</em>/<em>den</em>.
+</p>
+
+<p>
+<code> size_t genqdyn_n (genqdyn *g) </code> <br />
+Returns the number of elements in the genqdyn <em>*g</em>, which must
+have been initialized.
+</p>
+
+<p>
+<code> void *genqdyn_peek (genqdyn *g) </code> <br />
+Peeks at the next object in the queue, i.e. the object that has
+been pushed the earliest and that hasn't been popped yet.
+You can use the <tt>GENQDYN_PEEK(type, g)</tt> macro to get a
+<tt>type *</tt> pointer instead of a <tt>void *</tt> one.
+</p>
+
+
+
+<h2> Functions </h2>
+
+<p>
+<code> void genqdyn_init (genqdyn *g, size_t esize, unsigned int den, unsigned int den) </code> <br />
+Initializes the genqdyn <em>*g</em> to hold objects of size <em>esize</em>.
+<em>g</em> must be unused, or have been freed. The <em>num</em> and <em>den</em>
+arguments tune <em>g</em>'s behaviour as described above in the GENQDYN_INIT
+description. This function is similar to the GENQDYN_INIT macro, except that
+it can be used dynamically and works on a pre-declared genqdyn, whereas the
+macro can only be used as a static initializer.
+</p>
+
+<p>
+<code> void genqdyn_init (genqdyn *g, size_t esize, unsigned int den, unsigned int den) </code> <br />
+Initializes the genqdyn <em>*g</em> to hold objects of size <em>esize</em>.
+<em>g</em> must be unused, or have been freed. The <em>num</em> and <em>den</em>
+arguments tune <em>g</em>'s behaviour as described above in the GENQDYN_INIT
+description.
+</p>
+
+<p>
+<code> void genqdyn_free (genqdyn *g) </code> <br />
+Frees the resources used by <em>*g</em>, which is then considered
+uninitialized.
+</p>
+
+<p>
+<code> int genqdyn_push (genqdyn *g, void const *p) </code> <br />
+ Pushes the object pointed to by <em>p</em> onto the queue. This object
+must have the same size that has been given to the <tt>genqdyn_init()</tt>
+invocation, or be of the same type that has been given to the
+<tt>GENQDYN_INIT()</tt> invocation. The function returns 1 if it succeeds
+and 0 (and sets errno) if it fails.
+</p>
+
+<p>
+<code> int genqdyn_unpush (genqdyn *g) </code> <br />
+ Undoes the last push. Returns 1, except if the queue is empty,
+in which case it returns 0 and sets errno to EINVAL.
+</p>
+
+<p>
+<code> int genqdyn_pop (genqdyn *g) </code> <br />
+ Pops an object from the queue, and possibly performs maintenance
+to reuse some memory. Returns 1, unless the queue is empty, in which
+case it returns 0 and sets errno to EINVAL.
+</p>
+
+</body>
+</html>
diff --git a/doc/libdatastruct/index.html b/doc/libdatastruct/index.html
@@ -34,8 +34,14 @@ lists and AVL trees, in a memory-efficient and CPU-efficient way.
<h2> Programming </h2>
<p>
-FIXME: to be completed.
+ <tt>skalibs/datastruct.h</tt> is a collection of several headers, each
+one defining a specific data structure and providing functions to work on it.
</p>
+<ul>
+ <li> <a href="genqdyn.html"><tt>skalibs/genqdyn.h</tt></a>: dynamically allocated queues for generic objects </li>
+ <li> FIXME: To be completed </li>
+</ul>
+
</body>
</html>
diff --git a/doc/upgrade.html b/doc/upgrade.html
@@ -21,6 +21,7 @@
<ul>
<li> New functions: <a href="libstddjb/djbunix.html">execvep_loose()</a>,
<tt>byte_zzero()</tt> </li>
+ <li> New family of functions: <a href="libdatastruct/genqdyn.html">skalibs/genqdyn.h</a> </li>
</ul>
<h2> in 2.6.3.1 </h2>
diff --git a/tools/convert-leapsecs.c b/tools/convert-leapsecs.c
@@ -9,12 +9,12 @@
#include <skalibs/genalloc.h>
#include <skalibs/skamisc.h>
-static genalloc table = GENALLOC_ZERO ; /* uint64 */
+static genalloc table = GENALLOC_ZERO ; /* uint64_t */
static void add_leapsecs (uint64_t *t)
{
- uint64_t *tab = genalloc_s(uint64, &table) ;
- size_t n = genalloc_len(uint64, &table) ;
+ uint64_t *tab = genalloc_s(uint64_t, &table) ;
+ size_t n = genalloc_len(uint64_t, &table) ;
size_t i = 0 ;
for (; i < n ; i++) if (*t >= tab[i]) (*t)++ ;
}
