GNU Radio C++ API Reference  g90d26cb
The Free & Open Software Radio Ecosystem
gnuradio-runtime/include/gnuradio/block.h
Go to the documentation of this file.
1 /* -*- c++ -*- */
2 /*
3  * Copyright 2004,2007,2009,2010,2013,2017 Free Software Foundation, Inc.
4  *
5  * This file is part of GNU Radio
6  *
7  * SPDX-License-Identifier: GPL-3.0-or-later
8  *
9  */
10 
11 #ifndef INCLUDED_GR_RUNTIME_BLOCK_H
12 #define INCLUDED_GR_RUNTIME_BLOCK_H
13 
14 #include <cstdint>
15 #include <memory>
16 #include <optional>
17 
18 #include <gnuradio/api.h>
19 #include <gnuradio/basic_block.h>
20 #include <gnuradio/buffer_type.h>
21 #include <gnuradio/config.h>
22 #include <gnuradio/logger.h>
23 #include <gnuradio/tags.h>
24 #ifdef GR_MPLIB_MPIR
25 #include <mpirxx.h>
26 #else
27 #include <gmpxx.h>
28 #endif
29 
30 namespace gr {
31 
32 /*!
33  * \brief The abstract base class for all 'terminal' processing blocks.
34  * \ingroup base_blk
35  *
36  * A signal processing flow is constructed by creating a tree of
37  * hierarchical blocks, which at any level may also contain terminal
38  * nodes that actually implement signal processing functions. This
39  * is the base class for all such leaf nodes.
40  *
41  * Blocks have a set of input streams and output streams. The
42  * input_signature and output_signature define the number of input
43  * streams and output streams respectively, and the type of the data
44  * items in each stream.
45  *
46  * Blocks report the number of items consumed on each input in
47  * general_work(), using consume() or consume_each().
48  *
49  * If the same number of items is produced on each output, the block
50  * returns that number from general_work(). Otherwise, the block
51  * calls produce() for each output, then returns
52  * WORK_CALLED_PRODUCE. The input and output rates are not required
53  * to be related.
54  *
55  * User derived blocks override two methods, forecast and
56  * general_work, to implement their signal processing
57  * behavior. forecast is called by the system scheduler to determine
58  * how many items are required on each input stream in order to
59  * produce a given number of output items.
60  *
61  * general_work is called to perform the signal processing in the
62  * block. It reads the input items and writes the output items.
63  */
65 {
66 public:
67  //! Magic return values from general_work
68  enum work_return_t { WORK_CALLED_PRODUCE = -2, WORK_DONE = -1 };
69 
70  /*!
71  * \brief enum to represent different tag propagation policies.
72  */
74  TPP_DONT = 0, /*!< Scheduler doesn't propagate tags from in- to output. The block
75  itself is free to insert tags as it wants. */
76  TPP_ALL_TO_ALL = 1, /*!< Propagate tags from all in- to all outputs. The scheduler
77  takes care of that. */
78  TPP_ONE_TO_ONE = 2, /*!< Propagate tags from n. input to n. output. Requires same
79  number of in- and outputs */
80  TPP_CUSTOM = 3, /*!< Like TPP_DONT, but signals the block it should implement
81  application-specific forwarding behaviour. */
82  TPP_TSB = 4 /*!< like TPP_ALL_TO_ALL, but specific to tagged stream blocks. If
83  your TSB needs to control its own tag copying, use
84  set_tag_propagation_policy(TPP_CUSTOM) or TPP_DONT. */
85  };
86 
87  ~block() override;
88 
89  /*!
90  * Assume block computes y_i = f(x_i, x_i-1, x_i-2, x_i-3...)
91  * History is the number of x_i's that are examined to produce one y_i.
92  * This comes in handy for FIR filters, where we use history to
93  * ensure that our input contains the appropriate "history" for the
94  * filter. History should be equal to the number of filter taps. First
95  * history samples (when there are no previous samples) are
96  * initialized with zeroes.
97  */
98  unsigned history() const;
99  void set_history(unsigned history);
100 
101  /*!
102  * Declares the block's delay in samples. Since the delay of
103  * blocks like filters is derived from the taps and not the block
104  * itself, we cannot automatically calculate this value and so
105  * leave it as a user-defined property. It defaults to 0 is not
106  * set.
107  *
108  * This does not actively set the delay; it just tells the
109  * scheduler what the delay is.
110  *
111  * This delay is mostly used to adjust the placement of the tags
112  * and is not currently used for any signal processing. When a tag
113  * is passed through a block with internal delay, its location
114  * should be moved based on the delay of the block. This interface
115  * allows us to tell the scheduler this value.
116  *
117  * \param which The buffer on which to set the delay.
118  * \param delay The sample delay of the data stream.
119  */
120  void declare_sample_delay(int which, unsigned delay);
121 
122  /*!
123  * Convenience wrapper to gr::block::declare_delay(int which, unsigned delay)
124  * to set all ports to the same delay.
125  */
126  void declare_sample_delay(unsigned delay);
127 
128  /*!
129  * Gets the delay of the block. Since the delay of blocks like
130  * filters is derived from the taps and not the block itself, we
131  * cannot automatically calculate this value and so leave it as a
132  * user-defined property. It defaults to 0 is not set.
133  *
134  * \param which Which port from which to get the sample delay.
135  */
136  unsigned sample_delay(int which) const;
137 
138  /*!
139  * \brief Return true if this block has a fixed input to output rate.
140  *
141  * If true, then fixed_rate_in_to_out and fixed_rate_out_to_in may be called.
142  */
143  bool fixed_rate() const { return d_fixed_rate; }
144 
145  // ----------------------------------------------------------------
146  // override these to define your behavior
147  // ----------------------------------------------------------------
148 
149  /*!
150  * \brief Estimate input requirements given output request
151  *
152  * \param noutput_items number of output items to produce
153  * \param ninput_items_required number of input items required on each input stream
154  *
155  * Given a request to product \p noutput_items, estimate the
156  * number of data items required on each input stream. The
157  * estimate doesn't have to be exact, but should be close.
158  */
159  virtual void forecast(int noutput_items, gr_vector_int& ninput_items_required);
160 
161  /*!
162  * \brief compute output items from input items
163  *
164  * \param noutput_items number of output items to write on each output stream
165  * \param ninput_items number of input items available on each input stream
166  * \param input_items vector of pointers to the input items, one entry per input
167  * stream
168  * \param output_items vector of pointers to the output items, one entry per
169  * output stream
170  *
171  * \returns number of items actually written to each output stream
172  * or WORK_CALLED_PRODUCE or WORK_DONE. It is OK to return a
173  * value less than noutput_items.
174  *
175  * WORK_CALLED_PRODUCE is used where not all outputs produce the
176  * same number of items. general_work must call produce() for each
177  * output to indicate the number of items actually produced.
178  *
179  * WORK_DONE indicates that no more data will be produced by this block.
180  *
181  * general_work must call consume or consume_each to indicate how
182  * many items were consumed on each input stream.
183  */
184  virtual int general_work(int noutput_items,
185  gr_vector_int& ninput_items,
186  gr_vector_const_void_star& input_items,
187  gr_vector_void_star& output_items);
188 
189  /*!
190  * \brief Called to enable drivers, etc for i/o devices.
191  *
192  * This allows a block to enable an associated driver to begin
193  * transferring data just before we start to execute the scheduler.
194  * The end result is that this reduces latency in the pipeline
195  * when dealing with audio devices, usrps, etc.
196  */
197  virtual bool start();
198 
199  /*!
200  * \brief Called to disable drivers, etc for i/o devices.
201  */
202  virtual bool stop();
203 
204  // ----------------------------------------------------------------
205 
206  /*!
207  * \brief Constrain the noutput_items argument passed to forecast and general_work
208  *
209  * set_output_multiple causes the scheduler to ensure that the
210  * noutput_items argument passed to forecast and general_work will
211  * be an integer multiple of \param multiple The default value of
212  * output multiple is 1.
213  */
214  void set_output_multiple(int multiple);
215  int output_multiple() const { return d_output_multiple; }
216  bool output_multiple_set() const { return d_output_multiple_set; }
217 
218  /*!
219  * \brief Constrains buffers to work on a set item alignment (for SIMD)
220  *
221  * set_alignment_multiple causes the scheduler to ensure that the
222  * noutput_items argument passed to forecast and general_work will
223  * be an integer multiple of \param multiple The default value is
224  * 1.
225  *
226  * This control is similar to the output_multiple setting, except
227  * that if the number of items passed to the block is less than
228  * the output_multiple, this value is ignored and the block can
229  * produce like normal. The d_unaligned value is set to the number
230  * of items the block is off by. In the next call to general_work,
231  * the noutput_items is set to d_unaligned or less until
232  * d_unaligned==0. The buffers are now aligned again and the
233  * aligned calls can be performed again.
234  */
235  void set_alignment(int multiple);
236  int alignment() const { return d_output_multiple; }
237 
238  void set_unaligned(int na);
239  int unaligned() const { return d_unaligned; }
240  void set_is_unaligned(bool u);
241  bool is_unaligned() const { return d_is_unaligned; }
242 
243  /*!
244  * \brief Tell the scheduler \p how_many_items of input stream \p
245  * which_input were consumed.
246  *
247  * This function should be used in general_work() to tell the scheduler the
248  * number of input items processed. Calling consume() multiple times in the
249  * same general_work() call is safe. Every invocation of consume() updates
250  * the values returned by nitems_read().
251  */
252  void consume(int which_input, int how_many_items);
253 
254  /*!
255  * \brief Tell the scheduler \p how_many_items were consumed on
256  * each input stream.
257  *
258  * Also see notes on consume().
259  */
260  void consume_each(int how_many_items);
261 
262  /*!
263  * \brief Tell the scheduler \p how_many_items were produced on
264  * output stream \p which_output.
265  *
266  * This function should be used in general_work() to tell the scheduler the
267  * number of output items produced. If produce() is called in
268  * general_work(), general_work() must return \p WORK_CALLED_PRODUCE.
269  * Calling produce() multiple times in the same general_work() call is safe.
270  * Every invocation of produce() updates the values returned by
271  * nitems_written().
272  */
273  void produce(int which_output, int how_many_items);
274 
275  /*!
276  * \brief Set the approximate output rate / input rate
277  *
278  * Provide a hint to the buffer allocator and scheduler.
279  * The default relative_rate is 1.0
280  *
281  * decimators have relative_rates < 1.0
282  * interpolators have relative_rates > 1.0
283  */
284  void set_relative_rate(double relative_rate);
285 
286  /*!
287  * \brief Set the approximate output rate / input rate
288  * using its reciprocal
289  *
290  * This is a convenience function to avoid
291  * numerical problems with tag propagation that calling
292  * set_relative_rate(1.0/relative_rate) might introduce.
293  */
294  void set_inverse_relative_rate(double inverse_relative_rate);
295 
296  /*!
297  * \brief Set the approximate output rate / input rate as an integer ratio
298  *
299  * Provide a hint to the buffer allocator and scheduler.
300  * The default relative_rate is interpolation / decimation = 1 / 1
301  *
302  * decimators have relative_rates < 1.0
303  * interpolators have relative_rates > 1.0
304  */
305  void set_relative_rate(uint64_t interpolation, uint64_t decimation);
306 
307  /*!
308  * \brief return the approximate output rate / input rate
309  */
310  double relative_rate() const { return d_relative_rate; }
311 
312  /*!
313  * \brief return the numerator, or interpolation rate, of the
314  * approximate output rate / input rate
315  */
316  uint64_t relative_rate_i() const
317  {
318  return (uint64_t)d_mp_relative_rate.get_num().get_ui();
319  }
320 
321  /*!
322  * \brief return the denominator, or decimation rate, of the
323  * approximate output rate / input rate
324  */
325  uint64_t relative_rate_d() const
326  {
327  return (uint64_t)d_mp_relative_rate.get_den().get_ui();
328  }
329 
330  /*!
331  * \brief return a reference to the multiple precision rational
332  * representation of the approximate output rate / input rate
333  */
334  mpq_class& mp_relative_rate() { return d_mp_relative_rate; }
335 
336  /*
337  * The following two methods provide special case info to the
338  * scheduler in the event that a block has a fixed input to output
339  * ratio. sync_block, sync_decimator and
340  * sync_interpolator override these. If you're fixed rate,
341  * subclass one of those.
342  */
343  /*!
344  * \brief Given ninput samples, return number of output samples that will be produced.
345  * N.B. this is only defined if fixed_rate returns true.
346  * Generally speaking, you don't need to override this.
347  */
348  virtual int fixed_rate_ninput_to_noutput(int ninput);
349 
350  /*!
351  * \brief Given noutput samples, return number of input samples required to produce
352  * noutput. N.B. this is only defined if fixed_rate returns true. Generally speaking,
353  * you don't need to override this.
354  */
355  virtual int fixed_rate_noutput_to_ninput(int noutput);
356 
357  /*!
358  * \brief Return the number of items read on input stream which_input
359  */
360  uint64_t nitems_read(unsigned int which_input);
361 
362  /*!
363  * \brief Return the number of items written on output stream which_output
364  */
365  uint64_t nitems_written(unsigned int which_output);
366 
367  /*!
368  * \brief Asks for the policy used by the scheduler to moved tags downstream.
369  */
371 
372  /*!
373  * \brief Set the policy by the scheduler to determine how tags are moved downstream.
374  */
376 
377  /*!
378  * \brief Return the minimum number of output items this block can
379  * produce during a call to work.
380  *
381  * Should be 0 for most blocks. Useful if we're dealing with
382  * packets and the block produces one packet per call to work.
383  */
384  int min_noutput_items() const { return d_min_noutput_items; }
385 
386  /*!
387  * \brief Set the minimum number of output items this block can
388  * produce during a call to work.
389  *
390  * \param m the minimum noutput_items this block can produce.
391  */
392  void set_min_noutput_items(int m) { d_min_noutput_items = m; }
393 
394  /*!
395  * \brief Return the maximum number of output items this block will
396  * handle during a call to work.
397  */
399 
400  /*!
401  * \brief Set the maximum number of output items this block will
402  * handle during a call to work.
403  *
404  * \param m the maximum noutput_items this block will handle.
405  */
407 
408  /*!
409  * \brief Clear the switch for using the max_noutput_items value of this block.
410  *
411  * When is_set_max_noutput_items() returns 'true', the scheduler
412  * will use the value returned by max_noutput_items() to limit the
413  * size of the number of items possible for this block's work
414  * function. If is_set_max_notput_items() returns 'false', then
415  * the scheduler ignores the internal value and uses the value set
416  * globally in the top_block.
417  *
418  * Use this value to clear the 'is_set' flag so the scheduler will
419  * ignore this. Use the set_max_noutput_items(m) call to both set
420  * a new value for max_noutput_items and to re-enable its use in
421  * the scheduler.
422  */
424 
425  /*!
426  * \brief Ask the block if the flag is or is not set to use the
427  * internal value of max_noutput_items during a call to work.
428  */
430 
431  /*
432  * Used to expand the vectors that hold the min/max buffer sizes.
433  *
434  * Specifically, when -1 is used, the vectors are just initialized
435  * with 1 value; this is used by the flat_flowgraph to expand when
436  * required to add a new value for new ports on these blocks.
437  */
438  void expand_minmax_buffer(int port);
439 
440  /*!
441  * \brief Returns max buffer size on output port \p i.
442  */
443  long max_output_buffer(size_t i);
444 
445  /*!
446  * \brief Request limit on max buffer size on all output ports.
447  *
448  * \details
449  * This is an advanced feature. Calling this can affect some
450  * fundamental assumptions about the system behavior and
451  * performance.
452  *
453  * The actual buffer size is determined by a number of other
454  * factors from the block and system. This function only provides
455  * a requested maximum. The buffers will always be a multiple of
456  * the system page size, which may be larger than the value asked
457  * for here.
458  *
459  * \param max_output_buffer the requested maximum output size in items.
460  */
461  void set_max_output_buffer(long max_output_buffer);
462 
463  /*!
464  * \brief Request limit on max buffer size on output port \p port.
465  *
466  * \details
467  * This is an advanced feature. Calling this can affect some
468  * fundamental assumptions about the system behavior and
469  * performance.
470  *
471  * The actual buffer size is determined by a number of other
472  * factors from the block and system. This function only provides
473  * a requested maximum. The buffers will always be a multiple of
474  * the system page size, which may be larger than the value asked
475  * for here.
476  *
477  * \param port the output port the request applies to.
478  * \param max_output_buffer the requested maximum output size in items.
479  */
480  void set_max_output_buffer(int port, long max_output_buffer);
481 
482  /*!
483  * \brief Returns min buffer size on output port \p i.
484  */
485  long min_output_buffer(size_t i);
486 
487  /*!
488  * \brief Request limit on the minimum buffer size on all output
489  * ports.
490  *
491  * \details
492  * This is an advanced feature. Calling this can affect some
493  * fundamental assumptions about the system behavior and
494  * performance.
495  *
496  * The actual buffer size is determined by a number of other
497  * factors from the block and system. This function only provides
498  * a requested minimum. The buffers will always be a multiple of
499  * the system page size, which may be larger than the value asked
500  * for here.
501  *
502  * \param min_output_buffer the requested minimum output size in items.
503  */
504  void set_min_output_buffer(long min_output_buffer);
505 
506  /*!
507  * \brief Request limit on min buffer size on output port \p port.
508  *
509  * \details
510  * This is an advanced feature. Calling this can affect some
511  * fundamental assumptions about the system behavior and
512  * performance.
513  *
514  * The actual buffer size is determined by a number of other
515  * factors from the block and system. This function only provides
516  * a requested minimum. The buffers will always be a multiple of
517  * the system page size, which may be larger than the value asked
518  * for here.
519  *
520  * \param port the output port the request applies to.
521  * \param min_output_buffer the requested minimum output size in items.
522  */
523  void set_min_output_buffer(int port, long min_output_buffer);
524 
525  /*!
526  * \brief DEPRECATED Configure the timer set when input is blocked \p port.
527  *
528  * \details
529  * This is an advanced/experimental feature and might be removed in a future
530  * version. Calling this can affect some fundamental assumptions about the
531  * system behavior and
532  * performance.
533  *
534  * In the TPB scheduler, when a block has no work to do because there
535  * is no data at it inputs, it sets a timer and tries again after a
536  * period of time. The default is 250 ms, but this can be configured
537  * differently per block when necessary
538  *
539  * \param timer_value_ms the timer value in milliseconds
540  */
541  void set_blkd_input_timer_value(unsigned int timer_value_ms);
542 
543  /*!
544  * \brief DEPRECATED Returns timer value set when input is blocked
545  */
546  unsigned int blkd_input_timer_value();
547 
548 
549  /*!
550  * \brief Allocate the block_detail and necessary output buffers for this
551  * block.
552  */
553  void allocate_detail(int ninputs,
554  int noutputs,
555  const std::vector<int>& downstream_max_nitems_vec,
556  const std::vector<uint64_t>& downstream_lcm_nitems_vec,
557  const std::vector<uint32_t>& downstream_max_out_mult_vec);
558 
559  // --------------- Custom buffer-related functions -------------
560 
561  /*!
562  * \brief Replace the block's buffer with a new one owned by the block_owner
563  * parameter
564  *
565  * \details
566  * This function is used to replace the buffer on the specified output port
567  * of the block with a new buffer that is "owned" by the specified block. This
568  * function will only be called if a downstream block is using a custom buffer
569  * that is incompatible with the default buffer type created by this block.
570  *
571  */
572  buffer_sptr replace_buffer(size_t src_port, size_t dst_port, block_sptr block_owner);
573 
574  // --------------- Performance counter functions -------------
575 
576  /*!
577  * \brief Gets instantaneous noutput_items performance counter.
578  */
580 
581  /*!
582  * \brief Gets average noutput_items performance counter.
583  */
585 
586  /*!
587  * \brief Gets variance of noutput_items performance counter.
588  */
590 
591  /*!
592  * \brief Gets instantaneous num items produced performance counter.
593  */
594  float pc_nproduced();
595 
596  /*!
597  * \brief Gets average num items produced performance counter.
598  */
600 
601  /*!
602  * \brief Gets variance of num items produced performance counter.
603  */
605 
606  /*!
607  * \brief Gets instantaneous fullness of \p which input buffer.
608  */
609  float pc_input_buffers_full(int which);
610 
611  /*!
612  * \brief Gets average fullness of \p which input buffer.
613  */
614  float pc_input_buffers_full_avg(int which);
615 
616  /*!
617  * \brief Gets variance of fullness of \p which input buffer.
618  */
619  float pc_input_buffers_full_var(int which);
620 
621  /*!
622  * \brief Gets instantaneous fullness of all input buffers.
623  */
624  std::vector<float> pc_input_buffers_full();
625 
626  /*!
627  * \brief Gets average fullness of all input buffers.
628  */
629  std::vector<float> pc_input_buffers_full_avg();
630 
631  /*!
632  * \brief Gets variance of fullness of all input buffers.
633  */
634  std::vector<float> pc_input_buffers_full_var();
635 
636  /*!
637  * \brief Gets instantaneous fullness of \p which output buffer.
638  */
639  float pc_output_buffers_full(int which);
640 
641  /*!
642  * \brief Gets average fullness of \p which output buffer.
643  */
644  float pc_output_buffers_full_avg(int which);
645 
646  /*!
647  * \brief Gets variance of fullness of \p which output buffer.
648  */
649  float pc_output_buffers_full_var(int which);
650 
651  /*!
652  * \brief Gets instantaneous fullness of all output buffers.
653  */
654  std::vector<float> pc_output_buffers_full();
655 
656  /*!
657  * \brief Gets average fullness of all output buffers.
658  */
659  std::vector<float> pc_output_buffers_full_avg();
660 
661  /*!
662  * \brief Gets variance of fullness of all output buffers.
663  */
664  std::vector<float> pc_output_buffers_full_var();
665 
666  /*!
667  * \brief Gets instantaneous clock cycles spent in work.
668  */
669  float pc_work_time();
670 
671  /*!
672  * \brief Gets average clock cycles spent in work.
673  */
675 
676  /*!
677  * \brief Gets average clock cycles spent in work.
678  */
680 
681  /*!
682  * \brief Gets total clock cycles spent in work.
683  */
685 
686  /*!
687  * \brief Gets average throughput.
688  */
690 
691  /*!
692  * \brief Resets the performance counters
693  */
695 
696  /*!
697  * \brief Sets up export of perf. counters to ControlPort. Only
698  * called by the scheduler.
699  */
700  void setup_pc_rpc();
701 
702  /*!
703  * \brief Checks if this block is already exporting perf. counters
704  * to ControlPort.
705  */
706  bool is_pc_rpc_set() const { return d_pc_rpc_set; }
707 
708  /*!
709  * \brief If the block calls this in its constructor, it's
710  * perf. counters will not be exported.
711  */
712  void no_pc_rpc() { d_pc_rpc_set = true; }
713 
714 
715  // ----------------------------------------------------------------------------
716  // Functions to handle thread affinity
717 
718  /*!
719  * \brief Set the thread's affinity to processor core \p n.
720  *
721  * \param mask a vector of ints of the core numbers available to this block.
722  */
723  void set_processor_affinity(const std::vector<int>& mask) override;
724 
725  /*!
726  * \brief Remove processor affinity to a specific core.
727  */
728  void unset_processor_affinity() override;
729 
730  /*!
731  * \brief Get the current processor affinity.
732  */
733  std::vector<int> processor_affinity() override { return d_affinity; }
734 
735  /*!
736  * \brief Get the current thread priority in use
737  */
739 
740  /*!
741  * \brief Get the current thread priority stored
742  */
744 
745  /*!
746  * \brief Set the current thread priority
747  */
748  int set_thread_priority(int priority);
749 
750  bool update_rate() const;
751 
752  // ----------------------------------------------------------------------------
753 
754  /*!
755  * \brief the system message handler
756  */
758 
759  /*!
760  * \brief Set the logger's output level.
761  *
762  * Sets the level of the logger. This takes a string that is
763  * translated to the standard levels and can be (case insensitive):
764  *
765  * \li off , notset
766  * \li debug
767  * \li info
768  * \li notice
769  * \li warn
770  * \li error
771  * \li crit
772  * \li alert
773  * \li fatal
774  * \li emerg
775  */
776  void set_log_level(const std::string& level) override;
777 
778  /*!
779  * \brief Get the logger's output level
780  */
781  std::string log_level() override;
782 
783  /*!
784  * \brief returns true when execution has completed due to a message connection
785  */
786  bool finished();
787 
788 private:
789  int d_output_multiple;
790  bool d_output_multiple_set;
791  int d_unaligned;
792  bool d_is_unaligned;
793  double d_relative_rate; // approx output_rate / input_rate
794  mpq_class d_mp_relative_rate;
795  block_detail_sptr d_detail; // implementation details
796  unsigned d_history;
797  unsigned d_attr_delay; // the block's sample delay
798  bool d_fixed_rate;
799  bool d_max_noutput_items_set; // if d_max_noutput_items is valid
800  int d_max_noutput_items; // value of max_noutput_items for this block
801  int d_min_noutput_items;
803  d_tag_propagation_policy; // policy for moving tags downstream
804  std::vector<int> d_affinity; // thread affinity proc. mask
805  int d_priority; // thread priority level
806  bool d_pc_rpc_set;
807  bool d_update_rate; // should sched update rel rate?
808  bool d_finished; // true if msg ports think we are finished
809 
810 protected:
811  block(void) {} // allows pure virtual interface sub-classes
812  block(const std::string& name,
813  gr::io_signature::sptr input_signature,
814  gr::io_signature::sptr output_signature);
815 
816  void set_fixed_rate(bool fixed_rate) { d_fixed_rate = fixed_rate; }
817 
818  /*!
819  * \brief Adds a new tag onto the given output buffer.
820  *
821  * \param which_output an integer of which output stream to attach the tag
822  * \param abs_offset a uint64 number of the absolute item number
823  * associated with the tag. Can get from nitems_written.
824  * \param key the tag key as a PMT symbol
825  * \param value any PMT holding any value for the given key
826  * \param srcid optional source ID specifier; defaults to PMT_F
827  */
828  inline void add_item_tag(unsigned int which_output,
829  uint64_t abs_offset,
830  const pmt::pmt_t& key,
831  const pmt::pmt_t& value,
832  const pmt::pmt_t& srcid = pmt::PMT_F)
833  {
834  tag_t tag;
835  tag.offset = abs_offset;
836  tag.key = key;
837  tag.value = value;
838  tag.srcid = srcid;
839  this->add_item_tag(which_output, tag);
840  }
841 
842  /*!
843  * \brief Adds a new tag onto the given output buffer.
844  *
845  * \param which_output an integer of which output stream to attach the tag
846  * \param tag the tag object to add
847  */
848  void add_item_tag(unsigned int which_output, const tag_t& tag);
849 
850  /*!
851  * \brief Given a [start,end), returns a vector of all tags in the range.
852  *
853  * Range of counts is from start to end-1.
854  *
855  * The vector is sorted ascendingly by the offset of the tags.
856  *
857  * Tags are tuples of:
858  * (item count, source id, key, value)
859  *
860  * \param v a vector reference to return tags into
861  * \param which_input an integer of which input stream to pull from
862  * \param abs_start a uint64 count of the start of the range of interest
863  * \param abs_end a uint64 count of the end of the range of interest
864  */
865  void get_tags_in_range(std::vector<tag_t>& v,
866  unsigned int which_input,
867  uint64_t abs_start,
868  uint64_t abs_end);
869 
870  /*!
871  * \brief Given a [start,end), returns a vector of all tags in the
872  * range with a given key.
873  *
874  * Range of counts is from start to end-1.
875  *
876  * The vector is sorted ascendingly by the offset of the tags.
877  *
878  * Tags are tuples of:
879  * (item count, source id, key, value)
880  *
881  * \param v a vector reference to return tags into
882  * \param which_input an integer of which input stream to pull from
883  * \param abs_start a uint64 count of the start of the range of interest
884  * \param abs_end a uint64 count of the end of the range of interest
885  * \param key a PMT symbol key to filter only tags of this key
886  */
887  void get_tags_in_range(std::vector<tag_t>& v,
888  unsigned int which_input,
889  uint64_t abs_start,
890  uint64_t abs_end,
891  const pmt::pmt_t& key);
892 
893  /*!
894  * \brief Gets all tags within the relative window of the current call to work.
895  *
896  * \details
897  *
898  * This operates much like get_tags_in_range but allows us to
899  * work within the current window of items. Item range is
900  * therefore within the possible range of 0 to
901  * ninput_items[whic_input].
902  *
903  * Range of items counts from \p rel_start to \p rel_end-1 within
904  * current window.
905  *
906  * The vector is sorted ascendingly by the offset of the tags.
907  *
908  * Tags are tuples of:
909  * (item count, source id, key, value)
910  *
911  * \param v a vector reference to return tags into
912  * \param which_input an integer of which input stream to pull from
913  * \param rel_start a uint64 count of the start of the range of interest
914  * \param rel_end a uint64 count of the end of the range of interest
915  */
916  void get_tags_in_window(std::vector<tag_t>& v,
917  unsigned int which_input,
918  uint64_t rel_start,
919  uint64_t rel_end);
920 
921  /*!
922  * \brief Operates like gr::block::get_tags_in_window with the
923  * ability to only return tags with the specified \p key.
924  *
925  * \details
926  *
927  * \param v a vector reference to return tags into
928  * \param which_input an integer of which input stream to pull from
929  * \param rel_start a uint64 count of the start of the range of interest
930  * \param rel_end a uint64 count of the end of the range of interest
931  * \param key a PMT symbol key to filter only tags of this key
932  */
933  void get_tags_in_window(std::vector<tag_t>& v,
934  unsigned int which_input,
935  uint64_t rel_start,
936  uint64_t rel_end,
937  const pmt::pmt_t& key);
938 
939  /*!
940  * \brief Get the first tag in specified range (if any), fulfilling criterion
941  *
942  * \details
943  * This function returns the lowest-offset tag in the range for whom the predicate
944  * function returns true.
945  *
946  * The predicate function hence needs to map tags to booleans; its signature is
947  * bool function(const tag_t& tag_to check);
948  *
949  * A sensible choice is a side-effect-free lambda, e.g., you'd use this as:
950  *
951  * auto timestamp = get_first_tag_in_range(
952  * 0, // which input
953  * nitems_read(0), // start index
954  * nitems_read(0) + something, // end
955  * [this](const gr::tag_t& tag) {
956  * return pmt::eqv(tag.key, d_time_tag) && !pmt::is_null(tag.value)
957  * });
958  * if (timestamp) {
959  * d_logger->info("got time tag {} at offset {}",
960  * timestamp.value.value,
961  * timestamp.value.offset);
962  * }
963  *
964  * \param which_input an integer of which input stream to pull from
965  * \param start a uint64 count of the start of the range of interest
966  * \param end a uint64 count of the end of the range of interest
967  * \param predicate a function of tag_t, returning a boolean
968  */
969  std::optional<gr::tag_t> get_first_tag_in_range(
970  unsigned which_input,
971  uint64_t start,
972  uint64_t end,
973  std::function<bool(const gr::tag_t&)> predicate = [](const gr::tag_t&) {
974  return true;
975  });
976 
977  /*!
978  * \brief Get the first tag in specified range (if any) with given key
979  *
980  * \details Convenience wrapper for the predicate-accepting version.
981  *
982  * \param which_input an integer of which input stream to pull from
983  * \param start a uint64 count of the start of the range of interest
984  * \param end a uint64 count of the end of the range of interest
985  * \param key the PMT to match tag keys agains
986  */
987  [[nodiscard]] std::optional<gr::tag_t> get_first_tag_in_range(unsigned which_input,
988  uint64_t start,
989  uint64_t end,
990  const pmt::pmt_t& key);
991 
992  void enable_update_rate(bool en);
993 
994  /*!
995  * \brief Allocate a buffer for the given output port of this block. Note
996  * that the downstream max number of items must be passed in to this
997  * function for consideration.
998  */
999  buffer_sptr allocate_buffer(size_t port,
1000  int downstream_max_nitems,
1001  uint64_t downstream_lcm_nitems,
1002  uint32_t downstream_max_out_mult);
1003 
1004  std::vector<long> d_max_output_buffer;
1005  std::vector<long> d_min_output_buffer;
1006 
1007  unsigned int d_blkd_input_timer_value = 250;
1008 
1009  /*! Used by block's setters and work functions to make
1010  * setting/resetting of parameters thread-safe.
1011  *
1012  * Used by calling gr::thread::scoped_lock l(d_setlock);
1013  */
1015 
1016  // These are really only for internal use, but leaving them public avoids
1017  // having to work up an ever-varying list of friend GR_RUNTIME_APIs
1018 
1019  /*! PMT Symbol for "hey, we're done here"
1020  */
1022 
1023  /*! PMT Symbol of the system port, `pmt::mp("system")`
1024  */
1026 
1027 public:
1028  block_detail_sptr detail() const { return d_detail; }
1029  void set_detail(block_detail_sptr detail) { d_detail = detail; }
1030 
1031  /*! \brief Tell msg neighbors we are finished
1032  */
1034 
1035  /*! \brief Make sure we don't think we are finished
1036  */
1037  void clear_finished() { d_finished = false; }
1038 
1039  std::string identifier() const;
1040 };
1041 
1042 typedef std::vector<block_sptr> block_vector_t;
1043 typedef std::vector<block_sptr>::iterator block_viter_t;
1044 
1045 inline block_sptr cast_to_block_sptr(basic_block_sptr p)
1046 {
1047  return std::dynamic_pointer_cast<block, basic_block>(p);
1048 }
1049 
1050 GR_RUNTIME_API std::ostream& operator<<(std::ostream& os, const block* m);
1051 
1052 } /* namespace gr */
1053 
1054 #endif /* INCLUDED_GR_RUNTIME_BLOCK_H */
The abstract base class for all signal processing blocks.
Definition: basic_block.h:63
The abstract base class for all 'terminal' processing blocks.
Definition: gnuradio-runtime/include/gnuradio/block.h:65
void set_processor_affinity(const std::vector< int > &mask) override
Set the thread's affinity to processor core n.
float pc_input_buffers_full_var(int which)
Gets variance of fullness of which input buffer.
int unaligned() const
Definition: gnuradio-runtime/include/gnuradio/block.h:239
virtual bool stop()
Called to disable drivers, etc for i/o devices.
float pc_input_buffers_full_avg(int which)
Gets average fullness of which input buffer.
int active_thread_priority()
Get the current thread priority in use.
mpq_class & mp_relative_rate()
return a reference to the multiple precision rational representation of the approximate output rate /...
Definition: gnuradio-runtime/include/gnuradio/block.h:334
virtual int general_work(int noutput_items, gr_vector_int &ninput_items, gr_vector_const_void_star &input_items, gr_vector_void_star &output_items)
compute output items from input items
void set_is_unaligned(bool u)
std::vector< float > pc_output_buffers_full_avg()
Gets average fullness of all output buffers.
float pc_output_buffers_full_avg(int which)
Gets average fullness of which output buffer.
void consume_each(int how_many_items)
Tell the scheduler how_many_items were consumed on each input stream.
buffer_sptr replace_buffer(size_t src_port, size_t dst_port, block_sptr block_owner)
Replace the block's buffer with a new one owned by the block_owner parameter.
float pc_nproduced_var()
Gets variance of num items produced performance counter.
uint64_t nitems_read(unsigned int which_input)
Return the number of items read on input stream which_input.
const pmt::pmt_t d_system_port
Definition: gnuradio-runtime/include/gnuradio/block.h:1025
double relative_rate() const
return the approximate output rate / input rate
Definition: gnuradio-runtime/include/gnuradio/block.h:310
float pc_output_buffers_full_var(int which)
Gets variance of fullness of which output buffer.
std::vector< float > pc_input_buffers_full_var()
Gets variance of fullness of all input buffers.
float pc_work_time_total()
Gets total clock cycles spent in work.
void set_inverse_relative_rate(double inverse_relative_rate)
Set the approximate output rate / input rate using its reciprocal.
std::vector< float > pc_input_buffers_full()
Gets instantaneous fullness of all input buffers.
float pc_work_time_avg()
Gets average clock cycles spent in work.
std::vector< int > processor_affinity() override
Get the current processor affinity.
Definition: gnuradio-runtime/include/gnuradio/block.h:733
unsigned int blkd_input_timer_value()
DEPRECATED Returns timer value set when input is blocked.
float pc_noutput_items_avg()
Gets average noutput_items performance counter.
void system_handler(pmt::pmt_t msg)
the system message handler
void allocate_detail(int ninputs, int noutputs, const std::vector< int > &downstream_max_nitems_vec, const std::vector< uint64_t > &downstream_lcm_nitems_vec, const std::vector< uint32_t > &downstream_max_out_mult_vec)
Allocate the block_detail and necessary output buffers for this block.
void get_tags_in_window(std::vector< tag_t > &v, unsigned int which_input, uint64_t rel_start, uint64_t rel_end, const pmt::pmt_t &key)
Operates like gr::block::get_tags_in_window with the ability to only return tags with the specified k...
void unset_max_noutput_items()
Clear the switch for using the max_noutput_items value of this block.
void set_min_output_buffer(int port, long min_output_buffer)
Request limit on min buffer size on output port port.
void consume(int which_input, int how_many_items)
Tell the scheduler how_many_items of input stream which_input were consumed.
void set_tag_propagation_policy(tag_propagation_policy_t p)
Set the policy by the scheduler to determine how tags are moved downstream.
tag_propagation_policy_t tag_propagation_policy()
Asks for the policy used by the scheduler to moved tags downstream.
float pc_work_time_var()
Gets average clock cycles spent in work.
float pc_input_buffers_full(int which)
Gets instantaneous fullness of which input buffer.
void set_alignment(int multiple)
Constrains buffers to work on a set item alignment (for SIMD)
std::vector< long > d_min_output_buffer
Definition: gnuradio-runtime/include/gnuradio/block.h:1005
void set_unaligned(int na)
bool is_set_max_noutput_items()
Ask the block if the flag is or is not set to use the internal value of max_noutput_items during a ca...
int thread_priority()
Get the current thread priority stored.
virtual void forecast(int noutput_items, gr_vector_int &ninput_items_required)
Estimate input requirements given output request.
long max_output_buffer(size_t i)
Returns max buffer size on output port i.
unsigned sample_delay(int which) const
block(void)
Definition: gnuradio-runtime/include/gnuradio/block.h:811
void set_output_multiple(int multiple)
Constrain the noutput_items argument passed to forecast and general_work.
void set_min_noutput_items(int m)
Set the minimum number of output items this block can produce during a call to work.
Definition: gnuradio-runtime/include/gnuradio/block.h:392
uint64_t relative_rate_d() const
return the denominator, or decimation rate, of the approximate output rate / input rate
Definition: gnuradio-runtime/include/gnuradio/block.h:325
std::vector< float > pc_output_buffers_full()
Gets instantaneous fullness of all output buffers.
void set_max_output_buffer(long max_output_buffer)
Request limit on max buffer size on all output ports.
void enable_update_rate(bool en)
buffer_sptr allocate_buffer(size_t port, int downstream_max_nitems, uint64_t downstream_lcm_nitems, uint32_t downstream_max_out_mult)
Allocate a buffer for the given output port of this block. Note that the downstream max number of ite...
uint64_t nitems_written(unsigned int which_output)
Return the number of items written on output stream which_output.
void no_pc_rpc()
If the block calls this in its constructor, it's perf. counters will not be exported.
Definition: gnuradio-runtime/include/gnuradio/block.h:712
~block() override
std::string identifier() const
void set_detail(block_detail_sptr detail)
Definition: gnuradio-runtime/include/gnuradio/block.h:1029
float pc_throughput_avg()
Gets average throughput.
std::string log_level() override
Get the logger's output level.
virtual bool start()
Called to enable drivers, etc for i/o devices.
void get_tags_in_range(std::vector< tag_t > &v, unsigned int which_input, uint64_t abs_start, uint64_t abs_end, const pmt::pmt_t &key)
Given a [start,end), returns a vector of all tags in the range with a given key.
int set_thread_priority(int priority)
Set the current thread priority.
void unset_processor_affinity() override
Remove processor affinity to a specific core.
float pc_nproduced()
Gets instantaneous num items produced performance counter.
bool finished()
returns true when execution has completed due to a message connection
std::optional< gr::tag_t > get_first_tag_in_range(unsigned which_input, uint64_t start, uint64_t end, std::function< bool(const gr::tag_t &)> predicate=[](const gr::tag_t &) { return true;})
Get the first tag in specified range (if any), fulfilling criterion.
void add_item_tag(unsigned int which_output, uint64_t abs_offset, const pmt::pmt_t &key, const pmt::pmt_t &value, const pmt::pmt_t &srcid=pmt::PMT_F)
Adds a new tag onto the given output buffer.
Definition: gnuradio-runtime/include/gnuradio/block.h:828
void add_item_tag(unsigned int which_output, const tag_t &tag)
Adds a new tag onto the given output buffer.
void setup_pc_rpc()
Sets up export of perf. counters to ControlPort. Only called by the scheduler.
virtual int fixed_rate_ninput_to_noutput(int ninput)
Given ninput samples, return number of output samples that will be produced. N.B. this is only define...
void set_max_output_buffer(int port, long max_output_buffer)
Request limit on max buffer size on output port port.
int alignment() const
Definition: gnuradio-runtime/include/gnuradio/block.h:236
int output_multiple() const
Definition: gnuradio-runtime/include/gnuradio/block.h:215
void expand_minmax_buffer(int port)
void set_min_output_buffer(long min_output_buffer)
Request limit on the minimum buffer size on all output ports.
void get_tags_in_range(std::vector< tag_t > &v, unsigned int which_input, uint64_t abs_start, uint64_t abs_end)
Given a [start,end), returns a vector of all tags in the range.
unsigned history() const
std::vector< float > pc_input_buffers_full_avg()
Gets average fullness of all input buffers.
void produce(int which_output, int how_many_items)
Tell the scheduler how_many_items were produced on output stream which_output.
bool is_unaligned() const
Definition: gnuradio-runtime/include/gnuradio/block.h:241
uint64_t relative_rate_i() const
return the numerator, or interpolation rate, of the approximate output rate / input rate
Definition: gnuradio-runtime/include/gnuradio/block.h:316
void declare_sample_delay(unsigned delay)
void set_fixed_rate(bool fixed_rate)
Definition: gnuradio-runtime/include/gnuradio/block.h:816
work_return_t
Magic return values from general_work.
Definition: gnuradio-runtime/include/gnuradio/block.h:68
gr::thread::mutex d_setlock
Definition: gnuradio-runtime/include/gnuradio/block.h:1014
float pc_output_buffers_full(int which)
Gets instantaneous fullness of which output buffer.
std::vector< long > d_max_output_buffer
Definition: gnuradio-runtime/include/gnuradio/block.h:1004
bool fixed_rate() const
Return true if this block has a fixed input to output rate.
Definition: gnuradio-runtime/include/gnuradio/block.h:143
int min_noutput_items() const
Return the minimum number of output items this block can produce during a call to work.
Definition: gnuradio-runtime/include/gnuradio/block.h:384
tag_propagation_policy_t
enum to represent different tag propagation policies.
Definition: gnuradio-runtime/include/gnuradio/block.h:73
void set_blkd_input_timer_value(unsigned int timer_value_ms)
DEPRECATED Configure the timer set when input is blocked port.
virtual int fixed_rate_noutput_to_ninput(int noutput)
Given noutput samples, return number of input samples required to produce noutput....
void get_tags_in_window(std::vector< tag_t > &v, unsigned int which_input, uint64_t rel_start, uint64_t rel_end)
Gets all tags within the relative window of the current call to work.
bool is_pc_rpc_set() const
Checks if this block is already exporting perf. counters to ControlPort.
Definition: gnuradio-runtime/include/gnuradio/block.h:706
long min_output_buffer(size_t i)
Returns min buffer size on output port i.
void set_history(unsigned history)
void declare_sample_delay(int which, unsigned delay)
block_detail_sptr detail() const
Definition: gnuradio-runtime/include/gnuradio/block.h:1028
float pc_nproduced_avg()
Gets average num items produced performance counter.
bool output_multiple_set() const
Definition: gnuradio-runtime/include/gnuradio/block.h:216
const pmt::pmt_t d_pmt_done
Definition: gnuradio-runtime/include/gnuradio/block.h:1021
void reset_perf_counters()
Resets the performance counters.
void notify_msg_neighbors()
Tell msg neighbors we are finished.
void set_relative_rate(uint64_t interpolation, uint64_t decimation)
Set the approximate output rate / input rate as an integer ratio.
float pc_noutput_items_var()
Gets variance of noutput_items performance counter.
void set_max_noutput_items(int m)
Set the maximum number of output items this block will handle during a call to work.
void set_log_level(const std::string &level) override
Set the logger's output level.
float pc_work_time()
Gets instantaneous clock cycles spent in work.
block(const std::string &name, gr::io_signature::sptr input_signature, gr::io_signature::sptr output_signature)
bool update_rate() const
void clear_finished()
Make sure we don't think we are finished.
Definition: gnuradio-runtime/include/gnuradio/block.h:1037
std::optional< gr::tag_t > get_first_tag_in_range(unsigned which_input, uint64_t start, uint64_t end, const pmt::pmt_t &key)
Get the first tag in specified range (if any) with given key.
float pc_noutput_items()
Gets instantaneous noutput_items performance counter.
int max_noutput_items()
Return the maximum number of output items this block will handle during a call to work.
void set_relative_rate(double relative_rate)
Set the approximate output rate / input rate.
std::vector< float > pc_output_buffers_full_var()
Gets variance of fullness of all output buffers.
std::shared_ptr< io_signature > sptr
Definition: io_signature.h:52
#define GR_RUNTIME_API
Definition: gnuradio-runtime/include/gnuradio/api.h:18
GR_RUNTIME_API const pmt::pmt_t msg()
boost::mutex mutex
Definition: thread.h:34
GNU Radio logging wrapper.
Definition: basic_block.h:29
std::vector< block_sptr >::iterator block_viter_t
Definition: gnuradio-runtime/include/gnuradio/block.h:1043
std::vector< block_sptr > block_vector_t
Definition: gnuradio-runtime/include/gnuradio/block.h:1042
std::ostream & operator<<(std::ostream &os, basic_block_sptr basic_block)
Definition: basic_block.h:436
std::shared_ptr< pmt_base > pmt_t
typedef for shared pointer (transparent reference counting).
Definition: pmt.h:85
#define PMT_F
Definition: pmt.h:125
Definition: tags.h:28
uint64_t offset
the item tag occurred at (as a uint64_t)
Definition: tags.h:30
pmt::pmt_t srcid
the source ID of tag (as a PMT)
Definition: tags.h:39
pmt::pmt_t value
the value of tag (as a PMT)
Definition: tags.h:36
pmt::pmt_t key
the key of tag (as a PMT symbol)
Definition: tags.h:33
Definition: cc_common.h:35
std::vector< const void * > gr_vector_const_void_star
Definition: types.h:28
std::vector< void * > gr_vector_void_star
Definition: types.h:27
std::vector< int > gr_vector_int
Definition: types.h:23