UN_WireData.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * NAME:        UN_WireData.h ( UN Library, C++)
 *
 * COMMENTS:
 *      
 */

#ifndef __UN_WireData_h__
#define __UN_WireData_h__

#include "UN_API.h"
#include "UN_Data.h"
class UN_GraphData;


// ============================================================================
using UN_CustomWireData    = UN_CustomDataT< UN_WireID, UN_WireIndex >;
using UN_CustomWireDataPtr = UT_UniquePtr< UN_CustomWireData >;

// ============================================================================
/// Container of data for all the wires in the graph.
/// 
/// NOTE: This class is generally not trivially relocatable, because 
/// its base class (UN_Data) is not trivially relocatable (see comment there).

class UN_API UN_WireData : public UN_Data
{
public:
    /// Constructors and destructors.
     UN_WireData( UN_CustomWireDataPtr custom_data = UN_CustomWireDataPtr() );
    ~UN_WireData() = default;

                                UN_WireData(UN_WireData &&);
    UN_WireData &               operator=(UN_WireData &&);

protected:
    /// This container can have large data, so generally, forbid 
    /// the costly copy operations to the public.
    /// Knowledgable friends and derived classes can still use them.
    friend UN_GraphData;
                                UN_WireData(const UN_WireData &) = default;
    UN_WireData &               operator=(const UN_WireData &)   = default;

public:
    /// Increases the capacity of the data buffer arrays to the given minimum,
    /// unless the capacity is already greater or equal to that minimum,
    /// in which case the capacity remains unchanged.
    void                        setCapacityIfNeeded( UN_DataSize min_capacity );

    /// @{ Returns wire's custom data container, if one was provided to c-tor.
    UN_CustomWireData *         customWireData()
    { 
        return UTverify_cast<UN_CustomWireData*>( customData() );
    }

    const UN_CustomWireData *   customWireData() const
    { 
        return UTverify_cast<const UN_CustomWireData*>( customData() ); 
    }
    /// @}
    
    /// Merges another wire data container into this one.
    /// Returns a mapping between the wire IDs in the merge source 
    /// and destination (this) data buffers.
    UN_WireIDRemap              merge( const UN_WireData &src_wire_data );

    /// Adds a slot for a new wire in this container.
    /// Returns an ID that should be used to refer to this new wire
    /// for accessing its data (eg, source port, destination port, etc).
    UN_WireID                   addWire();

    /// Clears the data for the given wire to the default state.
    void                        clearWire(UN_WireID wire_id );

    /// Removes the wire from this container and frees the
    /// data slot it occupied. After calling this method, 
    /// the container will have no knowledge of the wire by this ID.
    /// Returns true on successs; false if the wire was not found.
    bool                        removeWire( UN_WireID wire_id );

    /// Frees the data slots occupied by all the wires.
    /// @param 'reset_next_id' If true, the wire ID generator is reset to zero.
    void                        removeAllWires( bool reset_next_id );

    /// Returns true if the given ID refers to a valid wire entry 
    /// in the data buffers. Ie, such a wire exists and is valid.
    bool                        isValid( UN_WireID wire_id ) const
                                    { return UN_Data::isValid( wire_id ); }


    /// Iterator for traversing valid wire IDs.
    class IDIterator : public UN_DataIndexMap::IDIterator
    {
    public:
        using value_type = UN_WireID;

        IDIterator( const UN_DataIndexMap::IDIterator &id_iterator )
            : UN_DataIndexMap::IDIterator( id_iterator )
        {}

        value_type operator*() const
        { return UN_WireID( UN_DataIndexMap::IDIterator::operator*() ); }
    };

    /// Iterator for traversing valid wire IDs in an ascending order.
    class OrderedIDIterator : public UN_DataIndexMap::OrderedIDIterator
    {
    public:
        using value_type = UN_WireID;

        OrderedIDIterator(const UN_DataIndexMap::OrderedIDIterator &id_iterator)
            : UN_DataIndexMap::OrderedIDIterator( id_iterator )
        {}

        value_type operator*() const
        { return UN_WireID( UN_DataIndexMap::OrderedIDIterator::operator*() ); }
    };


    /// Returns a range for iterating valid wire IDs. 
    using IDRange = UT_IteratorRange< IDIterator >;
    IDRange idRange() const
    {
        auto id_range( UN_Data::idRange() );
        return IDRange( id_range.begin(), id_range.end() );
    }

