Changeset 1347 for portaudio/branches

Show
Ignore:
Timestamp:
02/20/08 23:54:36 (9 months ago)
Author:
rossb
Message:

more ringbuffer comment docs and cleanups from Sven Fischer

Files:
1 modified

Legend:

Unmodified
Added
Removed

  • portaudio/branches/v19-devel/src/common/pa_ringbuffer.h

    r1346 r1347  
    5151/** @file 
    5252 @ingroup common_src 
     53 @brief Single-reader single-writer lock-free ring buffer 
     54 
     55 PaUtilRingBuffer is a ring buffer used to transport samples between 
     56 different execution contexts (threads, OS callbacks, interrupt handlers) 
     57 without requiring the use of any locks. This only works when there is 
     58 a single reader and a single writer (ie. one thread or callback writes 
     59 to the ring buffer, another thread or callback reads from it). 
     60 
     61 The PaUtilRingBuffer structure manages a ring buffer containing N  
     62 elements, where N must be a power of two. An element may be any size  
     63 (specified in bytes). 
     64 
     65 The memory area used to store the buffer elements must be allocated by  
     66 the client prior to calling PaUtil_InitializeRingBuffer() and must outlive 
     67 the use of the ring buffer. 
    5368*/ 
    5469 
    … …  
    6075typedef struct PaUtilRingBuffer 
    6176{ 
    62     long  bufferSize;   /* Number of elements in FIFO. Power of 2. Set by PaUtil_InitRingBuffer. */ 
    63     long  writeIndex;   /* Index of next writable element. Set by PaUtil_AdvanceRingBufferWriteIndex. */ 
    64     long  readIndex;    /* Index of next readable element. Set by PaUtil_AdvanceRingBufferReadIndex. */ 
    65     long  bigMask;    /* Used for wrapping indices with extra bit to distinguish full/empty. */ 
    66     long  smallMask;  /* Used for fitting indices to buffer. */ 
    67     long  elementSizeBytes; /* Number of bytes per element. */ 
    68     char  *buffer; 
     77    long  bufferSize; /**< Number of elements in FIFO. Power of 2. Set by PaUtil_InitRingBuffer. */ 
     78    long  writeIndex; /**< Index of next writable element. Set by PaUtil_AdvanceRingBufferWriteIndex. */ 
     79    long  readIndex;  /**< Index of next readable element. Set by PaUtil_AdvanceRingBufferReadIndex. */ 
     80    long  bigMask;    /**< Used for wrapping indices with extra bit to distinguish full/empty. */ 
     81    long  smallMask;  /**< Used for fitting indices to buffer. */ 
     82    long  elementSizeBytes; /**< Number of bytes per element. */ 
     83    char  *buffer;    /**< Pointer to the buffer containing the actual data. */ 
    6984}PaUtilRingBuffer; 
    7085 
    … …  
    7388 @param rbuf The ring buffer. 
    7489 
    75  @param elementCount The number of elements in the buffer and must be power of 2. 
     90 @param elementSizeBytes The size of a single data element in bytes. 
     91 
     92 @param elementCount The number of elements in the buffer (must be power of 2). 
    7693 
    7794 @param dataPtr A pointer to a previously allocated area where the data