libshbuf 0.0.3

   Copyright 2003 Lennart Poettering <mzfuohs (at) 0pointer (dot) de>
     * [1]License
     * [2]News
     * [3]Overview
     * [4]Status
     * [5]Documentation
     * [6]Requirements
     * [7]Installation
     * [8]Acknowledgements
     * [9]Download

License

   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation; either version 2 of the License, or (at
   your option) any later version.

   This program 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
   General Public License for more details.

   You should have received a copy of the GNU General Public License
   along with this program; if not, write to the Free Software
   Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

News

   Thu Sep 11 2003:

   [10]Version 0.0.3 released; Changes include: autoconf update,
   documentation update, some code bug fixes.

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:
     * Normally better latency and throughput
     * Full access to the buffer at any time
     * Connecting processes need not to be children of each other
     * Arbitrary buffer lengths
     * Memory mapped
     * 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.

Status

   Version 0.0.3 is stable and feature complete.

Documentation

  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 [11]src/shbuftest.c for a simple example.

  API Reference

   There is a Doxygen generated [12]API reference available.

  Python Module

   I wrote a basic shbuf module for interfacing shbuf objects from within
   Python. It is called [13]python-shbuf.

Requirements

   libshbuf was developed and tested on Debian GNU/Linux "testing" from
   September 2003, it should work on most other Linux distributions and
   may be POSIX implementations since it uses GNU autoconf for source
   code configuration.

Installation

   As this package is made with the GNU autotools you should run
   ./configure inside the distribution directory for configuring the
   source tree. After that you should run make for compilation and make
   install (as root) for installation of libshbuf.

Acknowledgements

   Thanks go to Sam Clegg for some work, especially related to the build
   system.

Download

   The newest release is always available from
   [14]http://0pointer.de/lennart/projects/libshbuf/

   The current release is [15]0.0.3

   Get libshbuf's development sources from the CVS [16]repository.

   There is a [17]Sourceforge project page for libshbuf
     _________________________________________________________________


    Lennart Poettering <mzfuohs (at) 0pointer (dot) de>, Sep 2003

   $Id: README.html.in,v 1.3 2003/09/11 17:04:23 poettering Exp $

References

   1. README#license
   2. README#news
   3. README#overview
   4. README#status
   5. README#documentation
   6. README#requirements
   7. README#installation
   8. README#acks
   9. README#download
  10. http://0pointer.de/lennart/projects/libshbuf/libshbuf-0.0.3.tar.gz
  11. http://0pointer.de/lennart/projects/libshbuf/reference/html/shbuftest_8c-example.html
  12. http://0pointer.de/lennart/projects/libshbuf/reference/html/
  13. http://0pointer.de/lennart/projects/python-shbuf/
  14. http://0pointer.de/lennart/projects/libshbuf/
  15. http://0pointer.de/lennart/projects/libshbuf/libshbuf-0.0.3.tar.gz
  16. http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/libshbuf/libshbuf/
  17. http://sourceforge.net/projects/libshbuf/