Quick Reference Table

PPBCheckRdAvail	PPBCheckWrFree
PPBClose	PPBErrorCode
PPBFlush	PPBGetMemBuf
PPBOpen	PPBPutByte
PPBPutWord	PPBRead
PPBWrite

Introduction

Ping-pong buffers are a specialized form of FIFO (First-In, First-out) queue that divides a block of storage into two equal halves, with one half (the write buffer) generally always available for writing, and the other half (the read buffer) generally emptied in one fell swoop when the write buffer fills and the ping-pong action makes the former write buffer now available for reading. Ping-pong buffers are similar to ring or circular buffers in that you you can keep writing to them so long as the corrosponding reads empty the buffer before it fills. They differ in that the read data does not become available until after the write buffer has filled, and more important (for the common memory buffers) the read buffer when available is guaranteed to be one contiguous chunk. This means you can send the output from a ping-pong buffer as a pointer argument to other routines, like memcpy(), write(), fwrite() and so on. You could construct a ping-pong buffer from a ring buffer by not reading from the buffer until it became half-full, but you could not access the data as a contigous block. The ping-pong buffer presented here is tailored for maximum efficiency in ping-pong mode.

Ping-pong buffers are especially useful for holding data that will ultimately be stored to devices that work best when handling large discrete blocks. For example, the Persistor GB2 uses a pair of ping-pong buffers to allow it to continuously accept incomming data streams at rates of up to 100kb/s while keeping the hard disk drive fully shut down whenever it's not absolutely essential that it be on. Incomming data steams into a 64KB ping-pong buffer (32KB/32KB) and when one half fills up and the buffer ping-pongs, the 32kb of available data is streamed into 40MB CompactFlash card ping-pong buffer (20MB/20MB) that takes advantage of the 32KB block size to write much faster and consume less power than it would working in smaller blocks. When the CompactFlash buffer ping-pongs, the hard drive is powered up (which typically takes four seconds, but is specified for a worst case of 20 seconds) then the CompactFlash data is pulled from the ping-pong buffer (in 32KB chuncks to allow the RAM ping-pong buffer to write new data) and written to the hard drive, after which it gets shut back down.

enum
    {
      ppbErrorStart = PPB_ERRORS
    , ppbWrOvflBufNotEmpty      // write operation would overflow to non-empty buffer
    , ppbWrIOFailed             // low level write failed
    , ppbRdIOFailed             // low level read failed
    , ppbRdBufferEmpty          // no data in read buffer
    , ppbMemAccReqToNonMem      // attempted direct memory access to non-memory device
    , pppWrBufferInUse          // attempted to write while another write was in process
    , pppRdBufferInUse          // attempted to read while another read was in process
    };

PPBOpen -- Open and initialize a ping-pong buffer

Description

typedef long    PPBWrf(void *buf, void *wrp, ulong wrofs, ulong n);
typedef long    PPBRdf(void *buf, void *rdp, ulong rdofs, ulong n);

Prototype:	void *PPBOpen(long totSize, void *buf, PPBRdf rdf, PPBWrf wrf, vfptr ppnotify);
Definition:	#include <cf1pico.h>
Inputs:	totSize is the combined size in bytes of both halves of the user supplied ping-pong buffer buf is user supplied ping-pong buffer rdf is an optional user supplied function that reads data from the ping-pong buffer (pass zero for default memory functions) wrf is an optional user supplied function that writes data into the ping-pong buffer (pass zero for default memory functions) ppnotify is an optional user supplied function to call when the ping-pong buffer wraps.
Returns:	Returns a generic pointer used internally by PPB to manage the buffers or zero on failure
Notes:	Notes
Timing:	TBD

PPBClose -- Close a ping-pong buffer (does not automatically flush)

Description

Prototype:	void PPBClose(void *ppb);
Definition:	#include <cf1pico.h>
Inputs:	ppb is the generic pointer returned by PPBOpen and used internally to manage the buffers.
Returns:	Returns nothing
Notes:	Notes
Timing:	TBD

