block高级功能

/* -*- c++ -*- *//* * Copyright 2004,2007,2009,2010,2013 Free Software Foundation, Inc. * * This file is part of GNU Radio * * GNU Radio is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 3, or (at your option) * any later version. * * GNU Radio is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with GNU Radio; see the file COPYING.  If not, write to * the Free Software Foundation, Inc., 51 Franklin Street, * Boston, MA 02110-1301, USA. */#ifndef INCLUDED_GR_RUNTIME_BLOCK_H#define INCLUDED_GR_RUNTIME_BLOCK_H#include <gnuradio/api.h>#include <gnuradio/basic_block.h>#include <gnuradio/tags.h>#include <gnuradio/logger.h>namespace gr {  /*!   * \brief The abstract base class for all 'terminal' processing blocks.   * \ingroup base_blk   *   * A signal processing flow is constructed by creating a tree of   * hierarchical blocks, which at any level may also contain terminal   * nodes that actually implement signal processing functions. This   * is the base class for all such leaf nodes.   *   * Blocks have a set of input streams and output streams.  The   * input_signature and output_signature define the number of input   * streams and output streams respectively, and the type of the data   * items in each stream.   *   * Although blocks may consume data on each input stream at a   * different rate, all outputs streams must produce data at the same   * rate.  That rate may be different from any of the input rates.   *   * User derived blocks override two methods, forecast and   * general_work, to implement their signal processing   * behavior. forecast is called by the system scheduler to determine   * how many items are required on each input stream in order to   * produce a given number of output items.   *   * general_work is called to perform the signal processing in the   * block.  It reads the input items and writes the output items.   */  class GR_RUNTIME_API block : public basic_block  {  public:    //! Magic return values from general_work    enum {      WORK_CALLED_PRODUCE = -2,      WORK_DONE = -1    };    enum tag_propagation_policy_t {      TPP_DONT = 0,      TPP_ALL_TO_ALL = 1,      TPP_ONE_TO_ONE = 2    };    virtual ~block();    /*!     * Assume block computes y_i = f(x_i, x_i-1, x_i-2, x_i-3...)     * History is the number of x_i's that are examined to produce one y_i.     * This comes in handy for FIR filters, where we use history to     * ensure that our input contains the appropriate "history" for the     * filter. History should be equal to the number of filter taps.     */    unsigned history() const;    void  set_history(unsigned history);    /*!     * Declares the block's delay in samples. Since the delay of     * blocks like filters is derived from the taps and not the block     * itself, we cannot automatically calculate this value and so     * leave it as a user-defined property. It defaults to 0 is not     * set.     *     * This does not actively set the delay; it just tells the     * scheduler what the delay is.     *     * This delay is mostly used to adjust the placement of the tags     * and is not currently used for any signal processing. When a tag     * is passed through a block with internal delay, its location     * should be moved based on the delay of the block. This interface     * allows us to tell the scheduler this value.     *     * \param which The buffer on which to set the delay.     * \param delay The sample delay of the data stream.     */    void declare_sample_delay(int which, unsigned delay);    /*!     * Convenience wrapper to gr::block::declare_delay(int which, unsigned delay)     * to set all ports to the same delay.     */    void declare_sample_delay(unsigned delay);    /*!     * Gets the delay of the block. Since the delay of blocks like     * filters is derived from the taps and not the block itself, we     * cannot automatically calculate this value and so leave it as a     * user-defined property. It defaults to 0 is not set.     *     * \param which Which port from which to get the sample delay.     */    unsigned sample_delay(int which) const;    /*!     * \brief Return true if this block has a fixed input to output rate.     *     * If true, then fixed_rate_in_to_out and fixed_rate_out_to_in may be called.     */    bool fixed_rate() const { return d_fixed_rate; }    // ----------------------------------------------------------------    //override these to define your behavior    // ----------------------------------------------------------------    /*!     * \brief  Estimate input requirements given output request     *     * \param noutput_items           number of output items to produce     * \param ninput_items_required   number of input items required on each input stream     *     * Given a request to product \p noutput_items, estimate the     * number of data items required on each input stream.  The     * estimate doesn't have to be exact, but should be close.     */    virtual void forecast(int noutput_items,                          gr_vector_int &ninput_items_required);    /*!     * \brief compute output items from input items     *     * \param noutput_itemsnumber of output items to write on each output stream     * \param ninput_itemsnumber of input items available on each input stream     * \param input_itemsvector of pointers to the input items, one entry per input stream     * \param output_itemsvector of pointers to the output items, one entry per output stream     *     * \returns number of items actually written to each output stream, or -1 on EOF.     * It is OK to return a value less than noutput_items.  -1 <= return value <= noutput_items     *     * general_work must call consume or consume_each to indicate how     * many items were consumed on each input stream.     */    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);    /*!     * \brief Called to enable drivers, etc for i/o devices.     *     * This allows a block to enable an associated driver to begin     * transfering data just before we start to execute the scheduler.     * The end result is that this reduces latency in the pipeline     * when dealing with audio devices, usrps, etc.     */    virtual bool start();    /*!     * \brief Called to disable drivers, etc for i/o devices.     */    virtual bool stop();    // ----------------------------------------------------------------    /*!     * \brief Constrain the noutput_items argument passed to forecast and general_work     *     * set_output_multiple causes the scheduler to ensure that the     * noutput_items argument passed to forecast and general_work will     * be an integer multiple of \param multiple The default value of     * output multiple is 1.     */    void set_output_multiple(int multiple);    int  output_multiple() const { return d_output_multiple; }    bool output_multiple_set() const { return d_output_multiple_set; }    /*!     * \brief Constrains buffers to work on a set item alignment (for SIMD)     *     * set_alignment_multiple causes the scheduler to ensure that the     * noutput_items argument passed to forecast and general_work will     * be an integer multiple of \param multiple The default value is     * 1.     *     * This control is similar to the output_multiple setting, except     * that if the number of items passed to the block is less than     * the output_multiple, this value is ignored and the block can     * produce like normal. The d_unaligned value is set to the number     * of items the block is off by. In the next call to general_work,     * the noutput_items is set to d_unaligned or less until     * d_unaligned==0. The buffers are now aligned again and the     * aligned calls can be performed again.     */    void set_alignment(int multiple);    int  alignment() const { return d_output_multiple; }    void set_unaligned(int na);    int  unaligned() const { return d_unaligned; }    void set_is_unaligned(bool u);    bool is_unaligned() const { return d_is_unaligned; }    /*!     * \brief Tell the scheduler \p how_many_items of input stream \p     * which_input were consumed.     * This function should be called at the end of work() or general_work(), after all processing is finished.     */    void consume(int which_input, int how_many_items);    /*!     * \brief Tell the scheduler \p how_many_items were consumed on     * each input stream.     */    void consume_each(int how_many_items);    /*!     * \brief Tell the scheduler \p how_many_items were produced on     * output stream \p which_output.     *     * If the block's general_work method calls produce, \p     * general_work must return WORK_CALLED_PRODUCE.     */    void produce(int which_output, int how_many_items);    /*!     * \brief Set the approximate output rate / input rate     *     * Provide a hint to the buffer allocator and scheduler.     * The default relative_rate is 1.0     *     * decimators have relative_rates < 1.0     * interpolators have relative_rates > 1.0     */    void set_relative_rate(double relative_rate);    /*!     * \brief return the approximate output rate / input rate     */    double relative_rate() const { return d_relative_rate; }    /*     * The following two methods provide special case info to the     * scheduler in the event that a block has a fixed input to output     * ratio.  sync_block, sync_decimator and     * sync_interpolator override these.  If you're fixed rate,     * subclass one of those.     */    /*!     * \brief Given ninput samples, return number of output samples that will be produced.     * N.B. this is only defined if fixed_rate returns true.     * Generally speaking, you don't need to override this.     */    virtual int fixed_rate_ninput_to_noutput(int ninput);    /*!     * \brief Given noutput samples, return number of input samples required to produce noutput.     * N.B. this is only defined if fixed_rate returns true.     * Generally speaking, you don't need to override this.     */    virtual int fixed_rate_noutput_to_ninput(int noutput);    /*!     * \brief Return the number of items read on input stream which_input     */    uint64_t nitems_read(unsigned int which_input);    /*!     * \brief  Return the number of items written on output stream which_output     */    uint64_t nitems_written(unsigned int which_output);    /*!     * \brief Asks for the policy used by the scheduler to moved tags downstream.     */    tag_propagation_policy_t tag_propagation_policy();    /*!     * \brief Set the policy by the scheduler to determine how tags are moved downstream.     */    void set_tag_propagation_policy(tag_propagation_policy_t p);    /*!     * \brief Return the minimum number of output items this block can     * produce during a call to work.     *     * Should be 0 for most blocks.  Useful if we're dealing with     * packets and the block produces one packet per call to work.     */    int min_noutput_items() const { return d_min_noutput_items; }    /*!     * \brief Set the minimum number of output items this block can     * produce during a call to work.     *     * \param m the minimum noutput_items this block can produce.     */    void set_min_noutput_items(int m) { d_min_noutput_items = m; }    /*!     * \brief Return the maximum number of output items this block will     * handle during a call to work.     */    int max_noutput_items();    /*!     * \brief Set the maximum number of output items this block will     * handle during a call to work.     *     * \param m the maximum noutput_items this block will handle.     */    void set_max_noutput_items(int m);    /*!     * \brief Clear the switch for using the max_noutput_items value of this block.     *     * When is_set_max_noutput_items() returns 'true', the scheduler     * will use the value returned by max_noutput_items() to limit the     * size of the number of items possible for this block's work     * function. If is_set_max_notput_items() returns 'false', then     * the scheduler ignores the internal value and uses the value set     * globally in the top_block.     *     * Use this value to clear the 'is_set' flag so the scheduler will     * ignore this. Use the set_max_noutput_items(m) call to both set     * a new value for max_noutput_items and to reenable its use in     * the scheduler.     */    void unset_max_noutput_items();    /*!     * \brief Ask the block if the flag is or is not set to use the     * internal value of max_noutput_items during a call to work.     */    bool is_set_max_noutput_items();    /*     * Used to expand the vectors that hold the min/max buffer sizes.     *     * Specifically, when -1 is used, the vectors are just initialized     * with 1 value; this is used by the flat_flowgraph to expand when     * required to add a new value for new ports on these blocks.     */    void expand_minmax_buffer(int port);    /*!     * \brief Returns max buffer size on output port \p i.     */    long max_output_buffer(size_t i);    /*!     * \brief Request limit on max buffer size on all output ports.     *     * \details     * This is an advanced feature. Calling this can affect some     * fundamental assumptions about the system behavior and     * performance.     *     * The actual buffer size is determined by a number of other     * factors from the block and system. This function only provides     * a requested maximum. The buffers will always be a multiple of     * the system page size, which may be larger than the value asked     * for here.     *     * \param max_output_buffer the requested maximum output size in items.     */    void set_max_output_buffer(long max_output_buffer);    /*!     * \brief Request limit on max buffer size on output port \p port.     *     * \details     * This is an advanced feature. Calling this can affect some     * fundamental assumptions about the system behavior and     * performance.     *     * The actual buffer size is determined by a number of other     * factors from the block and system. This function only provides     * a requested maximum. The buffers will always be a multiple of     * the system page size, which may be larger than the value asked     * for here.     *     * \param port the output port the request applies to.     * \param max_output_buffer the requested maximum output size in items.     */    void set_max_output_buffer(int port, long max_output_buffer);    /*!     * \brief Returns min buffer size on output port \p i.     */    long min_output_buffer(size_t i);    /*!     * \brief Request limit on the mininum buffer size on all output     * ports.     *     * \details     * This is an advanced feature. Calling this can affect some     * fundamental assumptions about the system behavior and     * performance.     *     * The actual buffer size is determined by a number of other     * factors from the block and system. This function only provides     * a requested minimum. The buffers will always be a multiple of     * the system page size, which may be larger than the value asked     * for here.     *     * \param min_output_buffer the requested minimum output size in items.     */    void set_min_output_buffer(long min_output_buffer);    /*!     * \brief Request limit on min buffer size on output port \p port.     *     * \details     * This is an advanced feature. Calling this can affect some     * fundamental assumptions about the system behavior and     * performance.     *     * The actual buffer size is determined by a number of other     * factors from the block and system. This function only provides     * a requested minimum. The buffers will always be a multiple of     * the system page size, which may be larger than the value asked     * for here.     *     * \param port the output port the request applies to.     * \param min_output_buffer the requested minimum output size in items.     */    void set_min_output_buffer(int port, long min_output_buffer);    // --------------- Performance counter functions -------------    /*!     * \brief Gets instantaneous noutput_items performance counter.     */    float pc_noutput_items();    /*!     * \brief Gets average noutput_items performance counter.     */    float pc_noutput_items_avg();    /*!     * \brief Gets variance of noutput_items performance counter.     */    float pc_noutput_items_var();    /*!     * \brief Gets instantaneous num items produced performance counter.     */    float pc_nproduced();    /*!     * \brief Gets average num items produced performance counter.     */    float pc_nproduced_avg();    /*!     * \brief Gets variance of  num items produced performance counter.     */    float pc_nproduced_var();    /*!     * \brief Gets instantaneous fullness of \p which input buffer.     */    float pc_input_buffers_full(int which);    /*!     * \brief Gets average fullness of \p which input buffer.     */    float pc_input_buffers_full_avg(int which);    /*!     * \brief Gets variance of fullness of \p which input buffer.     */    float pc_input_buffers_full_var(int which);    /*!     * \brief Gets instantaneous fullness of all input buffers.     */    std::vector<float> pc_input_buffers_full();    /*!     * \brief Gets average fullness of all input buffers.     */    std::vector<float> pc_input_buffers_full_avg();    /*!     * \brief Gets variance of fullness of all input buffers.     */    std::vector<float> pc_input_buffers_full_var();    /*!     * \brief Gets instantaneous fullness of \p which input buffer.     */    float pc_output_buffers_full(int which);    /*!     * \brief Gets average fullness of \p which input buffer.     */    float pc_output_buffers_full_avg(int which);    /*!     * \brief Gets variance of fullness of \p which input buffer.     */    float pc_output_buffers_full_var(int which);    /*!     * \brief Gets instantaneous fullness of all output buffers.     */    std::vector<float> pc_output_buffers_full();    /*!     * \brief Gets average fullness of all output buffers.     */    std::vector<float> pc_output_buffers_full_avg();    /*!     * \brief Gets variance of fullness of all output buffers.     */    std::vector<float> pc_output_buffers_full_var();    /*!     * \brief Gets instantaneous clock cycles spent in work.     */    float pc_work_time();    /*!     * \brief Gets average clock cycles spent in work.     */    float pc_work_time_avg();    /*!     * \brief Gets average clock cycles spent in work.     */    float pc_work_time_var();    /*!     * \brief Gets total clock cycles spent in work.     */    float pc_work_time_total();    /*!     * \brief Gets average throughput.     */    float pc_throughput_avg();    /*!     * \brief Resets the performance counters     */    void reset_perf_counters();    /*!     * \brief Sets up export of perf. counters to ControlPort. Only     * called by the scheduler.     */    void setup_pc_rpc();    /*!     * \brief Checks if this block is already exporting perf. counters     * to ControlPort.     */    bool is_pc_rpc_set() { return d_pc_rpc_set; }    /*!     * \brief If the block calls this in its constructor, it's     * perf. counters will not be exported.     */    void no_pc_rpc() { d_pc_rpc_set = true; }    // ----------------------------------------------------------------------------    // Functions to handle thread affinity    /*!     * \brief Set the thread's affinity to processor core \p n.     *     * \param mask a vector of ints of the core numbers available to this block.     */    void set_processor_affinity(const std::vector<int> &mask);    /*!     * \brief Remove processor affinity to a specific core.     */    void unset_processor_affinity();    /*!     * \brief Get the current processor affinity.     */    std::vector<int> processor_affinity() { return d_affinity; }    /*!     * \brief Get the current thread priority in use     */    int active_thread_priority();    /*!     * \brief Get the current thread priority stored     */    int thread_priority();    /*!     * \brief Set the current thread priority     */    int set_thread_priority(int priority);    bool update_rate() const;    // ----------------------------------------------------------------------------/*! * \brief the system message handler     */    void system_handler(pmt::pmt_t msg);/*!     * \brief returns true when execution has completed due to a message connection    */    bool finished();  private:    int                   d_output_multiple;    bool                  d_output_multiple_set;    int                   d_unaligned;    bool                  d_is_unaligned;    double                d_relative_rate;// approx output_rate / input_rate    block_detail_sptr     d_detail;// implementation details    unsigned              d_history;    unsigned              d_attr_delay;         // the block's sample delay    bool                  d_fixed_rate;    bool                  d_max_noutput_items_set;     // if d_max_noutput_items is valid    int                   d_max_noutput_items;         // value of max_noutput_items for this block    int                   d_min_noutput_items;    tag_propagation_policy_t d_tag_propagation_policy; // policy for moving tags downstream    std::vector<int>      d_affinity;              // thread affinity proc. mask    int                   d_priority;              // thread priority level    bool                  d_pc_rpc_set;    bool                  d_update_rate;           // should sched update rel rate?    bool d_finished;    // true if msg ports think we are finished  protected:    block(void) {} // allows pure virtual interface sub-classes    block(const std::string &name,          gr::io_signature::sptr input_signature,          gr::io_signature::sptr output_signature);    void set_fixed_rate(bool fixed_rate) { d_fixed_rate = fixed_rate; }    /*!     * \brief  Adds a new tag onto the given output buffer.     *     * \param which_output an integer of which output stream to attach the tag     * \param abs_offset   a uint64 number of the absolute item number     *                     assicated with the tag. Can get from nitems_written.     * \param key          the tag key as a PMT symbol     * \param value        any PMT holding any value for the given key     * \param srcid        optional source ID specifier; defaults to PMT_F     */    inline 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)    {      tag_t tag;      tag.offset = abs_offset;      tag.key = key;      tag.value = value;      tag.srcid = srcid;      this->add_item_tag(which_output, tag);    }    /*!     * \brief  Adds a new tag onto the given output buffer.     *     * \param which_output an integer of which output stream to attach the tag     * \param tag the tag object to add     */    void add_item_tag(unsigned int which_output, const tag_t &tag);    /*!     * \brief DEPRECATED. Will be removed in 3.8.     *     * \param which_input an integer of which input stream to remove the tag from     * \param abs_offset   a uint64 number of the absolute item number     *                     assicated with the tag. Can get from nitems_written.     * \param key          the tag key as a PMT symbol     * \param value        any PMT holding any value for the given key     * \param srcid        optional source ID specifier; defaults to PMT_F     *     * If no such tag is found, does nothing.     */    inline 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)    {      tag_t tag;      tag.offset = abs_offset;      tag.key = key;      tag.value = value;      tag.srcid = srcid;      this->remove_item_tag(which_input, tag);    }    /*!     * \brief DEPRECATED. Will be removed in 3.8.     *     * \param which_input an integer of which input stream to remove the tag from     * \param tag the tag object to remove     */    void remove_item_tag(unsigned int which_input, const tag_t &tag);    /*!     * \brief Given a [start,end), returns a vector of all tags in the range.     *     * Range of counts is from start to end-1.     *     * Tags are tuples of:     *      (item count, source id, key, value)     *     * \param v            a vector reference to return tags into     * \param which_input  an integer of which input stream to pull from     * \param abs_start    a uint64 count of the start of the range of interest     * \param abs_end      a uint64 count of the end of the range of interest     */    void get_tags_in_range(std::vector<tag_t> &v,                           unsigned int which_input,                           uint64_t abs_start,                           uint64_t abs_end);    /*!     * \brief Given a [start,end), returns a vector of all tags in the     * range with a given key.     *     * Range of counts is from start to end-1.     *     * Tags are tuples of:     *      (item count, source id, key, value)     *     * \param v            a vector reference to return tags into     * \param which_input  an integer of which input stream to pull from     * \param abs_start    a uint64 count of the start of the range of interest     * \param abs_end      a uint64 count of the end of the range of interest     * \param key          a PMT symbol key to filter only tags of this key     */    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);    /*!     * \brief Gets all tags within the relative window of the current call to work.     *     * \details     *     * This opperates much like get_tags_in_range but allows us to     * work within the current window of items. Item range is     * therefore within the possible range of 0 to     * ninput_items[whic_input].     *     * Range of items counts from \p rel_start to \p rel_end-1 within     * current window.     *     * Tags are tuples of:     *      (item count, source id, key, value)     *     * \param v            a vector reference to return tags into     * \param which_input  an integer of which input stream to pull from     * \param rel_start    a uint64 count of the start of the range of interest     * \param rel_end      a uint64 count of the end of the range of interest     */    void get_tags_in_window(std::vector<tag_t> &v,                            unsigned int which_input,                            uint64_t rel_start,                            uint64_t rel_end);    /*!     * \brief Operates like gr::block::get_tags_in_window with the     * ability to only return tags with the specified \p key.     *     * \details     *     * \param v            a vector reference to return tags into     * \param which_input  an integer of which input stream to pull from     * \param rel_start    a uint64 count of the start of the range of interest     * \param rel_end      a uint64 count of the end of the range of interest     * \param key          a PMT symbol key to filter only tags of this key     */    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);    void enable_update_rate(bool en);    std::vector<long> d_max_output_buffer;    std::vector<long> d_min_output_buffer;    /*! Used by block's setters and work functions to make     * setting/resetting of parameters thread-safe.     *     * Used by calling gr::thread::scoped_lock l(d_setlock);     */    gr::thread::mutex d_setlock;    /*! Used by blocks to access the logger system.     */    gr::logger_ptr d_logger;    gr::logger_ptr d_debug_logger;    // These are really only for internal use, but leaving them public avoids    // having to work up an ever-varying list of friend GR_RUNTIME_APIs  public:    block_detail_sptr detail() const { return d_detail; }    void set_detail(block_detail_sptr detail) { d_detail = detail; }   /*! \brief Tell msg neighbors we are finished*/   void notify_msg_neighbors();   /*! \brief Make sure we dont think we are finished*/   void clear_finished(){ d_finished = false; }  };  typedef std::vector<block_sptr> block_vector_t;  typedef std::vector<block_sptr>::iterator block_viter_t;  inline block_sptr cast_to_block_sptr(basic_block_sptr p)  {    return boost::dynamic_pointer_cast<block, basic_block>(p);  }  std::ostream&  operator << (std::ostream& os, const block *m);} /* namespace gr */#endif /* INCLUDED_GR_RUNTIME_BLOCK_H */

使用gr_modtool生成的模块模板中，只给出了几个可以重写的函数。实际上所有的模块都是继承自block基类，在block基类中包含非常多的函数，通过在模块中重写这些函数可以实现很多高级功能。