Remove CFFI instance, add cdef() and init()

Author: mgeier

.gitmodules

@@ -1,7 +1,2 @@
 include LICENSE
 include *.rst
-recursive-include doc *.rst *.py
-include portaudio/LICENSE.txt
-include portaudio/index.html
-include portaudio/src/common/pa_ringbuffer.h
-include portaudio/src/common/pa_memorybarrier.h

MANIFEST.in

@@ -7,10 +7,10 @@ of PortAudio_, therefore most Python wrappers don't include it, either.
 This module can be compiled and used on any Python version where CFFI_ is
 available.
 
-The class `pa_ringbuffer.RingBuffer` is designed to be used together with the
-sounddevice_ module for non-blocking transfer of data from the main Python
-program to an audio callback function which is implemented in C or some other
-compiled language.
+This module is designed to be used together with the sounddevice_ module
+(it might work with other modules, too) for non-blocking transfer of data from
+the main Python program to an audio callback function which is implemented in C
+or some other compiled language.
 
 .. _PortAudio: http://portaudio.com/
 .. _sounddevice: http://python-sounddevice.readthedocs.io/
@@ -19,10 +19,81 @@ compiled language.
 Installation
 ------------
 
-::
+Use this if you want to install it locally in a development environment::
 
     python3 setup.py develop --user
 
 or ::
 
     python3 -m pip install -e . --user
+
+Usage
+-----
+
+This module is not meant to be used on its own, it is only useful in cooperation
+with another Python module using CFFI.
+
+You can get the Python code from PyPI (Note: not yet available!),
+for example in your ``setup.py`` file:
+
+.. code:: python
+
+    from setuptools import setup
+    
+    setup(
+        name=...,
+        version=...,
+        author=...,
+        ...,
+        setup_requires=['CFFI', 'pa_ringbuffer'],
+        install_requires=['pa_ringbuffer'],
+        ...,
+    )
+
+Alternatively, you can just copy the file ``src/pa_ringbuffer.py`` to your own
+source directory and import it from there.
+
+You can build your own CFFI module like described in
+http://cffi.readthedocs.io/en/latest/cdef.html, just adding a few more bits:
+
+.. code:: python
+
+    from cffi import FFI
+    import pa_ringbuffer
+    
+    ffibuilder = FFI()
+    ffibuilder.cdef(pa_ringbuffer.cdef())
+    ffibuilder.cdef("""
+    
+    /* my own declarations */
+    
+    """)
+    ffibuilder.set_source(
+        '_mycffimodule',
+        '/* my implementation */',
+        sources=['portaudio/src/common/pa_ringbuffer.c'],
+    )
+    
+    if __name__ == '__main__':
+        ffibuilder.compile(verbose=True)
+
+Note that the following files must be available to the compiler:
+
+* https://app.assembla.com/spaces/portaudio/git/source/master/src/common/pa_ringbuffer.c
+* https://app.assembla.com/spaces/portaudio/git/source/master/src/common/pa_ringbuffer.h
+* https://app.assembla.com/spaces/portaudio/git/source/master/src/common/pa_memorybarrier.h
+
+For your own C code, you might need some definitions from the main PortAudio
+header:
+
+* https://app.assembla.com/spaces/portaudio/git/source/master/include/portaudio.h
+
+Once you have compiled your extension module (with the help of CFFI), you can
+use something like this to get access to the ``RingBuffer`` class:
+
+.. code:: python
+
+    import pa_ringbuffer
+    from _mycffimodule import ffi, lib
+
+    RingBuffer = pa_ringbuffer.init(ffi, lib)

README.rst

@@ -12,17 +12,14 @@
     name='pa-ringbuffer',
     version=__version__,
     package_dir={'': 'src'},
-    py_modules=['pa_ringbuffer', '_pa_ringbuffer_build'],
-    setup_requires=['CFFI>=1.4.0'],
-    cffi_modules=['src/_pa_ringbuffer_build.py:ffibuilder'],
-    install_requires=['CFFI>=1'],  # for _cffi_backend
+    py_modules=['pa_ringbuffer'],
     author='Matthias Geier',
     author_email='[email protected]',
     description="Python wrapper for PortAudio's ring buffer",
     long_description=open('README.rst').read(),
     license='MIT',
     keywords='sound audio PortAudio ringbuffer lock-free'.split(),
