UN_SubnetData.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_SubnetData.h ( UN Library, C++)
 *
 * COMMENTS:
 *      Core functionality for a utility-based subnet data.
 */

#ifndef __UN_SubnetData_h__
#define __UN_SubnetData_h__

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


// ============================================================================
using UN_CustomSubnetData    = UN_CustomDataT< UN_SubnetID, UN_SubnetIndex >;
using UN_CustomSubnetDataPtr = UT_UniquePtr< UN_CustomSubnetData >;

// ============================================================================
/// Container of data for all the subnetworks 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_SubnetData : public UN_Data
{
public:
    /// Constructors and destructors.
     UN_SubnetData( 
             UN_CustomSubnetDataPtr custom_data = UN_CustomSubnetDataPtr() );
    ~UN_SubnetData() = default;

                                UN_SubnetData(UN_SubnetData&&);
    UN_SubnetData &             operator=(UN_SubnetData&&);

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_SubnetData(const UN_SubnetData&) = default;
    UN_SubnetData &             operator=(const UN_SubnetData&)     = 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 subnet's custom data container, if one was provided to c-tor.
    UN_CustomSubnetData *       customSubnetData()
    { 
        return UTverify_cast<UN_CustomSubnetData*>( customData() );
    }

    const UN_CustomSubnetData *   customSubnetData() const
    { 
        return UTverify_cast<const UN_CustomSubnetData*>( customData() ); 
    }
    /// @}
    
    /// Merges another subnet data into this one.
    /// Returns a mapping between the data IDs in the merge source 
    /// and destination (this) data buffers.
    UN_SubnetIDRemap            merge( const UN_SubnetData &src_subnet_data );

    /// Adds a slot for a new subnet in this container.
    /// Returns an ID that should be used to refer to this new subnet
    /// for accessing its data (eg, children, etc).
    UN_SubnetID                 addSubnet();

    /// Adds a root subnet or returns one if it already exists.
    UN_SubnetID                 findOrAddRootSubnet();

    /// Clears the data for the given subnet to the default state.
    void                        clearSubnet( UN_SubnetID subnet_id );

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

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

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


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

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

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

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

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

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


    /// Returns a range for iterating valid subnet 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 subnet 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 subnet IDs in the graph.
    UN_SubnetIDList subnetIDs() const
    {
        SYS_STATIC_ASSERT( sizeof(UN_SubnetID) == sizeof(UN_DataID) );
        return reinterpret_cast<UN_SubnetIDList&&>( std::move( dataIDs() ));
    }

    /// Returns a list of all the valid subnet IDs in the graph.
    UN_SubnetIDList sortedSubnetIDs() const
    {
        SYS_STATIC_ASSERT( sizeof(UN_SubnetID) == sizeof(UN_DataID) );
        return reinterpret_cast<UN_SubnetIDList&&>(std::move(sortedDataIDs()));
    }


protected:
    /// Returns the subnet data index into the data buffer arrays.
    UN_SubnetIndex              subnetIndex( UN_SubnetID id ) const
                                    {
                                        return UN_SubnetIndex( 
                                                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() );
                                        // NOTE: currently subnets don't have
                                        //  any intrinsic data, so buffer
                                        //  size is always zero.
                                        return UN_DataSize(0) ;
                                    }


    /// Helper that adds a new data slot for the given subnet.
    UN_SubnetID                 addSubnetData(UN_SubnetID subnet_id,
                                        UN_SubnetIndex subnet_index );


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

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

    /// Clears the data for the given subnet to the default state.
    void                        clearCoreData( UN_SubnetIndex subnet_index );

    /// Frees the data slot occupied by the given subnet,
    /// 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: 
    // TODO: FIXME: Add a cache for child ID lookup (child name -> child id)
    //              The graph can use it in conjunciton with topology to speed
    //              up the child lookup based on its name.
    //              This class is where such map logically belongs, since 
    //              topology contains minimal set of only stictly necessary 
    //              relations. Name to ID is an optional optimization.
};


#endif