Api documentation

Python bindings to the PSR Dada library.

This package provides a minimal interface to the PSRDada library. Exported are the Reader and Writer classes to connect with psrdada ring buffers.

Ringbuffers are used to process large data streams, in our case data generated by radio telescopes. A writer and (mulitple) readers can connect to the buffer and read, process, and write data with a minimum of data copies. This library exposes the ringbuffer as a Cython memory view, which you can then interact with via fi. numpy.

Use cases are:

  • rapid prototyping

  • a glue layer to run CUDA kernels

  • interactive use of the telescope

Ringbuffer

class psrdada.Ringbuffer
isConnected

Boolean; indicates if the Ringbuffer instance is connected to a running dada_db.

isHoldingPage

Boolean; indicates if the Ringbuffer instance is currently holding a page; ie. has exclusive write access to it for Writers, or is preventing it from being rewritten for Readers.

isEndOfData

Boolean; indicates if the EOD flag has been set on the Ringbuffer. Used to implement iterators for the Reader and Writer classes.

header

dict; contains a copy of the last read header. For Readers, the original un-parsed header is available under the __RAW_HEADER__ key.

Reader

class psrdada.Reader

Bases: psrdada.ringbuffer.Ringbuffer

Reader class.

Implements reading header and data from a running PSRDada ringbuffer.

connect()

Connect to a PSRDada ringbuffer with the specified key, and lock it for reading.

Parameters

key – Identifier of the ringbuffer, typically 0xdada

disconnect()

Disconnect from the PSRDada ringbuffer

getHeader()

Read a header from the ringbuffer and return it as a dict.

We reimplement the parsing logic from the PSRDada code:

  • A page is read from the PSRDada header block, and parsed line by line. The page must contain ASCII text.

  • Each line (separated by newlines or backslashes) contains a key-value pair (separated by tabs or spaces).

The original header is also added to the dict using the special key __RAW_HEADER__ The read is blocking; it will wait for a header page to become available. If EndOfData has been set on the buffer, it is cleared and the buffer is reset.

Note

The last-read header is available as reader.header.

Returns

A dict

getNextPage()

Return a memoryview on the next available ringbuffer page. Use data = np.asarray(page) to convert it to something more useable.

The read is blocking; it will wait for a page to become available.

Note

The view is readonly, and a direct mapping of the ringbuffer page. So, no memory copies, and no garbage collector.

Returns

a PyMemoryView

markCleared()

Release a page back to the ringbuffer.

Mark the current page as cleared, so it can be reused by the ringbuffer. This is called automatically when iterating over the ringbuffer.

Writer

class psrdada.Writer

Bases: psrdada.ringbuffer.Ringbuffer

Writer class.

Implements writing header and data to a running PSRDada ringbuffer.

connect()

Connect to a PSR DADA ringbuffer with the specified key, and lock it for writing

Parameters

key – Identifier of the ringbuffer, typically 0xdada

disconnect()

Disconnect from PSRDada ringbuffer

getNextPage()

Return a memoryview on the next available ringbuffer page.

The call is blocking; it will wait for a page to become available. Use data = np.asarray(page) to convert it to something more useable.

Note

The view is a direct mapping of the ringbuffer page. So, no memory copies, and no garbage collector.

Returns

a PyMemoryView

markEndOfData()

Set the EOD (end-of-data) flag, and mark the page as filled.

Note

This will also raise a StopIteration exception when using iterators.

See also

markFilled

markFilled()

Release a page back to the ringbuffer.

Mark the current page as filled and and return it to the ringbuffer. This is called automatically when iterating over the ringbuffer.

See also

markEndOfData

setHeader()

Write a dict to a ringbuffer header page.

We reimplement the parsing logic from the PSRDada code:

  • Each key-value pair in the dict is formatted as an ASCII string, using a ‘ ‘ as separator;

  • All strings are concattenated (with an additional newline) and written to the header page.

The write is blocking; it will wait for a header page to become available. If EndOfData has been set on the buffer, it is cleared and the buffer is reset.

Note

The last-written header is available as writer.header.

Returns

A dict

Viewer

class psrdada.Viewer

Bases: psrdada.ringbuffer.Ringbuffer

Viewer class.

Implements monitoring buffer statistics from a running PSRDada ringbuffer.

connect()

Passively connect to a PSRDada ring buffer with the specified key

Parameters

key – Hex identifier of the ring buffer

getbufstats()

Get monitoring statistics. This subroutine is based on psrdada’s dada_dbmonitor

This call can be made in a loop for consistent monitoring

Note

Every dict returned by this function has 5 keys:

  • FREE: Current number of free header/data buffers

  • FULL: Current number of full header/data buffers

  • CLEAR: Current number of header/data buffers cleared for writing

  • NWRITE: Total number of header/data pages that have been written

  • NREAD: Total number of header/data pages that have been read

Returns

2-element tuple containing:

  • A dict for header buffer statistics

  • A list of dict for data buffer statistics. The list is for every reader connected to the ringbuffer