-    #url='http://python-pa-ringbuffer.readthedocs.io/',
+    #url='',
     platforms='any',
     classifiers=[
         'License :: OSI Approved :: MIT License',

portaudio

@@ -2,11 +2,54 @@
 
 __version__ = '0.0.0'
 
-import _cffi_backend
-from _pa_ringbuffer import ffi as _ffi, lib as _lib
 
-
-class RingBuffer(object):
+def cdef():
+    """Return C declarations needed by CFFI."""
+    import platform
+
+    if platform.system() == 'Darwin':
+        ring_buffer_size_t = 'int32_t'
+    else:
+        ring_buffer_size_t = 'long'
+
+    return """
+/* Declarations from PortAudio's pa_ringbuffer.h: */
+typedef %(ring_buffer_size_t)s ring_buffer_size_t;
+typedef struct PaUtilRingBuffer
+{
+    ring_buffer_size_t  bufferSize;
+    volatile ring_buffer_size_t writeIndex;
+    volatile ring_buffer_size_t readIndex;
+    ring_buffer_size_t bigMask;
+    ring_buffer_size_t smallMask;
+    ring_buffer_size_t elementSizeBytes;
+    char* buffer;
+} PaUtilRingBuffer;
+ring_buffer_size_t PaUtil_InitializeRingBuffer(PaUtilRingBuffer* rbuf, ring_buffer_size_t elementSizeBytes, ring_buffer_size_t elementCount, void* dataPtr);
+void PaUtil_FlushRingBuffer(PaUtilRingBuffer* rbuf);
+ring_buffer_size_t PaUtil_GetRingBufferWriteAvailable(const PaUtilRingBuffer* rbuf);
+ring_buffer_size_t PaUtil_GetRingBufferReadAvailable(const PaUtilRingBuffer* rbuf);
+ring_buffer_size_t PaUtil_WriteRingBuffer(PaUtilRingBuffer* rbuf, const void* data, ring_buffer_size_t elementCount);
+ring_buffer_size_t PaUtil_ReadRingBuffer(PaUtilRingBuffer* rbuf, void* data, ring_buffer_size_t elementCount);
+ring_buffer_size_t PaUtil_GetRingBufferWriteRegions(PaUtilRingBuffer* rbuf, ring_buffer_size_t elementCount, void** dataPtr1, ring_buffer_size_t* sizePtr1, void** dataPtr2, ring_buffer_size_t* sizePtr2);
+ring_buffer_size_t PaUtil_AdvanceRingBufferWriteIndex(PaUtilRingBuffer* rbuf, ring_buffer_size_t elementCount);
+ring_buffer_size_t PaUtil_GetRingBufferReadRegions(PaUtilRingBuffer* rbuf, ring_buffer_size_t elementCount, void** dataPtr1, ring_buffer_size_t* sizePtr1, void** dataPtr2, ring_buffer_size_t* sizePtr2);
+ring_buffer_size_t PaUtil_AdvanceRingBufferReadIndex(PaUtilRingBuffer* rbuf, ring_buffer_size_t elementCount);
+/* End of pa_ringbuffer.h declarations. */
+""" % locals()
+
+
+def init(ffi, lib):
+    """Return RingBuffer class using the given CFFI instance."""
+
+    class RingBuffer(_RingBufferBase):
+        _ffi = ffi
+        _lib = lib
+
+    return RingBuffer
+
+
+class _RingBufferBase(object):
     """Wrapper for PortAudio's ring buffer.
 
     See __init__().
@@ -24,9 +67,9 @@ def __init__(self, elementsize, size):
             The number of elements in the buffer (must be a power of 2).
 
         """
-        self._ptr = _ffi.new('PaUtilRingBuffer*')
-        self._data = _ffi.new('unsigned char[]', size * elementsize)
-        res = _lib.PaUtil_InitializeRingBuffer(
+        self._ptr = self._ffi.new('PaUtilRingBuffer*')
+        self._data = self._ffi.new('unsigned char[]', size * elementsize)
+        res = self._lib.PaUtil_InitializeRingBuffer(
             self._ptr, elementsize, size, self._data)
         if res != 0:
             assert res == -1
@@ -40,17 +83,17 @@ def flush(self):
         Should only be called when buffer is NOT being read or written.
 
         """
-        _lib.PaUtil_FlushRingBuffer(self._ptr)
+        self._lib.PaUtil_FlushRingBuffer(self._ptr)
 
     @property
     def write_available(self):
         """Number of elements available in the ring buffer for writing."""
-        return _lib.PaUtil_GetRingBufferWriteAvailable(self._ptr)
+        return self._lib.PaUtil_GetRingBufferWriteAvailable(self._ptr)
 
     @property
     def read_available(self):
         """Number of elements available in the ring buffer for reading."""
-        return _lib.PaUtil_GetRingBufferReadAvailable(self._ptr)
+        return self._lib.PaUtil_GetRingBufferReadAvailable(self._ptr)
 
     def write(self, data, size=-1):
         """Write data to the ring buffer.
@@ -69,14 +112,15 @@ def write(self, data, size=-1):
 
         """
         try:
-            data = _ffi.from_buffer(data)
+            data = self._ffi.from_buffer(data)
         except TypeError:
             pass  # input is not a buffer
         if size < 0:
-            size, rest = divmod(_ffi.sizeof(data), self._ptr.elementSizeBytes)
+            size, rest = divmod(self._ffi.sizeof(data),
+                                self._ptr.elementSizeBytes)
             if rest:
                 raise ValueError('data size must be multiple of elementsize')
-        return _lib.PaUtil_WriteRingBuffer(self._ptr, data, size)
+        return self._lib.PaUtil_WriteRingBuffer(self._ptr, data, size)
 
     def read(self, data, size=-1):
         """Read data from the ring buffer.
@@ -95,14 +139,15 @@ def read(self, data, size=-1):
 
         """
         try:
-            data = _ffi.from_buffer(data)
+            data = self._ffi.from_buffer(data)
         except TypeError:
             pass  # input is not a buffer
         if size < 0:
-            size, rest = divmod(_ffi.sizeof(data), self._ptr.elementSizeBytes)
+            size, rest = divmod(self._ffi.sizeof(data),
+                                self._ptr.elementSizeBytes)
             if rest:
                 raise ValueError('data size must be multiple of elementsize')
-        return _lib.PaUtil_ReadRingBuffer(self._ptr, data, size)
+        return self._lib.PaUtil_ReadRingBuffer(self._ptr, data, size)
 
     def get_write_buffers(self, size):
         """Get buffer(s) to which we can write data.
@@ -123,14 +168,14 @@ def get_write_buffers(self, size):
             The second buffer.
 
         """
-        ptr1 = _ffi.new('void**')
-        ptr2 = _ffi.new('void**')
-        size1 = _ffi.new('ring_buffer_size_t*')
-        size2 = _ffi.new('ring_buffer_size_t*')
-        return (_lib.PaUtil_GetRingBufferWriteRegions(
+        ptr1 = self._ffi.new('void**')
+        ptr2 = self._ffi.new('void**')
+        size1 = self._ffi.new('ring_buffer_size_t*')
+        size2 = self._ffi.new('ring_buffer_size_t*')
+        return (self._lib.PaUtil_GetRingBufferWriteRegions(
                     self._ptr, size, ptr1, size1, ptr2, size2),
-                _ffi.buffer(ptr1[0], size1[0] * self.elementsize),
-                _ffi.buffer(ptr2[0], size2[0] * self.elementsize))
+                self._ffi.buffer(ptr1[0], size1[0] * self.elementsize),
+                self._ffi.buffer(ptr2[0], size2[0] * self.elementsize))
 
     def advance_write_index(self, size):
         """Advance the write index to the next location to be written.
@@ -146,7 +191,7 @@ def advance_write_index(self, size):
             The new position.
 
         """
-        return _lib.PaUtil_AdvanceRingBufferWriteIndex(self._ptr, size)
+        return self._lib.PaUtil_AdvanceRingBufferWriteIndex(self._ptr, size)
 
     def get_read_buffers(self, size):
         """Get buffer(s) from which we can read data.
@@ -166,14 +211,14 @@ def get_read_buffers(self, size):
             The second buffer.
 
         """
-        ptr1 = _ffi.new('void**')
-        ptr2 = _ffi.new('void**')
-        size1 = _ffi.new('ring_buffer_size_t*')
-        size2 = _ffi.new('ring_buffer_size_t*')
-        return (_lib.PaUtil_GetRingBufferReadRegions(
+        ptr1 = self._ffi.new('void**')
+        ptr2 = self._ffi.new('void**')
+        size1 = self._ffi.new('ring_buffer_size_t*')
+        size2 = self._ffi.new('ring_buffer_size_t*')
+        return (self._lib.PaUtil_GetRingBufferReadRegions(
                     self._ptr, size, ptr1, size1, ptr2, size2),
-                _ffi.buffer(ptr1[0], size1[0] * self.elementsize),
-                _ffi.buffer(ptr2[0], size2[0] * self.elementsize))
+                self._ffi.buffer(ptr1[0], size1[0] * self.elementsize),
+                self._ffi.buffer(ptr2[0], size2[0] * self.elementsize))
 
     def advance_read_index(self, size):
         """Advance the read index to the next location to be read.
@@ -189,7 +234,7 @@ def advance_read_index(self, size):
             The new position.
 
         """
-        return _lib.PaUtil_AdvanceRingBufferReadIndex(self._ptr, size)
+        return self._lib.PaUtil_AdvanceRingBufferReadIndex(self._ptr, size)
 
     @property
     def elementsize(self):