PPBFlush -- Flush a ping-pong buffer and force a ping-pong flip

Description

Prototype:	short PPBFlush(void *ppb);
Definition:	#include <cf1pico.h>
Inputs:	ppb is the generic pointer returned by PPBOpen and used internally to manage the buffers.
Returns:	Returns zero for success or a non-zero error code
Notes:	Notes
Timing:	TBD

PPBWrite -- Write data into the ping-pong buffer

Description

Prototype:	long PPBWrite(void *ppb, void *buf, long nbyte);
Definition:	#include <cf1pico.h>
Inputs:	ppb is the generic pointer returned by PPBOpen and used internally to manage the buffers. buf is a pointer to a block of data to write data into the FIFO nbyte is the number of bytes to write
Returns:	Returns nbyte for complete success or the number of bytes written
Notes:	Notes
Timing:	TBD

PPBRead -- Read data from the ping-pong buffer

Description

Prototype:	long PPBRead(void *ppb, void *buf, long nbyte);
Definition:	#include <cf1pico.h>
Inputs:	ppb is the generic pointer returned by PPBOpen and used internally to manage the buffers. buf is a pointer to a block of data to read from the FIFO nbyte is the number of bytes to write
Returns:	Returns nbyte for complete success or the number of bytes read
Notes:	Notes
Timing:	TBD

PPBPutByte -- Write 8-bit byte into the ping-pong buffer

Description

Prototype:	short PPBPutByte(void *ppb, uchar byte);
Definition:	#include <cf1pico.h>
Inputs:	ppb is the generic pointer returned by PPBOpen and used internally to manage the buffers. byte is 8 bit value to write
Returns:	Returns zero for success or a non-zero error code
Notes:	Notes
Timing:	TBD

PPBPutWord -- Write 16-bit word into the ping-pong buffer

Description

Prototype:	short PPBPutWord();
Definition:	#include <cf1pico.h>
Inputs:	ppb is the generic pointer returned by PPBOpen and used internally to manage the buffers. word is the 16 bit value to write
Returns:	Returns zero for success or a non-zero error code
Notes:	Notes
Timing:	TBD

PPBGetMemBuf -- Return the read buffer and optionally zero the size

Description

Prototype:	void *PPBGetMemBuf(void *ppb, long *size, bool flush);
Definition:	#include <cf1pico.h>
Inputs:	ppb is the generic pointer returned by PPBOpen and used internally to manage the buffers. size is a pointer to a long variable to accept the count of available bytes flush if true resets the read buffer to indicate that the data has been read
Returns:	Returns a direct pointer to the read data buffer
Notes:	Notes
Timing:	TBD

PPBCheckRdAvail -- Return the number of bytes waiting to be read

Description

Prototype:	long PPBCheckRdAvail(void *ppb);
Definition:	#include <cf1pico.h>
Inputs:	ppb is the generic pointer returned by PPBOpen and used internally to manage the buffers.
Returns:	Returns the count of available bytes in the read buffer
Notes:	Notes
Timing:	TBD

PPBCheckWrFree -- Return the free space left before a wrap

Description

Prototype:	long PPBCheckWrFree(void *ppb);
Definition:	#include <cf1pico.h>
Inputs:	ppb is the generic pointer returned by PPBOpen and used internally to manage the buffers.
Returns:	Returns the number of bytes that can be written before the buffer ping-pongs
Notes:	Notes
Timing:	TBD

PPBErrorCode -- Return (and optionally clear) the ppb error code

Description

Prototype:	short PPBErrorCode(void *ppb, bool clear);
Definition:	#include <cf1pico.h>
Inputs:	ppb is the generic pointer returned by PPBOpen and used internally to manage the buffers. clear if true resets the error code to zero
Returns:	Returns the most recent error code from the enumerated list
Notes:	Notes
Timing:	TBD

Previous

Next

Top

Contents

Glossary

Index

Tel: 508-759-6434		Fax: 508-759-6436
Copyright (C) 1998 Persistor Instruments Inc. - All Rights Reserved