GNU Radio Manual and C++ API Reference  3.10.9.1
The Free & Open Software Radio Ecosystem
throttle.h
Go to the documentation of this file.
1 /* -*- c++ -*- */
2 /*
3  * Copyright 2005-2011,2013 Free Software Foundation, Inc.
4  * Copyright 2021,2022 Marcus Müller
5  *
6  * This file is part of GNU Radio
7  *
8  * SPDX-License-Identifier: GPL-3.0-or-later
9  *
10  */
11 
12 #ifndef INCLUDED_GR_THROTTLE_H
13 #define INCLUDED_GR_THROTTLE_H
14 
15 #include <gnuradio/blocks/api.h>
16 #include <gnuradio/sync_block.h>
17 
18 namespace gr {
19 namespace blocks {
20 
21 /*!
22  * \brief throttle flow of samples such that the average rate does
23  * not exceed samples_per_sec.
24  * \ingroup misc_blk
25  *
26  * \details
27  * input: one stream of itemsize; output: one stream of itemsize
28  *
29  * N.B. this should only be used in GUI apps where there is no
30  * other rate limiting block. It is not intended nor effective at
31  * precisely controlling the rate of samples. That should be
32  * controlled by a source or sink tied to sample clock. E.g., a
33  * USRP or audio card.
34  *
35  * You can insert this block "in series" with your sample flow, in which case it does a
36  * throttled copy of input to output. Alternatively, you can not connect its output and
37  * just connect this block's input in parallel to an existing block in your flow graph. In
38  * that case, Throttle will limit the rate at which samples are consumed; especially at
39  * higher rates, where the copying overhead might be significant, this is functionally not
40  * different to copying at a limited rate.
41  */
42 class BLOCKS_API throttle : virtual public sync_block
43 {
44 public:
45  typedef std::shared_ptr<throttle> sptr;
46 
47  /*!
48  * Make a sptr to a Throttle block
49  *
50  * \param itemsize Size of each item, e.g. 8 for gr_complex
51  *
52  * \param samples_per_sec Number of items to be passed per second. Waiting time is
53  * calculated based on this.
54  *
55  * \param ignore_tags Whether or not to react to "rx_rate" tags with a double value
56  * specifying a new rate.
57  *
58  * \param maximum_items_per_chunk Limit the amount of items that are produced/consumed
59  * between waiting. Set to 0 (or leave at default) to always wait for the full
60  * duration dictated by the current size of workload items, divided by the
61  * samples_per_sec.
62  */
63  static sptr make(size_t itemsize,
64  double samples_per_sec,
65  bool ignore_tags = true,
66  unsigned int maximum_items_per_chunk = 0);
67 
68  //! Sets the sample rate in samples per second.
69  virtual void set_sample_rate(double rate) = 0;
70 
71  //! Get the sample rate in samples per second.
72  virtual double sample_rate() const = 0;
73 
74  //! Set the maximum items that will be produced per waiting period
75  virtual void set_maximum_items_per_chunk(unsigned int maximum_items_per_chunk) = 0;
76 
77  //! Get the maximum items that will be produced per waiting period
78  virtual unsigned int maximum_items_per_chunk() const = 0;
79 };
80 
81 } /* namespace blocks */
82 } /* namespace gr */
83 
84 #endif /* INCLUDED_GR_THROTTLE_H */
throttle flow of samples such that the average rate does not exceed samples_per_sec.
Definition: throttle.h:43
virtual void set_maximum_items_per_chunk(unsigned int maximum_items_per_chunk)=0
Set the maximum items that will be produced per waiting period.
virtual double sample_rate() const =0
Get the sample rate in samples per second.
virtual void set_sample_rate(double rate)=0
Sets the sample rate in samples per second.
virtual unsigned int maximum_items_per_chunk() const =0
Get the maximum items that will be produced per waiting period.
std::shared_ptr< throttle > sptr
Definition: throttle.h:45
static sptr make(size_t itemsize, double samples_per_sec, bool ignore_tags=true, unsigned int maximum_items_per_chunk=0)
synchronous 1:1 input to output with history
Definition: sync_block.h:26
#define BLOCKS_API
Definition: gr-blocks/include/gnuradio/blocks/api.h:18
GR_RUNTIME_API size_t itemsize(types::vector_type type)
GNU Radio logging wrapper.
Definition: basic_block.h:29