uhd::rx_streamer Class Reference

#include <uhd/stream.hpp>

Inheritance diagram for uhd::rx_streamer:

Public Types
typedef std::shared_ptr< rx_streamer >	sptr
typedef ref_vector< void * >	buffs_type
	Typedef for a pointer to a single, or a collection of recv buffers. More...

Public Member Functions
virtual	~rx_streamer (void)
virtual size_t	get_num_channels (void) const =0
	Get the number of channels associated with this streamer. More...
virtual size_t	get_max_num_samps (void) const =0
	Get the max number of samples per buffer per packet. More...
virtual size_t	recv (const buffs_type &buffs, const size_t nsamps_per_buff, rx_metadata_t &metadata, const double timeout=0.1, const bool one_packet=false)=0
virtual void	issue_stream_cmd (const stream_cmd_t &stream_cmd)=0

Detailed Description

The RX streamer is the host interface to receiving samples. It represents the layer between the samples on the host and samples inside the device's receive DSP processing.

Member Typedef Documentation

buffs_type

typedef ref_vector<void*> uhd::rx_streamer::buffs_type

Typedef for a pointer to a single, or a collection of recv buffers.

sptr

typedef std::shared_ptr<rx_streamer> uhd::rx_streamer::sptr

Constructor & Destructor Documentation

~rx_streamer()

virtual uhd::rx_streamer::~rx_streamer ( void  )

virtual

Member Function Documentation

get_max_num_samps()

virtual size_t uhd::rx_streamer::get_max_num_samps ( void  ) const

pure virtual

Get the max number of samples per buffer per packet.

get_num_channels()

virtual size_t uhd::rx_streamer::get_num_channels ( void  ) const

pure virtual

Get the number of channels associated with this streamer.

issue_stream_cmd()

virtual void uhd::rx_streamer::issue_stream_cmd ( const stream_cmd_t &  stream_cmd )

pure virtual

Issue a stream command to the usrp device. This tells the usrp to send samples into the host. See the documentation for stream_cmd_t for more info.

With multiple devices, the first stream command in a chain of commands should have a time spec in the near future and stream_now = false; to ensure that the packets can be aligned by their time specs.

Parameters

stream_cmd

the stream command to issue

recv()

virtual size_t uhd::rx_streamer::recv ( const buffs_type &  buffs, const size_t  nsamps_per_buff, rx_metadata_t &  metadata, const double  timeout = 0.1, const bool  one_packet = false  )

pure virtual

Receive buffers containing samples described by the metadata.

Receive handles fragmentation as follows: If the buffer has insufficient space to hold all samples that were received in a single packet over-the-wire, then the buffer will be completely filled and the implementation will hold a pointer into the remaining portion of the packet. Subsequent calls will load from the remainder of the packet, and will flag the metadata to show that this is a fragment. The next call to receive, after the remainder becomes exhausted, will perform an over-the-wire receive as usual. See the rx metadata fragment flags and offset fields for details.

This is a blocking call and will not return until the number of samples returned have been written into each buffer. Under a timeout condition, the number of samples returned may be less than the number of samples specified.

The one_packet option allows the user to guarantee that the call will return after a single packet has been processed. This may be useful to maintain packet boundaries in some cases.

Note on threading: recv() is not thread-safe, to avoid locking overhead. The application calling recv() is responsible for making sure that not more than one thread can call recv() on the same streamer at the same time. If there are multiple streamers, receiving from different sources, then those may be called from different threads simultaneously.

Error Handling

metadata is a value that is set inside this function (effectively, a return value), and should be checked for potential error codes (see rx_metadata_t::error_code_t).

The most common error code when something goes wrong is an overrun (also referred to as overflow: error_code_t::ERROR_CODE_OVERFLOW). This error code means that the device produced data faster than the application could read, and various buffers filled up leaving no more space for the device to write data to. Note that an overrun on the device will not immediatiely show up when calling recv(). Depending on the device implementation, there may be many more valid samples available before the device had to stop writing samples to the FIFO. Only when all valid samples are returned to the call site will the error code be set to "overrun". When this happens, all valid samples have been returned to application where recv() was called. If the device is streaming continuously, it will reset itself when the FIFO is cleared, and recv() can be called again to retrieve new, valid data.

Parameters

	buffs	a vector of writable memory to fill with samples
	nsamps_per_buff	the size of each buffer in number of samples
[out]	metadata	data to fill describing the buffer
	timeout	the timeout in seconds to wait for a packet
	one_packet	return after the first packet is received

Returns

the number of samples received or 0 on error

---

The documentation for this class was generated from the following file:

• stream.hpp