1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
|
<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 num, 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_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>
|
