VRB - Virtual Ring Buffer

Download now: vrb-0.5.1.tar.bz2 [41106 bytes] or vrb-0.5.1.tar.gz [48050 bytes]

Introduction

The Virtual Ring Buffer (VRB) is an implementation of a character FIFO ring buffer. It provides direct access to the buffer so the calling program can construct output data in place, or parse input data in place, without the extra step of copying data to or from a calling program provided buffer area. In order to facilitate this direct access, VRB makes sure that all references to buffer locations for either output or input is always a single contiguous block of memory so that the calling program does not have to deal with split buffer spaces every time the cycling of data reaches the end of the buffer and wraps around to the beginning. Thus, the calling program is free to use any number of tools available which do not have to be aware that they are operating directly in a ring buffer. In the latest version, VRB also provides a buffer overflow protection mechanism so that buffer overflow bugs force the program to be trapped by the operating system if accessed pointers wander beyond the range of address space managed by VRB. This feature can be disabled if desired, since it occupies 2 extra pages of address space.
VRB does all this without adding any copying overhead of its own. This ability is achieved by placing a mirror image memory map immediately after the buffer that is a reference to exactly the same memory as the buffer itself. Thus a reference to the memory location immediately past the last location in the buffer accesses the same physical RAM as the beginning of the buffer. Thus a pointer near the end of the buffer that has a length that would otherwise have to wrap around will instead extend into the mirror image space to get the same result, but without any special handling by the program.

Licensing

Copyright © 2006 - Philip Howard - All rights reserved
You may copy and distribute this software under the terms of the GNU Lesser General Public License:
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
License
as published by the Free Software Foundation; either
version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public
License
along with this library; if not, write to the Free Software
Foundation, Inc.
, 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
You may also view the GNU Lesser General Public License here or there.

Download

Click on one of the links shown to download the VRB source code.

Installation

First extract the source where you wish to store it. One of these commands might be used within the desired directory after the tar files has been downloaded there:
bunzip2 < vrb-0.5.1.tar.bz2 | tar -xpf -
gunzip < vrb-0.5.1.tar.gz | tar -xpf -
A subdirectory called vrb-0.5.1 is created. Execute these command to change into that directory and compile the source (changing the prefix if desired):
cd vrb-0.5.1
./Configure --prefix=/usr/local
make clean
make install
Note that unlike most other source packages using a configuration system, the configure command name is capitalized. The above commands will not install the man pages at this time. To install the man pages, simply copy them to the desired location, such as:
cp -p vrb/man/man3/*.3 /usr/local/man/man3

Usage

VRB's basic approach designed into its API is that the calling program asks for the address and length of either the empty space where output data can be placed, or the data space where input data is present (previously placed there). These steps are implemented by macros for maximum speed, and are separate for address and length. The calling program then accesses that data directly in the buffer via that address (and length). Once the data handling is complete, the calling program decides how much of that data it has inserted into empty space, or taken from data space, and calls VRB functions to indicate the which, which updates pointers (but does not copy any data). There are also functions available to assist in doing read/write I/O. Once the man pages are installed, the command man vrb is the starting point.

This web page is: Copyright © 2006; by Phil Howard - all rights reserved.
You may copy this web page under the terms of the GNU Free Documentation License.
Last revised: 2-Aug-2006