GNU Radio Manual and C++ API Reference 3.7.14.0
The Free & Open Software Radio Ecosystem
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 * GNU Radio is free software; you can redistribute it and/or modify
8 * it under the terms of the GNU General Public License as published by
9 * the Free Software Foundation; either version 3, or (at your option)
10 * any later version.
11 *
12 * GNU Radio is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 * GNU General Public License for more details.
16 *
17 * You should have received a copy of the GNU General Public License
18 * along with GNU Radio; see the file COPYING. If not, write to
19 * the Free Software Foundation, Inc., 51 Franklin Street,
20 * Boston, MA 02110-1301, USA.
21 */
22
23#ifndef INCLUDED_GR_RUNTIME_BLOCK_H
24#define INCLUDED_GR_RUNTIME_BLOCK_H
25
26#include <gnuradio/api.h>
28#include <gnuradio/logger.h>
29#include <gnuradio/tags.h>
30
31namespace gr {
32
33/*!
34 * \brief The abstract base class for all 'terminal' processing blocks.
35 * \ingroup base_blk
36 *
37 * A signal processing flow is constructed by creating a tree of
38 * hierarchical blocks, which at any level may also contain terminal
39 * nodes that actually implement signal processing functions. This
40 * is the base class for all such leaf nodes.
41 *
42 * Blocks have a set of input streams and output streams. The
43 * input_signature and output_signature define the number of input
44 * streams and output streams respectively, and the type of the data
45 * items in each stream.
46 *
47 * Blocks report the number of items consumed on each input in
48 * general_work(), using consume() or consume_each().
49 *
50 * If the same number of items is produced on each output, the block
51 * returns that number from general_work(). Otherwise, the block
52 * calls produce() for each output, then returns
53 * WORK_CALLED_PRODUCE. The input and output rates are not required
54 * to be related.
55 *
56 * User derived blocks override two methods, forecast and
57 * general_work, to implement their signal processing
58 * behavior. forecast is called by the system scheduler to determine
59 * how many items are required on each input stream in order to
60 * produce a given number of output items.
61 *
62 * general_work is called to perform the signal processing in the
63 * block. It reads the input items and writes the output items.
64 */
66{
67public:
68 //! Magic return values from general_work
69 enum { WORK_CALLED_PRODUCE = -2, WORK_DONE = -1 };
70
71 /*!
72 * \brief enum to represent different tag propagation policies.
73 */
75 TPP_DONT = 0, /*!< Scheduler doesn't propagate tags from in- to output. The block
76 itself is free to insert tags as it wants. */
77 TPP_ALL_TO_ALL = 1, /*!< Propagate tags from all in- to all outputs. The scheduler
78 takes care of that. */
79 TPP_ONE_TO_ONE = 2, /*!< Propagate tags from n. input to n. output. Requires same
80 number of in- and outputs */
81 TPP_CUSTOM = 3 /*!< Like TPP_DONT, but signals the block it should implement
82 application-specific forwarding behaviour. */
83 };
84
85 virtual ~block();
86
87 /*!
88 * Assume block computes y_i = f(x_i, x_i-1, x_i-2, x_i-3...)
89 * History is the number of x_i's that are examined to produce one y_i.
90 * This comes in handy for FIR filters, where we use history to
91 * ensure that our input contains the appropriate "history" for the
92 * filter. History should be equal to the number of filter taps. First
93 * history samples (when there are no previous samples) are
94 * initialized with zeroes.
95 */
96 unsigned history() const;
97 void set_history(unsigned history);
98
99 /*!
100 * Declares the block's delay in samples. Since the delay of
101 * blocks like filters is derived from the taps and not the block
102 * itself, we cannot automatically calculate this value and so
103 * leave it as a user-defined property. It defaults to 0 is not
104 * set.
105 *
106 * This does not actively set the delay; it just tells the
107 * scheduler what the delay is.
108 *
109 * This delay is mostly used to adjust the placement of the tags
110 * and is not currently used for any signal processing. When a tag
111 * is passed through a block with internal delay, its location
112 * should be moved based on the delay of the block. This interface
113 * allows us to tell the scheduler this value.
114 *
115 * \param which The buffer on which to set the delay.
116 * \param delay The sample delay of the data stream.
117 */
118 void declare_sample_delay(int which, unsigned delay);
119
120 /*!
121 * Convenience wrapper to gr::block::declare_delay(int which, unsigned delay)
122 * to set all ports to the same delay.
123 */
124 void declare_sample_delay(unsigned delay);
125
126 /*!
127 * Gets the delay of the block. Since the delay of blocks like
128 * filters is derived from the taps and not the block itself, we
129 * cannot automatically calculate this value and so leave it as a
130 * user-defined property. It defaults to 0 is not set.
131 *
132 * \param which Which port from which to get the sample delay.
133 */
134 unsigned sample_delay(int which) const;
135
136 /*!
137 * \brief Return true if this block has a fixed input to output rate.
138 *
139 * If true, then fixed_rate_in_to_out and fixed_rate_out_to_in may be called.
140 */
141 bool fixed_rate() const { return d_fixed_rate; }
142
143 // ----------------------------------------------------------------
144 // override these to define your behavior
145 // ----------------------------------------------------------------
146
147 /*!
148 * \brief Estimate input requirements given output request
149 *
150 * \param noutput_items number of output items to produce
151 * \param ninput_items_required number of input items required on each input stream
152 *
153 * Given a request to product \p noutput_items, estimate the
154 * number of data items required on each input stream. The
155 * estimate doesn't have to be exact, but should be close.
156 */
157 virtual void forecast(int noutput_items, gr_vector_int& ninput_items_required);
158
159 /*!
160 * \brief compute output items from input items
161 *
162 * \param noutput_items number of output items to write on each output stream
163 * \param ninput_items number of input items available on each input stream
164 * \param input_items vector of pointers to the input items, one entry per input
165 * stream
166 * \param output_items vector of pointers to the output items, one entry per
167 * output stream
168 *
169 * \returns number of items actually written to each output stream
170 * or WORK_CALLED_PRODUCE or WORK_DONE. It is OK to return a
171 * value less than noutput_items.
172 *
173 * WORK_CALLED_PRODUCE is used where not all outputs produce the
174 * same number of items. general_work must call produce() for each
175 * output to indicate the numer of items actually produced.
176 *
177 * WORK_DONE indicates that no more data will be produced by this block.
178 *
179 * general_work must call consume or consume_each to indicate how
180 * many items were consumed on each input stream.
181 */
182 virtual int general_work(int noutput_items,
183 gr_vector_int& ninput_items,
184 gr_vector_const_void_star& input_items,
185 gr_vector_void_star& output_items);
186
187 /*!
188 * \brief Called to enable drivers, etc for i/o devices.
189 *
190 * This allows a block to enable an associated driver to begin
191 * transferring data just before we start to execute the scheduler.
192 * The end result is that this reduces latency in the pipeline
193 * when dealing with audio devices, usrps, etc.
194 */
195 virtual bool start();
196
197 /*!
198 * \brief Called to disable drivers, etc for i/o devices.
199 */
200 virtual bool stop();
201
202 // ----------------------------------------------------------------
203
204 /*!
205 * \brief Constrain the noutput_items argument passed to forecast and general_work
206 *
207 * set_output_multiple causes the scheduler to ensure that the
208 * noutput_items argument passed to forecast and general_work will
209 * be an integer multiple of \param multiple The default value of
210 * output multiple is 1.
211 */
212 void set_output_multiple(int multiple);
213 int output_multiple() const { return d_output_multiple; }
214 bool output_multiple_set() const { return d_output_multiple_set; }
215
216 /*!
217 * \brief Constrains buffers to work on a set item alignment (for SIMD)
218 *
219 * set_alignment_multiple causes the scheduler to ensure that the
220 * noutput_items argument passed to forecast and general_work will
221 * be an integer multiple of \param multiple The default value is
222 * 1.
223 *
224 * This control is similar to the output_multiple setting, except
225 * that if the number of items passed to the block is less than
226 * the output_multiple, this value is ignored and the block can
227 * produce like normal. The d_unaligned value is set to the number
228 * of items the block is off by. In the next call to general_work,
229 * the noutput_items is set to d_unaligned or less until
230 * d_unaligned==0. The buffers are now aligned again and the
231 * aligned calls can be performed again.
232 */
233 void set_alignment(int multiple);
234 int alignment() const { return d_output_multiple; }
235
236 void set_unaligned(int na);
237 int unaligned() const { return d_unaligned; }
238 void set_is_unaligned(bool u);
239 bool is_unaligned() const { return d_is_unaligned; }
240
241 /*!
242 * \brief Tell the scheduler \p how_many_items of input stream \p
243 * which_input were consumed.
244 *
245 * This function should be used in general_work() to tell the scheduler the
246 * number of input items processed. Calling consume() multiple times in the
247 * same general_work() call is safe. Every invocation of consume() updates
248 * the values returned by nitems_read().
249 */
250 void consume(int which_input, int how_many_items);
251
252 /*!
253 * \brief Tell the scheduler \p how_many_items were consumed on
254 * each input stream.
255 *
256 * Also see notes on consume().
257 */
258 void consume_each(int how_many_items);
259
260 /*!
261 * \brief Tell the scheduler \p how_many_items were produced on
262 * output stream \p which_output.
263 *
264 * This function should be used in general_work() to tell the scheduler the
265 * number of output items produced. If produce() is called in
266 * general_work(), general_work() must return \p WORK_CALLED_PRODUCE.
267 * Calling produce() multiple times in the same general_work() call is safe.
268 * Every invocation of produce() updates the values returned by
269 * nitems_written().
270 */
271 void produce(int which_output, int how_many_items);
272
273 /*!
274 * \brief Set the approximate output rate / input rate
275 *
276 * Provide a hint to the buffer allocator and scheduler.
277 * The default relative_rate is 1.0
278 *
279 * decimators have relative_rates < 1.0
280 * interpolators have relative_rates > 1.0
281 */
282 void set_relative_rate(double relative_rate);
283
284 /*!
285 * \brief return the approximate output rate / input rate
286 */
287 double relative_rate() const { return d_relative_rate; }
288
289 /*
290 * The following two methods provide special case info to the
291 * scheduler in the event that a block has a fixed input to output
292 * ratio. sync_block, sync_decimator and
293 * sync_interpolator override these. If you're fixed rate,
294 * subclass one of those.
295 */
296 /*!
297 * \brief Given ninput samples, return number of output samples that will be produced.
298 * N.B. this is only defined if fixed_rate returns true.
299 * Generally speaking, you don't need to override this.
300 */
301 virtual int fixed_rate_ninput_to_noutput(int ninput);
302
303 /*!
304 * \brief Given noutput samples, return number of input samples required to produce
305 * noutput. N.B. this is only defined if fixed_rate returns true. Generally speaking,
306 * you don't need to override this.
307 */
308 virtual int fixed_rate_noutput_to_ninput(int noutput);
309
310 /*!
311 * \brief Return the number of items read on input stream which_input
312 */
313 uint64_t nitems_read(unsigned int which_input);
314
315 /*!
316 * \brief Return the number of items written on output stream which_output
317 */
318 uint64_t nitems_written(unsigned int which_output);
319
320 /*!
321 * \brief Asks for the policy used by the scheduler to moved tags downstream.
322 */
324
325 /*!
326 * \brief Set the policy by the scheduler to determine how tags are moved downstream.
327 */
329
330 /*!
331 * \brief Return the minimum number of output items this block can
332 * produce during a call to work.
333 *
334 * Should be 0 for most blocks. Useful if we're dealing with
335 * packets and the block produces one packet per call to work.
336 */
337 int min_noutput_items() const { return d_min_noutput_items; }
338
339 /*!
340 * \brief Set the minimum number of output items this block can
341 * produce during a call to work.
342 *
343 * \param m the minimum noutput_items this block can produce.
344 */
345 void set_min_noutput_items(int m) { d_min_noutput_items = m; }
346
347 /*!
348 * \brief Return the maximum number of output items this block will
349 * handle during a call to work.
350 */
352
353 /*!
354 * \brief Set the maximum number of output items this block will
355 * handle during a call to work.
356 *
357 * \param m the maximum noutput_items this block will handle.
358 */
360
361 /*!
362 * \brief Clear the switch for using the max_noutput_items value of this block.
363 *
364 * When is_set_max_noutput_items() returns 'true', the scheduler
365 * will use the value returned by max_noutput_items() to limit the
366 * size of the number of items possible for this block's work
367 * function. If is_set_max_notput_items() returns 'false', then
368 * the scheduler ignores the internal value and uses the value set
369 * globally in the top_block.
370 *
371 * Use this value to clear the 'is_set' flag so the scheduler will
372 * ignore this. Use the set_max_noutput_items(m) call to both set
373 * a new value for max_noutput_items and to re-enable its use in
374 * the scheduler.
375 */
377
378 /*!
379 * \brief Ask the block if the flag is or is not set to use the
380 * internal value of max_noutput_items during a call to work.
381 */
383
384 /*
385 * Used to expand the vectors that hold the min/max buffer sizes.
386 *
387 * Specifically, when -1 is used, the vectors are just initialized
388 * with 1 value; this is used by the flat_flowgraph to expand when
389 * required to add a new value for new ports on these blocks.
390 */
391 void expand_minmax_buffer(int port);
392
393 /*!
394 * \brief Returns max buffer size on output port \p i.
395 */
396 long max_output_buffer(size_t i);
397
398 /*!
399 * \brief Request limit on max buffer size on all output ports.
400 *
401 * \details
402 * This is an advanced feature. Calling this can affect some
403 * fundamental assumptions about the system behavior and
404 * performance.
405 *
406 * The actual buffer size is determined by a number of other
407 * factors from the block and system. This function only provides
408 * a requested maximum. The buffers will always be a multiple of
409 * the system page size, which may be larger than the value asked
410 * for here.
411 *
412 * \param max_output_buffer the requested maximum output size in items.
413 */
414 void set_max_output_buffer(long max_output_buffer);
415
416 /*!
417 * \brief Request limit on max buffer size on output port \p port.
418 *
419 * \details
420 * This is an advanced feature. Calling this can affect some
421 * fundamental assumptions about the system behavior and
422 * performance.
423 *
424 * The actual buffer size is determined by a number of other
425 * factors from the block and system. This function only provides
426 * a requested maximum. The buffers will always be a multiple of
427 * the system page size, which may be larger than the value asked
428 * for here.
429 *
430 * \param port the output port the request applies to.
431 * \param max_output_buffer the requested maximum output size in items.
432 */
433 void set_max_output_buffer(int port, long max_output_buffer);
434
435 /*!
436 * \brief Returns min buffer size on output port \p i.
437 */
438 long min_output_buffer(size_t i);
439
440 /*!
441 * \brief Request limit on the minimum buffer size on all output
442 * ports.
443 *
444 * \details
445 * This is an advanced feature. Calling this can affect some
446 * fundamental assumptions about the system behavior and
447 * performance.
448 *
449 * The actual buffer size is determined by a number of other
450 * factors from the block and system. This function only provides
451 * a requested minimum. The buffers will always be a multiple of
452 * the system page size, which may be larger than the value asked
453 * for here.
454 *
455 * \param min_output_buffer the requested minimum output size in items.
456 */
457 void set_min_output_buffer(long min_output_buffer);
458
459 /*!
460 * \brief Request limit on min buffer size on output port \p port.
461 *
462 * \details
463 * This is an advanced feature. Calling this can affect some
464 * fundamental assumptions about the system behavior and
465 * performance.
466 *
467 * The actual buffer size is determined by a number of other
468 * factors from the block and system. This function only provides
469 * a requested minimum. The buffers will always be a multiple of
470 * the system page size, which may be larger than the value asked
471 * for here.
472 *
473 * \param port the output port the request applies to.
474 * \param min_output_buffer the requested minimum output size in items.
475 */
476 void set_min_output_buffer(int port, long min_output_buffer);
477
478 // --------------- Performance counter functions -------------
479
480 /*!
481 * \brief Gets instantaneous noutput_items performance counter.
482 */
484
485 /*!
486 * \brief Gets average noutput_items performance counter.
487 */
489
490 /*!
491 * \brief Gets variance of noutput_items performance counter.
492 */
494
495 /*!
496 * \brief Gets instantaneous num items produced performance counter.
497 */
499
500 /*!
501 * \brief Gets average num items produced performance counter.
502 */
504
505 /*!
506 * \brief Gets variance of num items produced performance counter.
507 */
509
510 /*!
511 * \brief Gets instantaneous fullness of \p which input buffer.
512 */
513 float pc_input_buffers_full(int which);
514
515 /*!
516 * \brief Gets average fullness of \p which input buffer.
517 */
519
520 /*!
521 * \brief Gets variance of fullness of \p which input buffer.
522 */
524
525 /*!
526 * \brief Gets instantaneous fullness of all input buffers.
527 */
528 std::vector<float> pc_input_buffers_full();
529
530 /*!
531 * \brief Gets average fullness of all input buffers.
532 */
533 std::vector<float> pc_input_buffers_full_avg();
534
535 /*!
536 * \brief Gets variance of fullness of all input buffers.
537 */
538 std::vector<float> pc_input_buffers_full_var();
539
540 /*!
541 * \brief Gets instantaneous fullness of \p which input buffer.
542 */
543 float pc_output_buffers_full(int which);
544
545 /*!
546 * \brief Gets average fullness of \p which input buffer.
547 */
549
550 /*!
551 * \brief Gets variance of fullness of \p which input buffer.
552 */
554
555 /*!
556 * \brief Gets instantaneous fullness of all output buffers.
557 */
558 std::vector<float> pc_output_buffers_full();
559
560 /*!
561 * \brief Gets average fullness of all output buffers.
562 */
563 std::vector<float> pc_output_buffers_full_avg();
564
565 /*!
566 * \brief Gets variance of fullness of all output buffers.
567 */
568 std::vector<float> pc_output_buffers_full_var();
569
570 /*!
571 * \brief Gets instantaneous clock cycles spent in work.
572 */
574
575 /*!
576 * \brief Gets average clock cycles spent in work.
577 */
579
580 /*!
581 * \brief Gets average clock cycles spent in work.
582 */
584
585 /*!
586 * \brief Gets total clock cycles spent in work.
587 */
589
590 /*!
591 * \brief Gets average throughput.
592 */
594
595 /*!
596 * \brief Resets the performance counters
597 */
599
600 /*!
601 * \brief Sets up export of perf. counters to ControlPort. Only
602 * called by the scheduler.
603 */
605
606 /*!
607 * \brief Checks if this block is already exporting perf. counters
608 * to ControlPort.
609 */
610 bool is_pc_rpc_set() { return d_pc_rpc_set; }
611
612 /*!
613 * \brief If the block calls this in its constructor, it's
614 * perf. counters will not be exported.
615 */
616 void no_pc_rpc() { d_pc_rpc_set = true; }
617
618
619 // ----------------------------------------------------------------------------
620 // Functions to handle thread affinity
621
622 /*!
623 * \brief Set the thread's affinity to processor core \p n.
624 *
625 * \param mask a vector of ints of the core numbers available to this block.
626 */
627 void set_processor_affinity(const std::vector<int>& mask);
628
629 /*!
630 * \brief Remove processor affinity to a specific core.
631 */
633
634 /*!
635 * \brief Get the current processor affinity.
636 */
637 std::vector<int> processor_affinity() { return d_affinity; }
638
639 /*!
640 * \brief Get the current thread priority in use
641 */
643
644 /*!
645 * \brief Get the current thread priority stored
646 */
648
649 /*!
650 * \brief Set the current thread priority
651 */
652 int set_thread_priority(int priority);
653
654 bool update_rate() const;
655
656 // ----------------------------------------------------------------------------
657
658 /*!
659 * \brief the system message handler
660 */
662
663 /*!
664 * \brief returns true when execution has completed due to a message connection
665 */
666 bool finished();
667
668private:
669 int d_output_multiple;
670 bool d_output_multiple_set;
671 int d_unaligned;
672 bool d_is_unaligned;
673 double d_relative_rate; // approx output_rate / input_rate
674 block_detail_sptr d_detail; // implementation details
675 unsigned d_history;
676 unsigned d_attr_delay; // the block's sample delay
677 bool d_fixed_rate;
678 bool d_max_noutput_items_set; // if d_max_noutput_items is valid
679 int d_max_noutput_items; // value of max_noutput_items for this block
680 int d_min_noutput_items;
682 d_tag_propagation_policy; // policy for moving tags downstream
683 std::vector<int> d_affinity; // thread affinity proc. mask
684 int d_priority; // thread priority level
685 bool d_pc_rpc_set;
686 bool d_update_rate; // should sched update rel rate?
687 bool d_finished; // true if msg ports think we are finished
688
689protected:
690 block(void) {} // allows pure virtual interface sub-classes
691 block(const std::string& name,
692 gr::io_signature::sptr input_signature,
693 gr::io_signature::sptr output_signature);
694
695 void set_fixed_rate(bool fixed_rate) { d_fixed_rate = fixed_rate; }
696
697 /*!
698 * \brief Adds a new tag onto the given output buffer.
699 *
700 * \param which_output an integer of which output stream to attach the tag
701 * \param abs_offset a uint64 number of the absolute item number
702 * assicated with the tag. Can get from nitems_written.
703 * \param key the tag key as a PMT symbol
704 * \param value any PMT holding any value for the given key
705 * \param srcid optional source ID specifier; defaults to PMT_F
706 */
707 inline void add_item_tag(unsigned int which_output,
708 uint64_t abs_offset,
709 const pmt::pmt_t& key,
710 const pmt::pmt_t& value,
711 const pmt::pmt_t& srcid = pmt::PMT_F)
712 {
713 tag_t tag;
714 tag.offset = abs_offset;
715 tag.key = key;
716 tag.value = value;
717 tag.srcid = srcid;
718 this->add_item_tag(which_output, tag);
719 }
720
721 /*!
722 * \brief Adds a new tag onto the given output buffer.
723 *
724 * \param which_output an integer of which output stream to attach the tag
725 * \param tag the tag object to add
726 */
727 void add_item_tag(unsigned int which_output, const tag_t& tag);
728
729 /*!
730 * \brief DEPRECATED. Will be removed in 3.8.
731 *
732 * \param which_input an integer of which input stream to remove the tag from
733 * \param abs_offset a uint64 number of the absolute item number
734 * assicated with the tag. Can get from nitems_written.
735 * \param key the tag key as a PMT symbol
736 * \param value any PMT holding any value for the given key
737 * \param srcid optional source ID specifier; defaults to PMT_F
738 *
739 * If no such tag is found, does nothing.
740 */
741 inline void remove_item_tag(unsigned int which_input,
742 uint64_t abs_offset,
743 const pmt::pmt_t& key,
744 const pmt::pmt_t& value,
745 const pmt::pmt_t& srcid = pmt::PMT_F)
746 {
747 tag_t tag;
748 tag.offset = abs_offset;
749 tag.key = key;
750 tag.value = value;
751 tag.srcid = srcid;
752 this->remove_item_tag(which_input, tag);
753 }
754
755 /*!
756 * \brief DEPRECATED. Will be removed in 3.8.
757 *
758 * \param which_input an integer of which input stream to remove the tag from
759 * \param tag the tag object to remove
760 */
761 void remove_item_tag(unsigned int which_input, const tag_t& tag);
762
763 /*!
764 * \brief Given a [start,end), returns a vector of all tags in the range.
765 *
766 * Range of counts is from start to end-1.
767 *
768 * Tags are tuples of:
769 * (item count, source id, key, value)
770 *
771 * \param v a vector reference to return tags into
772 * \param which_input an integer of which input stream to pull from
773 * \param abs_start a uint64 count of the start of the range of interest
774 * \param abs_end a uint64 count of the end of the range of interest
775 */
776 void get_tags_in_range(std::vector<tag_t>& v,
777 unsigned int which_input,
778 uint64_t abs_start,
779 uint64_t abs_end);
780
781 /*!
782 * \brief Given a [start,end), returns a vector of all tags in the
783 * range with a given key.
784 *
785 * Range of counts is from start to end-1.
786 *
787 * Tags are tuples of:
788 * (item count, source id, key, value)
789 *
790 * \param v a vector reference to return tags into
791 * \param which_input an integer of which input stream to pull from
792 * \param abs_start a uint64 count of the start of the range of interest
793 * \param abs_end a uint64 count of the end of the range of interest
794 * \param key a PMT symbol key to filter only tags of this key
795 */
796 void get_tags_in_range(std::vector<tag_t>& v,
797 unsigned int which_input,
798 uint64_t abs_start,
799 uint64_t abs_end,
800 const pmt::pmt_t& key);
801
802 /*!
803 * \brief Gets all tags within the relative window of the current call to work.
804 *
805 * \details
806 *
807 * This opperates much like get_tags_in_range but allows us to
808 * work within the current window of items. Item range is
809 * therefore within the possible range of 0 to
810 * ninput_items[whic_input].
811 *
812 * Range of items counts from \p rel_start to \p rel_end-1 within
813 * current window.
814 *
815 * Tags are tuples of:
816 * (item count, source id, key, value)
817 *
818 * \param v a vector reference to return tags into
819 * \param which_input an integer of which input stream to pull from
820 * \param rel_start a uint64 count of the start of the range of interest
821 * \param rel_end a uint64 count of the end of the range of interest
822 */
823 void get_tags_in_window(std::vector<tag_t>& v,
824 unsigned int which_input,
825 uint64_t rel_start,
826 uint64_t rel_end);
827
828 /*!
829 * \brief Operates like gr::block::get_tags_in_window with the
830 * ability to only return tags with the specified \p key.
831 *
832 * \details
833 *
834 * \param v a vector reference to return tags into
835 * \param which_input an integer of which input stream to pull from
836 * \param rel_start a uint64 count of the start of the range of interest
837 * \param rel_end a uint64 count of the end of the range of interest
838 * \param key a PMT symbol key to filter only tags of this key
839 */
840 void get_tags_in_window(std::vector<tag_t>& v,
841 unsigned int which_input,
842 uint64_t rel_start,
843 uint64_t rel_end,
844 const pmt::pmt_t& key);
845
846 void enable_update_rate(bool en);
847
848 std::vector<long> d_max_output_buffer;
849 std::vector<long> d_min_output_buffer;
850
851 /*! Used by block's setters and work functions to make
852 * setting/resetting of parameters thread-safe.
853 *
854 * Used by calling gr::thread::scoped_lock l(d_setlock);
855 */
857
858 /*! Used by blocks to access the logger system.
859 */
862
863 // These are really only for internal use, but leaving them public avoids
864 // having to work up an ever-varying list of friend GR_RUNTIME_APIs
865
866 /*! PMT Symbol for "hey, we're done here"
867 */
869
870 /*! PMT Symbol of the system port, `pmt::mp("system")`
871 */
873
874public:
875 block_detail_sptr detail() const { return d_detail; }
876 void set_detail(block_detail_sptr detail) { d_detail = detail; }
877
878 /*! \brief Tell msg neighbors we are finished
879 */
881
882 /*! \brief Make sure we don't think we are finished
883 */
884 void clear_finished() { d_finished = false; }
885};
886
887typedef std::vector<block_sptr> block_vector_t;
888typedef std::vector<block_sptr>::iterator block_viter_t;
889
890inline block_sptr cast_to_block_sptr(basic_block_sptr p)
891{
892 return boost::dynamic_pointer_cast<block, basic_block>(p);
893}
894
895GR_RUNTIME_API std::ostream& operator<<(std::ostream& os, const block* m);
896
897} /* namespace gr */
898
899#endif /* INCLUDED_GR_RUNTIME_BLOCK_H */
The abstract base class for all signal processing blocks.
Definition: basic_block.h:60
The abstract base class for all 'terminal' processing blocks.
Definition: block.h:66
float pc_input_buffers_full_var(int which)
Gets variance of fullness of which input buffer.
void set_processor_affinity(const std::vector< int > &mask)
Set the thread's affinity to processor core n.
int unaligned() const
Definition: block.h:237
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 input buffer.
void consume_each(int how_many_items)
Tell the scheduler how_many_items were consumed on each input stream.
float pc_nproduced_var()
Gets variance of num items produced performance counter.
virtual ~block()
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: block.h:872
double relative_rate() const
return the approximate output rate / input rate
Definition: block.h:287
float pc_output_buffers_full_var(int which)
Gets variance of fullness of which input buffer.
float pc_work_time_total()
Gets total clock cycles spent in work.
float pc_work_time_avg()
Gets average clock cycles spent in work.
std::vector< int > processor_affinity()
Get the current processor affinity.
Definition: block.h:637
float pc_noutput_items_avg()
Gets average noutput_items performance counter.
void system_handler(pmt::pmt_t msg)
the system message handler
gr::logger_ptr d_debug_logger
Definition: block.h:861
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 remove_item_tag(unsigned int which_input, uint64_t abs_offset, const pmt::pmt_t &key, const pmt::pmt_t &value, const pmt::pmt_t &srcid=pmt::PMT_F)
DEPRECATED. Will be removed in 3.8.
Definition: block.h:741
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: block.h:849
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.
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: block.h:690
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: block.h:345
gr::logger_ptr d_logger
Definition: block.h:860
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)
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: block.h:616
void set_detail(block_detail_sptr detail)
Definition: block.h:876
float pc_throughput_avg()
Gets average throughput.
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.
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: block.h:707
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.
void remove_item_tag(unsigned int which_input, const tag_t &tag)
DEPRECATED. Will be removed in 3.8.
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::vector< float > pc_input_buffers_full()
Gets instantaneous fullness of all input buffers.
int alignment() const
Definition: block.h:234
int output_multiple() const
Definition: block.h:213
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
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: block.h:239
void declare_sample_delay(unsigned delay)
void set_fixed_rate(bool fixed_rate)
Definition: block.h:695
bool is_pc_rpc_set()
Checks if this block is already exporting perf. counters to ControlPort.
Definition: block.h:610
gr::thread::mutex d_setlock
Definition: block.h:856
float pc_output_buffers_full(int which)
Gets instantaneous fullness of which input buffer.
std::vector< long > d_max_output_buffer
Definition: block.h:848
bool fixed_rate() const
Return true if this block has a fixed input to output rate.
Definition: block.h:141
int min_noutput_items() const
Return the minimum number of output items this block can produce during a call to work.
Definition: block.h:337
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: block.h:74
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.
void unset_processor_affinity()
Remove processor affinity to a specific core.
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: block.h:875
float pc_nproduced_avg()
Gets average num items produced performance counter.
bool output_multiple_set() const
Definition: block.h:214
const pmt::pmt_t d_pmt_done
Definition: block.h:868
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.
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.
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: block.h:884
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.
boost::shared_ptr< io_signature > sptr
Definition: io_signature.h:46
#define GR_RUNTIME_API
Definition: gnuradio-runtime/include/gnuradio/api.h:30
std::vector< const void * > gr_vector_const_void_star
Definition: gnuradio-runtime/include/gnuradio/types.h:40
std::vector< void * > gr_vector_void_star
Definition: gnuradio-runtime/include/gnuradio/types.h:39
std::vector< int > gr_vector_int
Definition: gnuradio-runtime/include/gnuradio/types.h:35
static purpose_t msg
Definition: source_logger.h:39
boost::mutex mutex
Definition: thread.h:48
Include this header to use the message passing features.
Definition: basic_block.h:45
@ TPP_DONT
Definition: block_gateway.h:47
@ TPP_ONE_TO_ONE
Definition: block_gateway.h:49
@ TPP_CUSTOM
Definition: block_gateway.h:50
@ TPP_ALL_TO_ALL
Definition: block_gateway.h:48
void * logger_ptr
Definition: logger.h:696
std::vector< block_sptr >::iterator block_viter_t
Definition: block.h:888
std::ostream & operator<<(std::ostream &os, basic_block_sptr basic_block)
Definition: basic_block.h:427
std::vector< block_sptr > block_vector_t
Definition: block.h:887
@ WORK_CALLED_PRODUCE
Definition: block_gateway.h:45
@ WORK_DONE
Definition: block_gateway.h:45
boost::intrusive_ptr< pmt_base > pmt_t
typedef for shared pointer (transparent reference counting). See http://www.boost....
Definition: pmt.h:56
#define PMT_F
Definition: pmt.h:105
Definition: tags.h:31
uint64_t offset
the item tag occurred at (as a uint64_t)
Definition: tags.h:33
pmt::pmt_t srcid
the source ID of tag (as a PMT)
Definition: tags.h:42
pmt::pmt_t value
the value of tag (as a PMT)
Definition: tags.h:39
pmt::pmt_t key
the key of tag (as a PMT symbol)
Definition: tags.h:36
Definition: cc_common.h:45