aboutsummaryrefslogtreecommitdiffstats
path: root/man/man7/rb_overview.7
blob: 173faef010a82f93afed7c487bac7cf0edc8c5a1 (plain)
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
.TH "rb_overview" "7" "20 January 2018 (v2.1.0)" "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 "size_t rb_count(struct rb *" rb ");"
.br
.BI "size_t 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 thread safe and thread aware.
If there are no resources available while reading or writting, caller thread
gets locked and doesn't use any resources until data is available.
Ring buffer can also be configured 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.
Thread awarness can be disabled via
.B O_NONTHREAD
flags passed to
.BR rb_new (3).
In such case all calls to rb function will be non blocking.
Library can also be compiled without thread support at all, then it can be used
even in very constrained platforms.
.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, O_NONBLOCK | O_NONTHREAD);

        /* 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_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)