buffer_single_mapped.h

Go to the documentation of this file.

/* -*- c++ -*- */
/*
 * Copyright 2020 Free Software Foundation, Inc.
 *
 * This file is part of GNU Radio
 *
 * SPDX-License-Identifier: GPL-3.0-or-later
 *
 */
 
#ifndef INCLUDED_GR_RUNTIME_BUFFER_SINGLE_MAPPED_H
#define INCLUDED_GR_RUNTIME_BUFFER_SINGLE_MAPPED_H
 
#include <cstddef>
#include <functional>
 
#include <gnuradio/api.h>
#include <gnuradio/buffer.h>
#include <gnuradio/buffer_reader.h>
#include <gnuradio/logger.h>
#include <gnuradio/runtime_types.h>
 
namespace gr {
 
/*!
 * \brief A single mapped buffer where wrapping conditions are handled explicitly
 * via input/output_blocked_callback functions called from block_executor.
 * \ingroup internal
 */
class GR_RUNTIME_API buffer_single_mapped : public buffer
{
public:
    gr::logger_ptr d_logger;
    gr::logger_ptr d_debug_logger;
 
    ~buffer_single_mapped() override;
 
    /*!
     * \brief Return the block that owns this buffer.
     */
    block_sptr buf_owner() { return d_buf_owner; }
 
    /*!
     * \brief return number of items worth of space available for writing
     */
    int space_available() override;
 
    void update_reader_block_history(unsigned history, int delay) override;
 
    /*!
     * \brief Return true if thread is ready to call input_blocked_callback,
     * false otherwise
     */
    bool input_blkd_cb_ready(int items_required, unsigned read_index) override;
 
    /*!
     * \brief Callback function that the scheduler will call when it determines
     * that the input is blocked. Override this function if needed.
     */
    bool input_blocked_callback(int items_required,
                                int items_avail,
                                unsigned read_index) override = 0;
 
    /*!
     * \brief Return true if thread is ready to call the callback, false otherwise
     */
    bool output_blkd_cb_ready(int output_multiple) override;
 
    /*!
     * \brief Callback function that the scheduler will call when it determines
     * that the output is blocked
     */
    bool output_blocked_callback(int output_multiple, bool force) override = 0;
 
protected:
    /*!
     * \brief Make reasonable attempt to adjust nitems based on read/write
     * granularity then delegate actual allocation to do_allocate_buffer().
     * @return true iff successful.
     */
    bool allocate_buffer(int nitems) override;
 
    /*!
     * \brief Do actual buffer allocation. This is intended (required) to be
     * handled by the derived class.
     */
    virtual bool do_allocate_buffer(size_t final_nitems, size_t sizeof_item) = 0;
 
    unsigned index_add(unsigned a, unsigned b) override
    {
        unsigned s = a + b;
 
        if (s >= d_bufsize)
            s -= d_bufsize;
 
        assert(s < d_bufsize);
        return s;
    }
 
    unsigned index_sub(unsigned a, unsigned b) override
    {
        // NOTE: a is writer ptr and b is read ptr
        int s = a - b;
 
        if (s < 0)
            s = d_bufsize - b;
 
        assert((unsigned)s < d_bufsize);
        return s;
    }
 
 
    friend class buffer_reader;
 
    friend GR_RUNTIME_API buffer_sptr make_buffer(int nitems,
                                                  size_t sizeof_item,
                                                  uint64_t downstream_lcm_nitems,
                                                  block_sptr link,
                                                  block_sptr buf_owner);
 
    block_sptr d_buf_owner; // block that "owns" this buffer
 
    std::unique_ptr<char[]> d_buffer;
 
    /*!
     * \brief constructor is private.  Use gr_make_buffer to create instances.
     *
     * Allocate a buffer that holds at least \p nitems of size \p sizeof_item.
     *
     * \param nitems is the minimum number of items the buffer will hold.
     * \param sizeof_item is the size of an item in bytes.
     * \param downstream_lcm_nitems is the least common multiple of the items to
     *                              read by downstream blocks
     * \param downstream_max_out_mult is the maximum output multiple of all
     *                                downstream blocks
     * \param link is the block that writes to this buffer.
     * \param buf_owner if the block that owns the buffer which may or may not
     *                  be the same as the block that writes to this buffer
     *
     * The total size of the buffer will be rounded up to a system
     * dependent boundary.  This is typically the system page size, but
     * under MS windows is 64KB.
     */
    buffer_single_mapped(int nitems,
                         size_t sizeof_item,
                         uint64_t downstream_lcm_nitems,
                         uint32_t downstream_max_out_mult,
                         block_sptr link,
                         block_sptr buf_owner);
 
    /*!
     * \brief Abstracted logic for the input blocked callback function.
     *
     * This function contains the logic for the input blocked callback however
     * the data adjustment portion of the callback has been abstracted to allow
     * the caller to pass in the desired buffer and corresponding buffer
     * manipulation functions (memcpy and memmove).
     *
     * The input blocked callback is called when a reader needs to read more
     * data than is available in a buffer and the available data is located at
     * the end of the buffer. The input blocked callback will attempt to move
     * any data located at the beginning of the buffer "down", and will then
     * attempt to copy from the end of the buffer back to the beginning of the
     * buffer. This process explicitly handles wrapping for a single mapped
     * buffer and will realign the data at the beginning of the buffer such
     * that the reader is able to read the available data and becomes unblocked.
     *
     * \param items_required is the number of items required by the reader
     * \param items_avail is the number of items available
     * \param read_index is the current read index of the buffer reader caller
     * \param buffer_ptr is the pointer to the desired buffer
     * \param memcpy_func is a pointer to a memcpy function appropriate for the
     *                    the passed in buffer
     * \param memmove_func is a pointer to a memmove function appropriate for
     *                     the passed in buffer
     */
    virtual bool input_blocked_callback_logic(int items_required,
                                              int items_avail,
                                              unsigned read_index,
                                              char* buffer_ptr,
                                              mem_func_t const& memcpy_func,
                                              mem_func_t const& memmove_func);
 
    /*!
     * \brief Abstracted logic for the output blocked callback function.
     *
     * This function contains the logic for the output blocked callback however
     * the data adjustment portion of the callback has been abstracted to allow
     * the caller to pass in the desired buffer and corresponding buffer
     * manipulation functions (memcpy and memmove).
     *
     * The output blocked callback is called when a block needs to write data
     * to the end of a single mapped buffer but not enough free space exists to
     * write the data before the end of the buffer is reached. The output blocked
     * callback will attempt to copy data located towards the end of a single
     * mapped buffer back to the beginning of the buffer. This process explicitly
     * handles wrapping for a single mapped buffer and will realign data located
     * at the end of a buffer back to the beginning of the buffer such that the
     * writing block can write its output into the buffer after the existing data.
     *
     * \param output_multiple
     * \param force run the callback disregarding the internal checks
     * \param buffer_ptr is the pointer to the desired buffer
     * \param memmove_func is a pointer to a memmove function appropriate for
     *                     the passed in buffer
     */
    virtual bool output_blocked_callback_logic(int output_multiple,
                                               bool force,
                                               char* buffer_ptr,
                                               mem_func_t const& memmove_func);
};
 
} /* namespace gr */
 
 
#endif /* INCLUDED_GR_RUNTIME_BUFFER_SINGLE_MAPPED_H */