SHMFIFO
Shared Memory Block FIFO Pipe Implementation Library

version 1.0

About shmfifo
-------------
SHMFIFO library provides easy to use interface to shared mem for programs
where one process needs to send blocks of data to other process. It was
developed because pipe(2) and mkfifo(3) has very small buffer size (4k) and
unsuitable for many applications.

Shmfifo allows to put block of data in shared memory, get oldest block of
data from shared memory, and has additional feature to share one instance of
private data structure among all processes which uses library.  


How to use shmfifo
------------------
Before using, shared memory should be created. After creating shared memory,
process which wants to use it, should attach to memory. Then it can put and
get blocks to FIFO. After process is finished working with FIFO, it calls
shfifo_detach. When no processes will use FIFO, shared memory should be
deallocated. 

Usally, lifecycle of shmfifo-based program is following:
1. [parent] shmfifo_create
2. [parent] fork(2)
2. [both] shmfifo_attach
3. [both] shmfifo_put, shmfifo_get  (many times)
4. [both] shmfifo_detach
5. [parent] wait(2) or waitpid(2)
6. [child] exit
7. [parent] shmfifo_dealloc

shmfifo comes with test.c program, which is good sample of how to write
programs with shmfifo. It forks into 2 processes, parent generated
variable-length blocks, writes checksum into each block and put it into
FIFO. Child gets blocks from fifo, check if checksum is valid (it's always
valid if there is no bug in program) and prints debug info. after large
number of blocks gets transferred, both processes are exit.   

Additionally, shmfifo allows processes to share one private structure.
test.c uses this structure to store counter, which is increased each time
when parent cannot put block to FIFO because it's already full and has to
wait until child will get block. If small amount of memory allocated for
FIFO, then parent will wait more often.  


Functions of shmfifo
--------------------
struct shmhandle *shmfifo_create(int npages, int privsz);
- Allocated shared memory, semaphores, and performs initialization of
internal structures. Returns ptr to allocated shmhandle struct of NULL if
there were errors. npages is number of 4k pages which should be used for
shared memory. privsz is size of private structure if you want to use it.
shmfifo_create should be called from main process and shmhandle should
exists in all processes which will work with library functions.     

int shmfifo_attach(struct shmhandle *shm);
- Attaches process to fifo. Returns -1 if error and 1 if ok.

void shmfifo_detach(struct shmhandle *shm);
- Detaches. 

void shmfifo_dealloc(struct shmhandle *shm);
- Deallocates all shared memory. Should be called in main process after all
children (and main process) called detach function. 

int shmfifo_put(struct shmhandle *shm, void *data, int sz);
- creates block in shared memory of size 'sz' and content copied from data.
returns sz if successful or -1 if failed (e.g. if no enough free space in
fifo). 

int shmfifo_get(struct shmhandle *shm, void *data,int sz);
- gets block from fifo. data points to area where it will be copies, sz is
size of this area. Returns size of copied data or -2 if sz is less then
blocksize and -1 if any other error.

void shmfifo_setpriv(struct shmhandle *shm, void *priv);
void shmfifo_getpriv(struct shmhandle *shm, void *priv);
- copies private structure to shared memory and back from shared memory to
usual process memory. 

int shmfifo_empty(struct shmhandle *shm);
- returns 1 if FIFO is empty.