randolf.ca  1.00
Randolf Richardson's C++ classes
Loading...
Searching...
No Matches
rring_bam
1#pragma once
2
3namespace randolf {
4
5 /*======================================================================*//**
6 @brief
7 This structure contains a Block Allocation Map (BAM) of the positions and
8 lengths of data blocks in ring buffer memory. This is part of an advanced
9 feature that's specifically useful for direct memory access to the ring
10 buffer's memory (access operations will likely need to be split into two
11 operations when the buffer straddles the ring buffer's memory boundary, which
12 benefits performance by making direct read/write operations with file and
13 socket I/O, but for most applications it's better to use the other methods
14 provided in the @ref randolf::rring class since this is what they were
15 designed for).
16
17 @note
18 This code demonstrates how to obtain a "bam" and access ring buffer memory by
19 using
20 this structure:
21 @code{.cpp}
22 #include <randolf/rring>
23 #include <randolf/rring_bam>
24
25 // ... code that initializes a ring buffer and populates it; documentation
26 // for the data_bam() method is available in the randolf::rring class ...
27
28 char b1 = 0;
29 char b2 = 0;
30 char a1 = 0;
31 char a2 = 0;
32
33 randolf::rring_bam bam = rb.data_bam();
34
35 if (bam->block1 != nullptr) // Check for pointer (avoids segfault)
36 b1 = ((char*)bam->block1)[0]; // First byte of utilized buffer memory
37
38 if (bam->block2 != nullptr) // Check for pointer (avoids segfault)
39 b2 = ((char*)bam->block2)[0]; // Second byte of utilized buffer memory
40
41 if (bam->avail1 != nullptr) // Check for pointer (avoids segfault)
42 a1 = ((char*)bam->avail1)[0]; // First byte of available buffer memory
43
44 if (bam->avail2 != nullptr) // Check for pointer (avoids segfault)
45 a2 = ((char*)bam->avail1)[0]; // Second byte of available buffer memory
46 @endcode
47 @see randolf::rring::data_bam
48 @par History
49 - 2024-Dec-03 v1.00 Initial version
50 @version 1.00
51 @author Randolf Richardson
52 *///=========================================================================
53 struct rring_bam {
54
55 /*======================================================================*//**
56 @brief
57 Pointer to first portion of utilized buffer memory.
58 *///=========================================================================
59 void* block1;
60
61 /*======================================================================*//**
62 @brief
63 Pointer to second portion of utilized buffer memory, if this part of the ring
64 buffer straddles the boundary, otherwise @c nullptr will be specified.
65 *///=========================================================================
66 void* block2;
67
68 /*======================================================================*//**
69 @brief
70 Pointer to first portion of available buffer memory.
71 *///=========================================================================
72 void* avail1;
73
74 /*======================================================================*//**
75 @brief
76 Pointer to second portion of available buffer memory, if this part of the
77 ring buffer straddles the boundary, otherwise @c nullptr will be specified.
78 *///=========================================================================
79 void* avail2;
80
81 /*======================================================================*//**
82 @brief
83 Number of elements in @ref block1.
84 *///=========================================================================
85 size_t block1_size;
86
87 /*======================================================================*//**
88 @brief
89 Number of elements in @ref block2.
90 *///=========================================================================
91 size_t block2_size;
92
93 /*======================================================================*//**
94 @brief
95 Number of elements in @ref avail1.
96 *///=========================================================================
97 size_t avail1_size;
98
99 /*======================================================================*//**
100 @brief
101 Number of elements in @ref avail2.
102 *///=========================================================================
103 size_t avail2_size;
104
105 }; // -x- struct rring_bam -x-
106
107}; // -x- namespace randolf -x-