GNU Radio 3.6.5.1 C++ API
gr_tagged_stream_block.h
Go to the documentation of this file.
1 /* -*- c++ -*- */
2 /*
3  * Copyright 2013 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_TAGGED_STREAM_BLOCK_H
24 #define INCLUDED_GR_TAGGED_STREAM_BLOCK_H
25 
26 #include <gr_core_api.h>
27 #include <gr_block.h>
28 
29 /*!
30  * \brief Block that operates on PDUs in form of tagged streams
31  * \ingroup base_blk
32  *
33  * Override work to provide the signal processing implementation.
34  */
36 {
37  private:
38  pmt::pmt_t d_length_tag_key; //!< This is the key for the tag that stores the PDU length
39  gr_vector_int d_n_input_items_reqd; //!< How many input items do I need to process the next PDU?
40 
41  protected:
42  std::string d_length_tag_key_str;
43  gr_tagged_stream_block (void){} //allows pure virtual interface sub-classes
44  gr_tagged_stream_block (const std::string &name,
45  gr_io_signature_sptr input_signature,
46  gr_io_signature_sptr output_signature,
47  const std::string &length_tag_key);
48 
49  /*!
50  * \brief Parse all tags on the first sample of a PDU, return the number of items per input
51  * and prune the length tags.
52  *
53  * In most cases, you don't need to override this, unless the number of items read
54  * is not directly coded in one single tag.
55  *
56  * Default behaviour:
57  * - Go through all input ports
58  * - On every input port, search for the tag with the key specified in \p length_tag_key
59  * - Copy that value as an int to the corresponding position in \p n_input_items_reqd
60  * - Remove the length tag.
61  *
62  * \param[in] tags All the tags found on the first item of every input port.
63  * \param[out] n_input_items_reqd Number of items which will be read from every input
64  */
65  virtual void parse_length_tags(
66  const std::vector<std::vector<gr_tag_t> > &tags,
67  gr_vector_int &n_input_items_reqd
68  );
69 
70  /*!
71  * \brief Calculate the number of output items.
72  *
73  * This is basically the inverse function to forecast(): Given a number of input
74  * items, it returns the maximum number of output items.
75  *
76  * You most likely need to override this function, unless your block is a sync
77  * block or integer interpolator/decimator.
78  *
79  */
80  virtual int calculate_output_stream_length(const gr_vector_int &ninput_items);
81 
82  /*!
83  * \brief Set the new length tags on the output stream
84  *
85  * Default behaviour: Set a tag with key \p length_tag_key and
86  * the number of produced items on every output port.
87  *
88  * For anything else, override this.
89  *
90  * \param n_produced Length of the new PDU
91  * \param n_ports Number of output ports
92  */
93  virtual void update_length_tags(int n_produced, int n_ports);
94 
95  public:
96 
97  /*! \brief Don't override this.
98  */
99  void /* final */ forecast (int noutput_items, gr_vector_int &ninput_items_required);
100 
101  /*!
102  * - Reads the number of input items from the tags using parse_length_tags()
103  * - Checks there's enough data on the input and output buffers
104  * - If not, inform the scheduler and do nothing
105  * - Calls work() with the exact number of items per PDU
106  * - Updates the tags using update_length_tags()
107  */
108  int general_work (int noutput_items,
109  gr_vector_int &ninput_items,
110  gr_vector_const_void_star &input_items,
111  gr_vector_void_star &output_items);
112 
113  /*!
114  * \brief Just like gr_block::general_work, but makes sure the input is valid
115  *
116  * The user must override work to define the signal processing code.
117  * Check the documentation for general_work() to see what happens here.
118  *
119  * Like gr_sync_block, this calls consume() for you (it consumes ninput_items[i]
120  * items from the i-th port).
121  *
122  * A note on tag propagation: The PDU length tags are handled by other functions,
123  * but all other tags are handled just as in any other \p gr_block. So, most likely,
124  * you either set the tag propagation policy to TPP_DONT and handle the tag
125  * propagation manually, or you propagate tags through the scheduler and don't
126  * do anything here.
127  *
128  * \param noutput_items The size of the writable output buffer
129  * \param ninput_items The exact size of the items on every input for this particular PDU.
130  * These will be consumed if a length tag key is provided!
131  * \param input_items See gr_block
132  * \param output_items See gr_block
133  */
134  virtual int work (int noutput_items,
135  gr_vector_int &ninput_items,
136  gr_vector_const_void_star &input_items,
137  gr_vector_void_star &output_items) = 0;
138 
139 };
140 
141 #endif /* INCLUDED_GR_TAGGED_STREAM_BLOCK_H */
142