GNU Radio Manual and C++ API Reference  3.7.9.2
The Free & Open Software Radio Ecosystem
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
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_RUNTIME_TAGGED_STREAM_BLOCK_H
24 #define INCLUDED_GR_RUNTIME_TAGGED_STREAM_BLOCK_H
25 
26 #include <gnuradio/api.h>
27 #include <gnuradio/block.h>
28 
29 namespace gr {
30 
31  /*!
32  * \brief Block that operates on PDUs in form of tagged streams
33  * \ingroup base_blk
34  *
35  * Override work to provide the signal processing implementation.
36  */
38  {
39  private:
40  pmt::pmt_t d_length_tag_key; //!< This is the key for the tag that stores the PDU length
41  gr_vector_int d_n_input_items_reqd; //!< How many input items do I need to process the next PDU?
42 
43  protected:
44  std::string d_length_tag_key_str;
45  tagged_stream_block(void) {} // allows pure virtual interface sub-classes
46  tagged_stream_block(const std::string &name,
47  gr::io_signature::sptr input_signature,
48  gr::io_signature::sptr output_signature,
49  const std::string &length_tag_key);
50 
51  /*!
52  * \brief Parse all tags on the first sample of a PDU, return the
53  * number of items per input and prune the length tags.
54  *
55  * In most cases, you don't need to override this, unless the
56  * number of items read is not directly coded in one single tag.
57  *
58  * Default behaviour:
59  * - Go through all input ports
60  * - On every input port, search for the tag with the key specified in \p length_tag_key
61  * - Copy that value as an int to the corresponding position in \p n_input_items_reqd
62  * - Remove the length tag.
63  *
64  * \param[in] tags All the tags found on the first item of every input port.
65  * \param[out] n_input_items_reqd Number of items which will be read from every input
66  */
67  virtual void parse_length_tags(const std::vector<std::vector<tag_t> > &tags,
68  gr_vector_int &n_input_items_reqd);
69 
70  /*!
71  * \brief Calculate the number of output items.
72  *
73  * This is basically the inverse function to forecast(): Given a
74  * number of input items, it returns the maximum number of output
75  * items.
76  *
77  * You most likely need to override this function, unless your
78  * block is a sync block or integer interpolator/decimator.
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 the
86  * 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  /*! \brief Don't override this.
97  */
98  void /* final */ forecast (int noutput_items, gr_vector_int &ninput_items_required);
99 
100  bool check_topology(int ninputs, int /* noutputs */);
101 
102  /*!
103  * - Reads the number of input items from the tags using parse_length_tags()
104  * - Checks there's enough data on the input and output buffers
105  * - If not, inform the scheduler and do nothing
106  * - Calls work() with the exact number of items per PDU
107  * - Updates the tags using update_length_tags()
108  */
109  int general_work(int noutput_items,
110  gr_vector_int &ninput_items,
111  gr_vector_const_void_star &input_items,
112  gr_vector_void_star &output_items);
113 
114  /*!
115  * \brief Just like gr::block::general_work, but makes sure the input is valid
116  *
117  * The user must override work to define the signal processing
118  * code. Check the documentation for general_work() to see what
119  * happens here.
120  *
121  * Like gr::sync_block, this calls consume() for you (it consumes
122  * ninput_items[i] items from the i-th port).
123  *
124  * A note on tag propagation: The PDU length tags are handled by
125  * other functions, but all other tags are handled just as in any
126  * other \p gr::block. So, most likely, you either set the tag
127  * propagation policy to TPP_DONT and handle the tag propagation
128  * manually, or you propagate tags through the scheduler and don't
129  * do anything here.
130  *
131  * \param noutput_items The size of the writable output buffer
132  * \param ninput_items The exact size of the items on every input for this particular PDU.
133  * These will be consumed if a length tag key is provided!
134  * \param input_items See gr::block
135  * \param output_items See gr::block
136  */
137  virtual int work(int noutput_items,
138  gr_vector_int &ninput_items,
139  gr_vector_const_void_star &input_items,
140  gr_vector_void_star &output_items) = 0;
141  };
142 
143 } /* namespace gr */
144 
145 #endif /* INCLUDED_GR_RUNTIME_TAGGED_STREAM_BLOCK_H */
146 
boost::shared_ptr< io_signature > sptr
Definition: io_signature.h:45
Block that operates on PDUs in form of tagged streamsOverride work to provide the signal processing i...
Definition: tagged_stream_block.h:37
std::vector< const void * > gr_vector_const_void_star
Definition: gnuradio-runtime/include/gnuradio/types.h:38
#define GR_RUNTIME_API
Definition: gnuradio-runtime/include/gnuradio/api.h:30
std::vector< void * > gr_vector_void_star
Definition: gnuradio-runtime/include/gnuradio/types.h:37
std::vector< int > gr_vector_int
Definition: gnuradio-runtime/include/gnuradio/types.h:33
std::string d_length_tag_key_str
Definition: tagged_stream_block.h:44
Include this header to use the message passing features.
Definition: logger.h:131
tagged_stream_block(void)
Definition: tagged_stream_block.h:45
boost::intrusive_ptr< pmt_base > pmt_t
typedef for shared pointer (transparent reference counting). See http://www.boost.org/libs/smart_ptr/smart_ptr.htm
Definition: pmt.h:56
The abstract base class for all 'terminal' processing blocks.A signal processing flow is constructed ...
Definition: block.h:60