libshbuf - Library for Shared Buffer IPC
========================================

Overview
--------

libshbuf implements a new kind of IPC: the "shared buffer", a faster,
more flexible replacement for standard Unix FIFOs. It offers the
following advantages:

o Normally better latency and throughput
o Full access to the buffer at any time
o Connecting processes need not to be children of each other
o Arbitrary buffer lengths
o Memory mapped
o "Backlog"

The implementation is based on SysV shared memory, semaphores and
message queues. It makes use of POSIX pthreads. 

Both an easy understandable C library and a basic Python module are
provided.

Purpose
------

The concept of "shared buffers" is explicitly designed for high
thoughput, low latency streaming of data (e.g. audio) between two
processes, where a Unix FIFO is not enough. Thus it is optimized for
exactly two connecting peers, a minimum of locking and minimum of
copying of memory.

Technical Design
----------------

For each shared buffer two shared memory blocks, a semaphore and a
messages queue are created. The first shared memory block (aka
"control memory block") contains some watermark information about the
shared buffer. The second contains the buffer itself. The semaphore is
used for locking access to the control block. The message queue is
used for signalling the other side on changes of the buffer.

A shared buffer provider is a process which creates it with with
shbuf_create(). A new key for it will be registered (the key is an
integer value, the key_t of the control shm). A shared buffer client
is the other side of the buffer: it opens an existing buffer with
shbuf_open(key). Only one client and one provider may be connected at
once.

When using the notifying feature of libshbuf a background thread is
started, which listens on the message queue for certain messages. It
forwards these messages to a classic FIFO. The main program may listen
on this FIFO with a standard select() or poll().

Examples
--------

See src/shbuftest.c for a simple example.

(Online at http://libshbuf.sourceforge.net/html/shbuftest_8c-example.html)

Documentation
-------------

You may read the online documentation on:

  http://libshbuf.sourceforge.net/html/

After running "make doc" in the extracted distribution directory you
may have a look in doc/html/ for the same documentation extracted from
the source codes with doxygen.

Compiling
---------

The build system is based on GNU autoconf and GNU automake. Thus a
"configure && make && make install" should succeed for installing the
library. 
Some documentation may be compiled with "make doc", doxygen is needed
for doing so.

Python Module
-------------

I wrote a basic shbuf module for interfacing shbuf objects from within
python. It is called
"python-shbuf". (http://libshbuf.sourceforge.net/python-shbuf.html)

Download
--------
   
You may download libshbuf and python-shbuf from this URL:
http://prdownloads.sourceforge.net/libshbuf/

Homepage
--------

This README can be found on http://libshbuf.sourceforge.net/ 

The Sourceforge project page is http://sourceforge.net/projects/libshbuf/

The homepage of the author is http://www.poettering.de/lennart/

CVS Web interface at http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/libshbuf/libshbuf/

Lennart Poettering <mz7368627566@poettering.de>, May 2002

$Id: README,v 1.6 2002/05/02 17:02:20 poettering Exp $