genqdyn.html (4418B)
1 <html> 2 <head> 3 <meta name="viewport" content="width=device-width, initial-scale=1.0" /> 4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 5 <meta http-equiv="Content-Language" content="en" /> 6 <title>skalibs: the genqdyn library interface</title> 7 <meta name="Description" content="skalibs: the genqdyn library interface" /> 8 <meta name="Keywords" content="skalibs c unix genqdyn library queue libdatastruct" /> 9 <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> 10 </head> 11 <body> 12 13 <p> 14 <a href="index.html">libdatastruct</a><br /> 15 <a href="../libskarnet.html">libskarnet</a><br /> 16 <a href="../index.html">skalibs</a><br /> 17 <a href="//skarnet.org/software/">Software</a><br /> 18 <a href="//skarnet.org/">skarnet.org</a> 19 </p> 20 21 <h1> The <tt>genqdyn</tt> library interface </h1> 22 23 <p> 24 The following functions are declared in the <tt>skalibs/genqdyn.h</tt> header, 25 and implemented in the <tt>libskarnet.a</tt> or <tt>libskarnet.so</tt> library. 26 </p> 27 28 <h2> General information </h2> 29 30 <p> 31 <tt>genqdyn</tt> is a set of functions implementing simple queues on 32 generic objects. The <em>dyn</em> prefix means the queues are dynamically 33 allocated (and live in heap memory): it is possible to enqueue an arbitrary 34 number of objects, up to the available memory. 35 </p> 36 37 <h2> Data structures </h2> 38 39 <p> 40 A <tt>genqdyn</tt> structure holds the information necessary to implement 41 a queue. It can be declared anywhere (including in the stack). All genqdyn 42 functions take a pointer to this structure as an argument. 43 </p> 44 45 <h2> Macros </h2> 46 47 <p> 48 <code> genqdyn GENQDYN_INIT(type, num, den) </code> <br /> 49 Returns an anonymous genqdyn structure suitable for holding objects of 50 type <em>type</em>. The <em>num</em> and <em>den</em> arguments are integers, 51 used to tune the amount of memory needed / management overhead balance. 52 <em>num</em>/<em>den</em> must be a fractional value between 0 and 1. 53 The closer to 0, the longer genqdyn will wait before performing a 54 cleanup (and the more memory it can consume). At 0, genqdyn can only 55 recycle memory when the queue becomes totally empty. The closer to 1, 56 the more genqdyn optimizes its memory usage (and the more often it 57 performs maintenance on its queue). At 1, it performs maintenance 58 every time an object is popped. 59 Anything between 1/4 and 3/4 is a reasonable value for <em>num</em>/<em>den</em>. 60 </p> 61 62 <p> 63 <code> size_t genqdyn_n (genqdyn *g) </code> <br /> 64 Returns the number of elements in the genqdyn <em>*g</em>, which must 65 have been initialized. 66 </p> 67 68 <p> 69 <code> void *genqdyn_peek (genqdyn *g) </code> <br /> 70 Peeks at the next object in the queue, i.e. the object that has 71 been pushed the earliest and that hasn't been popped yet. 72 You can use the <tt>GENQDYN_PEEK(type, g)</tt> macro to get a 73 <tt>type *</tt> pointer instead of a <tt>void *</tt> one. 74 </p> 75 76 77 78 <h2> Functions </h2> 79 80 <p> 81 <code> void genqdyn_init (genqdyn *g, size_t esize, unsigned int num, unsigned int den) </code> <br /> 82 Initializes the genqdyn <em>*g</em> to hold objects of size <em>esize</em>. 83 <em>g</em> must be unused, or have been freed. The <em>num</em> and <em>den</em> 84 arguments tune <em>g</em>'s behaviour as described above in the GENQDYN_INIT 85 description. This function is similar to the GENQDYN_INIT macro, except that 86 it can be used dynamically and works on a pre-declared genqdyn, whereas the 87 macro can only be used as a static initializer. 88 </p> 89 90 <p> 91 <code> void genqdyn_free (genqdyn *g) </code> <br /> 92 Frees the resources used by <em>*g</em>, which is then considered 93 uninitialized. 94 </p> 95 96 <p> 97 <code> int genqdyn_push (genqdyn *g, void const *p) </code> <br /> 98 Pushes the object pointed to by <em>p</em> onto the queue. This object 99 must have the same size that has been given to the <tt>genqdyn_init()</tt> 100 invocation, or be of the same type that has been given to the 101 <tt>GENQDYN_INIT()</tt> invocation. The function returns 1 if it succeeds 102 and 0 (and sets errno) if it fails. 103 </p> 104 105 <p> 106 <code> int genqdyn_unpush (genqdyn *g) </code> <br /> 107 Undoes the last push. Returns 1, except if the queue is empty, 108 in which case it returns 0 and sets errno to EINVAL. 109 </p> 110 111 <p> 112 <code> int genqdyn_pop (genqdyn *g) </code> <br /> 113 Pops an object from the queue, and possibly performs maintenance 114 to reuse some memory. Returns 1, unless the queue is empty, in which 115 case it returns 0 and sets errno to EINVAL. 116 </p> 117 118 </body> 119 </html>