*.pyx: Add some rather laconic docstrings.

[mLib-python] / selpk.pyx

### -*-pyrex-*-
###
### Selecting packet-buffer
###
### (c) 2005 Straylight/Edgeware
###

###----- Licensing notice ---------------------------------------------------
###
### This file is part of the Python interface to mLib.
###
### mLib/Python 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.
###
### mLib/Python 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 mLib/Python; if not, write to the Free Software Foundation,
### Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

cdef class SelPacketBuffer:
  """
  SelPacketBuffer(FILE, [packetproc = None], [eofproc = None])

  Split an incoming stream into packets.
  """
  cdef selpk p
  cdef _packet
  cdef _eof
  def __cinit__(me, fd, packetproc = None, eofproc = None, *hunoz, **hukairz):
    selpk_init(&me.p, &_sel, _getfd(fd), _selpkfunc, <void *>me)
    selpk_disable(&me.p)
    me._packet = _checkcallable(packetproc, 'packet proc')
    me._eof = _checkcallable(eofproc, 'eof proc')
  def __dealloc__(me):
    selpk_destroy(&me.p)
  property activep:
    """SPK.activep -> BOOL: is the buffer still active?"""
    def __get__(me):
      return _to_bool(me.p.pk.f & PKBUF_ENABLE)
  property fd:
    """SPK.fd -> INT: the file descriptor"""
    def __get__(me):
      return me.p.reader.fd
  property want:
    """SPK.want -> INT: size of next packet to return"""
    def __get__(me):
      return me.p.pk.want
    def __set__(me, n):
      if n <= 0:
        raise TypeError, 'size must be positive'
      selpk_want(&me.p, n)
  property packetproc:
    """SPK.packetproc -> FUNC: call FUNC(PACKET) on each packet"""
    def __get__(me):
      return me._packet
    def __set__(me, proc):
      me._packet = _checkcallable(proc, 'packet proc')
    def __del__(me):
      me._packet = None
  property eofproc:
    """SPK.eofproc -> FUNC: call FUNC() at end-of-file"""
    def __get__(me):
      return me._eof
    def __set__(me, proc):
      me._eof = _checkcallable(proc, 'eof proc')
    def __del__(me):
      me._eof = None
  def enable(me):
    """SPK.enable(): enable the buffer, allowing packets to be emitted"""
    if me.p.pk.f & PKBUF_ENABLE:
      raise ValueError, 'already enabled'
    selpk_enable(&me.p)
    me.enabled()
    return me
  def disable(me):
    """SPK.disable(): disable the buffer, suspending packet emission"""
    if not (me.p.pk.f & PKBUF_ENABLE):
      raise ValueError, 'already disabled'
    selpk_disable(&me.p)
    me.disabled()
    return me
  def enabled(me):
    """SPK.enabled(): called when buffer is enabled"""
    pass
  def disabled(me):
    """SPK.disabled(): called when buffer is disabled"""
    pass
  def packet(me, pk):
    """SPK.packet(PACKET): called for each completed packet"""
    return _maybecall(me._packet, (pk,))
  def eof(me):
    """SPK.eof(): called at end-of-file"""
    return _maybecall(me._eof, ())

cdef void _selpkfunc(unsigned char *p, size_t n, pkbuf *pk,
                     size_t *keep, void *arg):
  cdef SelPacketBuffer pb
  cdef void *rp
  cdef Py_ssize_t rn
  pb = <SelPacketBuffer>arg
  if p is NULL:
    pb.eof()
  else:
    r = pb.packet(PyString_FromStringAndSize(<char *>p, n))
    if r is not None:
      PyObject_AsReadBuffer(r, <cvp *>&rp, &rn)
      if rn > n:
        raise ValueError, 'remaining buffer too large'
      if rn:
        memcpy(p + n - rn, rp, rn)
        keep[0] = rn

###----- That's all, folks --------------------------------------------------