overwrite_node

[flow_graph.overwrite_node]

A node that is a buffer of a single item that can be overwritten.

// Defined in header <oneapi/tbb/flow_graph.h>

namespace oneapi {
namespace tbb {
namespace flow {

    template<typename T>
    class overwrite_node : public graph_node, public receiver<T>, public sender<T> {
    public:
        explicit overwrite_node( graph &g );
        overwrite_node( const overwrite_node &src );
        ~overwrite_node();

        bool try_put( const T &v );
        bool try_get( T &v );

        bool is_valid( );
        void clear( );
    };

} // namespace flow
} // namespace tbb
} // namespace oneapi

Requirements:

  • The type T must meet the DefaultConstructible requirements from [defaultconstructible] and CopyAssignable requirements from [copyassignable] ISO C++ Standard sections.

This type of node buffers a single item of type T. The value is initially invalid. Gets from the node are non-destructive.

overwrite_node is a graph_node, receiver<T> and sender<T>.

overwrite_node has a buffering and broadcast-push properties.

overwrite_node allows overwriting its single item buffer.

Member functions

explicit overwrite_node(graph &g)

Constructs an object of type overwrite_node that belongs to the graph g with an invalid internal buffer item.

overwrite_node(const overwrite_node &src)

Constructs an object of type overwrite_node that belongs to the graph g with an invalid internal buffer item. The buffered value and list of successors and predecessors are not copied from src.

~overwrite_node()

Destroys the overwrite_node.

bool try_put(const T &v)

Stores v in the internal single item buffer and calls try_put(v) on all successors.

Returns: true

bool try_get(T &v)

If the internal buffer is valid, assigns the value to v.

Returns:true if v is assigned to; false, otherwise.

bool is_valid()

Returns: true if the buffer holds a valid value; false, otherwise.

void clear()

Invalidates the value held in the buffer.

Examples

The example demonstrates overwrite_node as a single-value storage that might be updated. Data can be accessed with direct try_get() call.

#include "oneapi/tbb/flow_graph.h"

int main() {
    const int data_limit = 20;
    int count = 0;

    oneapi::tbb::flow::graph g;

    oneapi::tbb::flow::function_node< int, int > data_set_preparation(g,
        oneapi::tbb::flow::unlimited, []( int data ) {
            printf("Prepare large data set and keep it inside node storage\n");
            return data;
        });

    oneapi::tbb::flow::overwrite_node< int > overwrite_storage(g);

    oneapi::tbb::flow::source_node<int> data_generator(g,
        [&]( int& v ) -> bool {
            if ( count < data_limit ) {
                ++count;
                v = count;
                return true;
            } else {
                return false;
            }
        });

    oneapi::tbb::flow::function_node< int > process(g, oneapi::tbb::flow::unlimited,
        [&]( const int& data) {
            int data_from_storage = 0;
            overwrite_storage.try_get(data_from_storage);
            printf("Data from a storage: %d\n", data_from_storage);
            printf("Data to process: %d\n", data);
        });

    oneapi::tbb::flow::make_edge(data_set_preparation, overwrite_storage);
    oneapi::tbb::flow::make_edge(data_generator, process);

    data_set_preparation.try_put(1);
    data_generator.activate();

    g.wait_for_all();

    return 0;
}

overwrite_node supports reserving join_node as its successor. See the example in the example section of write_once_node.