filter.c: Handle filter errors gracefully.
[paraslash.git] / ringbuffer.c
1 /*
2 * Copyright (C) 2006-2008 Andre Noll <maan@systemlinux.org>
3 *
4 * Licensed under the GPL v2. For licencing details see COPYING.
5 */
6
7 /** \file ringbuffer.c Simple ringbuffer implementation */
8
9 #include "para.h"
10 #include "ringbuffer.h"
11 #include "string.h"
12
13 /**
14 * Holds all information about one ring buffer
15 *
16 * It is intentionally not exported via ringbuffer.h. Think abstract.
17 */
18 struct ringbuffer
19 {
20 /** The size of this ring buffer. */
21 unsigned size;
22 /** The actual entries of the ringbuffer. */
23 void **entries;
24 /** The next entry will be added at this position. */
25 int head;
26 /** How many entries the ring buffer contains. */
27 unsigned filled;
28 };
29
30 /**
31 * Initialize a new ringbuffer.
32 *
33 * \param size The number of entries the ringbuffer holds.
34 *
35 * This function initializes a circular ring buffer which can hold up to \a
36 * size entries of arbitrary type. If performance is an issue, \a size should
37 * be a power of two to make the underlying modulo operations cheap. Arbitrary
38 * many ringbuffers may be initialized via this function. Each ringbuffer is
39 * identified by a 'cookie'.
40 *
41 * \return A 'cookie' which identifies the ringbuffer just created and
42 * which must be passed to ringbuffer_add() and ringbuffer_get().
43 */
44 struct ringbuffer *ringbuffer_new(unsigned size)
45 {
46 struct ringbuffer *rb = para_calloc(sizeof(struct ringbuffer));
47 rb->entries = para_calloc(size * sizeof(void *));
48 rb->size = size;
49 return rb;
50 };
51
52 /**
53 * Add one entry to a ringbuffer.
54 *
55 * \param rb The ringbuffer identifier.
56 * \param data The data to be inserted.
57 *
58 * Insert \a data into the ringbuffer associated with \a cookie. As soon as
59 * the ringbuffer fills up, its oldest entry is disregarded and replaced by \a
60 * data.
61 *
62 * \return The old \a data pointer which is going to be disregarded, or
63 * NULL if the ringbuffer is not yet full.
64 */
65 void *ringbuffer_add(struct ringbuffer *rb, void *data)
66 {
67 void *ret = rb->entries[rb->head];
68 rb->entries[rb->head] = data;
69 rb->head = (rb->head + 1) % rb->size;
70 if (rb->filled < rb->size)
71 rb->filled++;
72 return ret;
73 }
74
75 /**
76 * Get one entry from a ringbuffer.
77 *
78 * \param rb The ringbuffer identifier.
79 * \param num The number of the entry.
80 *
81 * \return A pointer to data previously added, or NULL if entry number
82 * \a num is not available. \a num counts backwards from zero, i.e.
83 * ringbuffer_get_entry(0) gets the entry which was added most recently.
84 */
85 void *ringbuffer_get(struct ringbuffer *rb, int num)
86 {
87 int pos = (rb->head + rb->size - 1 - num) % rb->size;
88 // fprintf(stderr, "pos = %d\n", pos);
89 return rb->entries[pos];
90 }
91
92 /**
93 * Get the number of entries in the ring buffer.
94 *
95 * \param rb The ringbuffer identifier
96 *
97 * This function always succeeds and never returns a number greater than the
98 * size of the ring buffer.
99 */
100 unsigned ringbuffer_filled(struct ringbuffer *rb)
101 {
102 return rb->filled;
103 }