    /// Returns a range for iterating valid wire IDs. 
    using OrderedIDRange = UT_IteratorRange< OrderedIDIterator >;
    OrderedIDRange orderedIDRange() const
    {
        auto id_range( UN_Data::orderedIDRange() );
        return OrderedIDRange( id_range.begin(), id_range.end() );
    }

    /// Returns a list of all the valid wire IDs in the graph.
    UN_WireIDList wireIDs() const
    {
        SYS_STATIC_ASSERT( sizeof(UN_WireID) == sizeof(UN_DataID) );
        return reinterpret_cast<UN_WireIDList&&>( std::move( dataIDs() ));
    }

    /// Returns a list of all the valid wire IDs in the graph.
    UN_WireIDList sortedWireIDs() const
    {
        SYS_STATIC_ASSERT( sizeof(UN_WireID) == sizeof(UN_DataID) );
        return reinterpret_cast<UN_WireIDList&&>( std::move(sortedDataIDs() ));
    }



    /// Sets the data value in a generic buffer for a given wire.
    template<typename T>
    void setGenericData( UN_GenericBufferID buf_id, UN_WireID wire_id,
                         const T &value )
    { UN_Data::setGenericData( buf_id, wire_id, value ); }

    /// Sets the data value in a generic buffer via move.
    template<typename T>
    void setGenericData( UN_GenericBufferID buf_id, UN_WireID wire_id,
                         T &&value )
    { UN_Data::setGenericData( buf_id, wire_id, std::forward<T>(value) ); }

    /// Returns a const ref to the data value in a generic buffer.
    template<typename T>
    const T & genericDataRef( UN_GenericBufferID buf_id,
                           UN_WireID wire_id ) const
    { return UN_Data::genericDataRef<T>( buf_id, wire_id ); }

    /// Returns a copy of a data value from a generic buffer.
    template<typename T>
    T genericDataVal( UN_GenericBufferID buf_id, UN_WireID wire_id ) const
    { return UN_Data::genericDataVal<T>( buf_id, wire_id ); }


    /// Moves the data value out of a generic buffer.
    template<typename T>
    T stealGenericData( UN_GenericBufferID buf_id, UN_WireID wire_id )
    { return UN_Data::stealGenericData<T>( buf_id, wire_id ); }

    /// Updates the data value in a generic buffer in-place via a callable.
    template<typename T, typename OP>
    void updateGenericData( UN_GenericBufferID buf_id, UN_WireID wire_id,
                            const OP &op )
    { UN_Data::updateGenericData<T>( buf_id, wire_id, op ); }


protected:
    /// Returns the wire's data index into the data buffer arrays.
    UN_WireIndex                wireIndex( UN_WireID id ) const
                                    {
                                        return UN_WireIndex( 
                                                UN_Data::dataIndex( id ));
                                    }

private:
    /// Returns the current size of the internals data buffers.
    /// The number of valid entries (slots) in data buffers is less than
    /// or equal to that number, since some data slots may be free.
    UN_DataSize                 coreDataBufferSize() const
                                    {
                                        UT_ASSERT( isCoreDataSizeConsistent() );
                                        return dataBufferSize();
                                    }


    /// Handles merging of another wire data container into this one.
    void                        mergeCoreData( const UN_WireData &src,
                                        const UN_DataMergeInfo &merge_info );

    /// Adds a new data slot to accommodate a new data piece at the given index.
    void                        addCoreData( UN_WireIndex wire_index );

    /// Clears the data for the given wire to the default state.
    void                        clearCoreData( UN_WireIndex wire_index );

    /// Frees the data slot occupied by the given wire,
    /// clearing it if necessary.
    void                        removeCoreData() //, index)
                                    // Nothing urgent to free; will clear lazily
                                    { UT_ASSERT( isDataSizeConsistent() ); }

    /// Frees all the data slots.
    void                        removeAllCoreData();

    /// Sets the capacity of core data buffers if needed.
    void                        setCoreDataCapacityIfNeeded(
                                        UN_DataSize min_capacity );

    /// Returns true if the sizes of all core data buffers are equal.
    bool                        isCoreDataSizeConsistent() const;

    /// Returns true if the sizes of data buffers and index map are equal.
    bool                        isDataSizeConsistent() const;

private: 
};


#endif