node.hpp

Go to the documentation of this file.

//
// Copyright 2019 Ettus Research, a National Instruments Brand
//
// SPDX-License-Identifier: GPL-3.0-or-later
//

#pragma once

#include <uhd/rfnoc/actions.hpp>
#include <uhd/rfnoc/dirtifier.hpp>
#include <uhd/rfnoc/property.hpp>
#include <uhd/types/device_addr.hpp>
#include <uhd/types/time_spec.hpp>
#include <uhd/utils/log.hpp>
#include <uhd/utils/scope_exit.hpp>
#include <unordered_map>
#include <unordered_set>
#include <boost/graph/adjacency_list.hpp>
#include <functional>
#include <memory>
#include <mutex>
#include <string>
#include <tuple>
#include <vector>

namespace uhd { namespace rfnoc {

class UHD_API node_t
{
public:
    using resolver_fn_t          = std::function<void(void)>;
    using resolve_callback_t     = std::function<void(void)>;
    using graph_mutex_callback_t = std::function<std::recursive_mutex&(void)>;
    using action_handler_t =
        std::function<void(const res_source_info&, action_info::sptr)>;
    using forwarding_map_t =
        std::unordered_map<res_source_info, std::vector<res_source_info>>;

    enum class forwarding_policy_t {
        //(e.g., if it comes from input port 0, forward it to output port 0).
        ONE_TO_ONE,
        ONE_TO_FAN,
        ONE_TO_ALL_IN,
        ONE_TO_ALL_OUT,
        ONE_TO_ALL,
        DROP,
        USE_MAP
    };

    static const size_t ANY_PORT = size_t(~0);

    /**************************************************************************
     * Structors
     *************************************************************************/
    node_t();

    virtual ~node_t() {}

    /******************************************
     * Basic Operations
     ******************************************/
    // no two nodes cannot have the same ID.
    //
    // \returns The unique ID as a string
    virtual std::string get_unique_id() const;

    virtual size_t get_num_input_ports() const = 0;

    virtual size_t get_num_output_ports() const = 0;

    /******************************************
     * Property Specific
     ******************************************/

    std::vector<std::string> get_property_ids() const;

    template <typename prop_data_t>
    void set_property(
        const std::string& id, const prop_data_t& val, const size_t instance = 0);

    void set_properties(const uhd::device_addr_t& props, const size_t instance = 0);

    template <typename prop_data_t>
    const prop_data_t& get_property(
        const std::string& id, const size_t instance = 0) /* mutable */;

    virtual void set_command_time(uhd::time_spec_t time, const size_t instance);

    virtual uhd::time_spec_t get_command_time(const size_t instance) const;

    virtual void clear_command_time(const size_t instance);

protected:
    /******************************************
     * Internal Registration Functions
     ******************************************/
    using prop_ptrs_t = std::vector<property_base_t*>;

    void register_property(
        property_base_t* prop, resolve_callback_t&& clean_callback = nullptr);

    void add_property_resolver(
        prop_ptrs_t&& inputs, prop_ptrs_t&& outputs, resolver_fn_t&& resolver_fn);

    /**************************************************************************
     * Property forwarding
     *************************************************************************/
    void set_prop_forwarding_policy(
        forwarding_policy_t policy, const std::string& prop_id = "");

    void set_prop_forwarding_map(const forwarding_map_t& map);

    template <typename prop_data_t>
    void set_property(
        const std::string& id, const prop_data_t& val, const res_source_info& src_info);

    template <typename prop_data_t>
    const prop_data_t& get_property(
        const std::string& id, const res_source_info& src_info) /* mutable */;

    /******************************************
     * Internal action forwarding
     ******************************************/
    void register_action_handler(const std::string& id, action_handler_t&& handler);

    void set_action_forwarding_policy(
        forwarding_policy_t policy, const std::string& action_key = "");

    void set_action_forwarding_map(const forwarding_map_t& map);

    void post_action(const res_source_info& edge_info, action_info::sptr action);

    /**************************************************************************
     * Graph Interaction
     *************************************************************************/
    virtual bool check_topology(const std::vector<size_t>& connected_inputs,
        const std::vector<size_t>& connected_outputs);

    virtual void shutdown();

