hls::stream.size() Method - 2023.2 English

Vitis High-Level Synthesis User Guide (UG1399)

Document ID
Release Date
2023.2 English

The hls::stream.size() method returns an unsigned integer specifying the current number of elements the stream is holding. This lets you check if there is data or how much data is in the channel prior to reading to prevent stalls or deadlocks.

Note: hls::stream.size() can be used to check if an input FIFO is full, and an output FIFO is empty. While hls::stream.empty() can only be applied to an input FIFO and hls::stream.full() to an output FIFO.
hls::stream<int> my_stream;
var = 16;

if (my_stream.size()>0) {

The hls::stream.size() and hls::stream.capacity() methods enable advanced flow control to write or read the stream only when there is specific amounts of space or data available for the transaction. For example, before starting a read burst of size N, you can check if there are N data items in the input stream so that the burst can complete without stalling. For write bursts you can also check if there is enough space available in an output stream to store the burst data without stalling.

if (instream.size() > N) 
  for(i=0, i<N; i++)
    ... = instream.read(); // will not block

To read only when the stream is full:

if (instream.size() == instream.capacity())
  ... = instream.read(); // read only if full
Tip: You cannot use hls::stream.full() to check for this condition. The following will not work:
if (instream.full())
  ... = instream.read();