GNU Radio C++ API Reference g90d26cb
The Free & Open Software Radio Ecosystem
 
Loading...
Searching...
No Matches
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>
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
30namespace 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{
66public:
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 */
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 */
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 */
615
616 /*!
617 * \brief Gets variance of fullness of \p which input buffer.
618 */
620
621 /*!
622 * \brief Gets instantaneous fullness of all input buffers.
623 */
625
626 /*!
627 * \brief Gets average fullness of all input buffers.
628 */
630
631 /*!
632 * \brief Gets variance of fullness of all input buffers.
633 */
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 */
645
646 /*!
647 * \brief Gets variance of fullness of \p which output buffer.
648 */
650
651 /*!
652 * \brief Gets instantaneous fullness of all output buffers.
653 */
655
656 /*!
657 * \brief Gets average fullness of all output buffers.
658 */
660
661 /*!
662 * \brief Gets variance of fullness of all output buffers.
663 */
665
666 /*!
667 * \brief Gets instantaneous clock cycles spent in work.
668 */
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 */
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 */
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
788private:
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
810protected:
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 */
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 */
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 */
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 */
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
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
1027public:
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
1043typedef std::vector<block_sptr>::iterator block_viter_t;
1044
1045inline block_sptr cast_to_block_sptr(basic_block_sptr p)
1046{
1047 return std::dynamic_pointer_cast<block, basic_block>(p);
1048}
1049
1050GR_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.
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)
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.
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.
float pc_work_time_avg()
Gets average clock cycles spent in work.
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.
std::vector< float > pc_output_buffers_full_var()
Gets variance of fullness of all output buffers.
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
std::vector< float > pc_input_buffers_full_avg()
Gets average fullness of all input buffers.
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.
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 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
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
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.
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.
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.
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.
std::vector< float > pc_input_buffers_full()
Gets instantaneous fullness of all input buffers.
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.
std::vector< int > processor_affinity() override
Get the current processor affinity.
Definition gnuradio-runtime/include/gnuradio/block.h:733
unsigned history() const
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
std::vector< float > pc_output_buffers_full()
Gets instantaneous fullness of all output buffers.
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
std::vector< float > pc_output_buffers_full_avg()
Gets average fullness of all output buffers.
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)
std::vector< float > pc_input_buffers_full_var()
Gets variance of fullness of all input buffers.
bool update_rate() const
void clear_finished()
Make sure we don't think we are finished.
Definition gnuradio-runtime/include/gnuradio/block.h:1037
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::shared_ptr< io_signature > sptr
Definition io_signature.h:52
#define GR_RUNTIME_API
Definition gnuradio-runtime/include/gnuradio/api.h:18
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::ostream & operator<<(std::ostream &os, basic_block_sptr basic_block)
Definition basic_block.h:436
std::vector< block_sptr > block_vector_t
Definition gnuradio-runtime/include/gnuradio/block.h:1042
std::shared_ptr< pmt_base > pmt_t
typedef for shared pointer (transparent reference counting).
Definition pmt.h:85
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