    /**************************************************************************
     * Attributes
     *************************************************************************/
    static dirtifier_t ALWAYS_DIRTY;

private:
    friend class node_accessor_t;

    property_base_t* _find_property(
        res_source_info src_info, const std::string& id) const;

    uhd::utils::scope_exit::uptr _request_property_access(
        property_base_t* prop, property_base_t::access_t access) const;

    template <typename PredicateType>
    prop_ptrs_t filter_props(PredicateType&& predicate)
    {
        prop_ptrs_t filtered_props{};
        for (const auto& type_prop_pair : _props) {
            for (const auto& prop : type_prop_pair.second) {
                if (predicate(prop)) {
                    filtered_props.push_back(prop);
                }
            }
        }

        return filtered_props;
    }

    property_base_t* inject_edge_property(
        property_base_t* blueprint, res_source_info new_src_info);

    void init_props();

    void resolve_props();

    void resolve_all();

    void clean_props();

    void set_resolve_all_callback(resolve_callback_t&& resolver)
    {
        _resolve_all_cb = resolver;
    }

    void clear_resolve_all_callback()
    {
        _resolve_all_cb = _default_resolve_all_cb;
    }

    void set_graph_mutex_callback(graph_mutex_callback_t&& mutex)
    {
        _graph_mutex_cb = mutex;
    }

    void clear_graph_mutex_callback()
    {
        _graph_mutex_cb = NULL;
    }

    void forward_edge_property(
        property_base_t* incoming_prop, const size_t incoming_port);

    /**************************************************************************
     * Action-Related Methods
     *************************************************************************/
    void set_post_action_callback(action_handler_t&& post_handler)
    {
        _post_action_cb = std::move(post_handler);
    }

    void receive_action(const res_source_info& src_info, action_info::sptr action);

    /**************************************************************************
     * Private helpers
     *************************************************************************/
    bool _has_port(const res_source_info& port_info) const;

    template <typename prop_data_t>
    void _set_property(
        const std::string& id, const prop_data_t& val, const res_source_info& src_info);

    /****** Attributes *******************************************************/
    // global property mutex, this only write-protects access to the property-
    // related containers in this class.
    mutable std::mutex _prop_mutex;

    std::unordered_map<res_source_info::source_t,
        std::vector<property_base_t*>,
        std::hash<size_t>>
        _props;

    std::unordered_map<property_base_t*, resolve_callback_t> _clean_cb_registry;

    using property_resolver_t = std::tuple<prop_ptrs_t, prop_ptrs_t, resolver_fn_t>;
    std::vector<property_resolver_t> _prop_resolvers;

    // This will return a global mutex to the graph. It is required to propagate
    // properties on multithread applications.
    graph_mutex_callback_t _graph_mutex_cb;

    // has changed, and that a property resolution needs to be performed.
    resolve_callback_t _resolve_all_cb;

    // method.
    const resolve_callback_t _default_resolve_all_cb = [this]() {
        resolve_props();
        clean_props();
    };


    // explicitly.
    //
    // Dynamic properties include properties defined in the block descriptor
    // file, as well as new properties that get passed in during property
    // propagation.
    std::unordered_set<std::unique_ptr<property_base_t>> _dynamic_props;

    //
    // The entry with the empty-string-key is the default policy.
    std::unordered_map<std::string, forwarding_policy_t> _prop_fwd_policies{
        {"", forwarding_policy_t::ONE_TO_ONE}};

    forwarding_map_t _prop_fwd_map;

    /**************************************************************************
     * Action-related attributes
     *************************************************************************/
    mutable std::mutex _action_mutex;

    std::unordered_map<std::string, action_handler_t> _action_handlers;

    std::unordered_map<std::string, forwarding_policy_t> _action_fwd_policies{
        {"", forwarding_policy_t::ONE_TO_ONE}};

    //
    // The default callback will simply drop actions
    action_handler_t _post_action_cb = [](const res_source_info&,
                                           action_info::sptr) { /* nop */ };

    forwarding_map_t _action_fwd_map;

    /**************************************************************************
     * Other attributes
     *************************************************************************/
    std::vector<uhd::time_spec_t> _cmd_timespecs;
}; // class node_t

}} /* namespace uhd::rfnoc */

#include <uhd/rfnoc/node.ipp>