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
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
|
.TH "rb_overview" "7" "25 January 2018 (v2.1.2)" "bofc.pl"
.SH NAME
.PP
.B rb_overview
\- quick overview of librb ring buffer library
.SH SYNOPSIS
.PP
.B librb
- library that provides fast, easy to use ring buffer implementation.
Its interface is very similar to read/write functions from
.B POSIX.
Basic usage can be done with only 4 functions:
.PP
.B #include <librb.h>
.PP
.BI "struct rb *rb_new(size_t " count ", size_t " object_size ", \
unsigned long " flags ");"
.br
.BI "int rb_destroy(struct rb *" rb ");"
.br
.BI "long rb_read(struct rb *" rb ", void *" buffer ", size_t " count ");"
.br
.BI "long rb_write(struct rb *" rb ", const void *" buffer ", \
size_t " count ");"
.PP
Additinal functions are provided for better control over buffer
.PP
.BI "long rb_recv(struct rb *" rb ", void *" buffer ", size_t " count ", \
unsigned long " flags ");"
.br
.BI "long rb_send(struct rb *" rb ", const void *" buffer ", \
size_t " count ", unsigned long " flags ");"
.BI "int rb_clear(struct rb *" rb ", int " clear ");"
.br
.BI "long rb_count(struct rb *" rb ");"
.br
.BI "long rb_space(struct rb *" rb ");"
.br
.BI "int rb_stop(struct rb *" rb ");"
.br
.BI "const char *rb_version(char *" major ", char *" minor ", char *" patch ");"
.SH DESCRIPTION
.PP
.B librb
is a simple ring buffer implementation that operates on objects rather than
raw bytes.
See
.BR rb_new (3)
to know what that means.
By default library operates in single-thread mode which is way faster than
multi-thread mode but naturally will break if concurrent thread will try to
access
.I rb
object.
To relief user from pesky synchronization process, library can optionally be
thread safe and thread aware by passing
.B O_MULTITHREAD
flag to
.BR rb_new (3).
In multi-thread mode if there are no resources available while reading or
writting, caller thread gets locked and doesn't use any resources until data is
available.
This behaviour can be altered to work in non-blocking mode, so calls from
read and write will return immediately when there are not enough resources.
malloc and free are called only in new and destory functions.
.PP
As this library is focused on speed, user can create buffer with only power of
two count (n^2).
Thanks to this solution there are much less conditional jumps.
Altough user is limited to number of elements that can be stored in buffer,
single element can be any size.
Thanks to that, ring buffer can be used with raw data (like from 8bit adc when
object size is 1 byte) or bigger raw data (like from 12bit adc when object size
is 2 bytes) or even more sophisticated types like structures with any number of
parameters when object size is set to sizeof(struct s).
.SH EXAMPLE
.PP
Please note, that example is missing error handling for simplicity.
.EX
.PP
#include <rb.h>
#include <stdio.h>
int main(void)
{
char i;
char data[] = "abcdefghij";
struct rb *rb;
/* initialize ring buffer with 32 1-byte elements */
rb = rb_new(32, 1, 0);
/* add data to buffer one byte at a time */
for (i = '0'; i <= '9'; ++i)
rb_write(rb, &i, 1);
/* add data in a single burst */
rb_write(rb, data, sizeof(data) - 1);
/* print data in packets of 8 bytes */
for (;;)
{
int bytes_read;
char buf[8 + 1] = {0};
bytes_read = rb_read(rb, buf, 8);
if (bytes_read == 0) /* nothing left to read */
break;
printf("%s\\n", buf);
}
/* clean up */
rb_destroy(rb);
return 0;
}
.EE
.SH SEE ALSO
.PP
.BR rb_overview (7),
.BR rb_new (3),
.BR rb_destroy (3),
.BR rb_discard (3),
.BR rb_stop (3),
.BR rb_read (3),
.BR rb_recv (3),
.BR rb_write (3),
.BR rb_send (3),
.BR rb_clear (3),
.BR rb_count (3),
.BR rb_space (3),
.BR rb_version (3)
|
