annotate libgaim/circbuffer.h @ 15165:2c0e3ef91e37

[gaim-migrate @ 17950] credit committer: Tailor Script <tailor@pidgin.im>
author Sean Egan <seanegan@gmail.com>
date Sun, 10 Dec 2006 23:32:28 +0000
parents 60b1bc8dbf37
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
14192
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
1 /*
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
2 * @file circbuffer.h Buffer Utility Functions
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
3 * @ingroup core
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
4 *
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
5 * Gaim is the legal property of its developers, whose names are too numerous
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
6 * to list here. Please refer to the COPYRIGHT file distributed with this
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
7 * source distribution.
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
8 *
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
9 * This program is free software; you can redistribute it and/or modify
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
10 * it under the terms of the GNU General Public License as published by
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
11 * the Free Software Foundation; either version 2 of the License, or
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
12 * (at your option) any later version.
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
13 *
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
14 * This program is distributed in the hope that it will be useful,
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
17 * GNU General Public License for more details.
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
18 *
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
19 * You should have received a copy of the GNU General Public License
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
20 * along with this program; if not, write to the Free Software
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
21 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
22 */
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
23 #ifndef _CIRCBUFFER_H
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
24 #define _CIRCBUFFER_H
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
25
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
26 #include <glib.h>
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
27
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
28 #ifdef __cplusplus
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
29 extern "C" {
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
30 #endif
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
31
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
32 typedef struct _GaimCircBuffer {
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
33
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
34 /** A pointer to the starting address of our chunk of memory. */
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
35 gchar *buffer;
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
36
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
37 /** The incremental amount to increase this buffer by when
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
38 * the buffer is not big enough to hold incoming data, in bytes. */
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
39 gsize growsize;
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
40
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
41 /** The length of this buffer, in bytes. */
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
42 gsize buflen;
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
43
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
44 /** The number of bytes of this buffer that contain unread data. */
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
45 gsize bufused;
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
46
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
47 /** A pointer to the next byte where new incoming data is
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
48 * buffered to. */
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
49 gchar *inptr;
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
50
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
51 /** A pointer to the next byte of buffered data that should be
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
52 * read by the consumer. */
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
53 gchar *outptr;
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
54
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
55 } GaimCircBuffer;
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
56
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
57 /**
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
58 * Creates a new circular buffer. This will not allocate any memory for the
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
59 * actual buffer until data is appended to it.
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
60 *
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
61 * @param growsize The amount that the buffer should grow the first time data
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
62 * is appended and every time more space is needed. Pass in
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
63 * "0" to use the default of 256 bytes.
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
64 *
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
65 * @return The new GaimCircBuffer. This should be freed with
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
66 * gaim_circ_buffer_destroy when you are done with it
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
67 */
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
68 GaimCircBuffer *gaim_circ_buffer_new(gsize growsize);
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
69
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
70 /**
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
71 * Dispose of the GaimCircBuffer and free any memory used by it (including any
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
72 * memory used by the internal buffer).
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
73 *
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
74 * @param buf The GaimCircBuffer to free
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
75 */
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
76 void gaim_circ_buffer_destroy(GaimCircBuffer *buf);
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
77
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
78 /**
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
79 * Append data to the GaimCircBuffer. This will grow the internal
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
80 * buffer to fit the added data, if needed.
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
81 *
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
82 * @param buf The GaimCircBuffer to which to append the data
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
83 * @param src pointer to the data to copy into the buffer
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
84 * @param len number of bytes to copy into the buffer
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
85 */
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
86 void gaim_circ_buffer_append(GaimCircBuffer *buf, gconstpointer src, gsize len);
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
87
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
88 /**
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
89 * Determine the maximum number of contiguous bytes that can be read from the
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
90 * GaimCircBuffer.
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
91 * Note: This may not be the total number of bytes that are buffered - a
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
92 * subsequent call after calling gaim_circ_buffer_mark_read() may indicate more
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
93 * data is available to read.
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
94 *
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
95 * @param buf the GaimCircBuffer for which to determine the maximum contiguous
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
96 * bytes that can be read.
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
97 *
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
98 * @return the number of bytes that can be read from the GaimCircBuffer
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
99 */
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
100 gsize gaim_circ_buffer_get_max_read(GaimCircBuffer *buf);
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
101
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
102 /**
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
103 * Mark the number of bytes that have been read from the buffer.
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
104 *
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
105 * @param buf The GaimCircBuffer to mark bytes read from
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
106 * @param len The number of bytes to mark as read
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
107 *
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
108 * @return TRUE if we successfully marked the bytes as having been read, FALSE
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
109 * otherwise.
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
110 */
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
111 gboolean gaim_circ_buffer_mark_read(GaimCircBuffer *buf, gsize len);
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
112
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
113 #ifdef __cplusplus
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
114 }
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
115 #endif
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
116
60b1bc8dbf37 [gaim-migrate @ 16863]
Evan Schoenberg <evan.s@dreskin.net>
parents:
diff changeset
117 #endif /* _CIRCBUFFER_H */