Add genqdyn doc

author: Laurent Bercot <ska-skaware@skarnet.org> 2018-03-16 13:25:03 +0000
committer: Laurent Bercot <ska-skaware@skarnet.org> 2018-03-16 13:25:03 +0000
commit: dd174c64d5f91debf561a0266b18989696d3eaf8 (patch)
tree: 7e7b6a9fd0275336b0786655886b18f229c216a0
parent: 6bae0b3d69c7968586afc73827b5844c6a23873f (diff)
download: skalibs-dd174c64d5f91debf561a0266b18989696d3eaf8.tar.xz
5 files changed, 139 insertions, 4 deletions
diff --git a/NEWS b/NEWS
index 05bfb32..7d12046 100644
--- 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
new file mode 100644
index 0000000..4f1c8f1
--- /dev/null
+++ 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
index 2ecf854..a0cf918 100644
--- 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>:&nbsp;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
index 18a8656..f14f557 100644
--- 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
index 9964b74..27f8507 100644
--- 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)++ ;
 }
author	Laurent Bercot <ska-skaware@skarnet.org>	2018-03-16 13:25:03 +0000
committer	Laurent Bercot <ska-skaware@skarnet.org>	2018-03-16 13:25:03 +0000
commit	dd174c64d5f91debf561a0266b18989696d3eaf8 (patch)
tree	7e7b6a9fd0275336b0786655886b18f229c216a0
parent	6bae0b3d69c7968586afc73827b5844c6a23873f (diff)
download	skalibs-dd174c64d5f91debf561a0266b18989696d3eaf8.tar.xz