Hurricane::Collection< Type > Class Template Reference

Collection description (API) More...

Inheritance diagram for Hurricane::Collection< Type >:

Public Member Functions
virtual	~Collection ()
virtual Collection< Type > *	getClone () const =0
virtual Locator< Type > *	getLocator () const =0
virtual unsigned	getSize () const
Type	getFirst () const
GenericCollection< Type >	getSubSet (const Filter< Type > &filter) const
template<class SubType >
GenericCollection< SubType >	getSubSet () const
template<class SubType >
GenericCollection< SubType >	getSubSet (const Filter< SubType > &filter) const

Detailed Description

template<class Type>
class Hurricane::Collection< Type >

Collection description (API)

Introduction

Collections introduce the concept of set of elements.

Strictly speaking collections are not containers (in the STL way) but indeed set descriptors. For example, the set of instances called by a cell, which are located within a given rectangular area, will be a subtype of Collection<Instance*> whose first attribute will be a pointer to the cell and a second attribute the rectangular area.

Main characteristics of Collections:

• Collections do not own their elements (they remains when the Collection is deleted).
• They can only be iterated forward. Once an element is consumed you cannot go back to it. You must restart the collection walktrough instead.
• Collections are very light objects which are built, copied or destroyed very rapidly.

STL Iterator Support

The Collections now provides a basic iterator support to allow the C++11 for contruct:

Cell* cell = ...; // Get a Cell from somewhere.
 
for( Net* inet : cell->getNets() ) {
  cout << "This is " << inet;
  if (inet->isExternal())
    cout << " [external net].";
  cout << endl;
}

Although the forEach macro is still retained for backward compatibility, it is advisable to use the C++11 way.

The forEach Macro (obsoleted)

Collections are to be used in conjunction with the forEach macro which allows to easily iterate over the elements. Iteration is done through a simplistic iterator which have overload for the operator*() and operator->()

The forEach macro takes three arguments:

forEach(type,iterator,collection)
type	Element's type of the collection.
iterator	Name of the iterator's variable.
collection	An appropriate collection to iterate over, that is, built over type elements.

To use the forEach macro outside the Hurricane namespace, the following statement is necessary:

using Hurricane::ForEachIterator

Here is a small example of a loop:

using Hurricane::ForEachIterator;
 
Cell* cell = ...; // Get a Cell from somewhere.
 
forEach( Net*, inet, cell->getNets() ) {
  cout << "This is " << (*inet);
  if (inet->isExternal())
    cout << " [external net].";
  cout << endl;
}

The Generic getCollection

The collections provide the generic getCollection() function which allows to convert its argument into a generic collection. It has no specific interest for Hurricane collections, but this function is overloaded for STL containers.

This allows to handle a STL containers like a normal collection as shown in the following example:

set<Instance*> instanceSet;
 
// here we fill the set with the desired instances... 
 
forEach(Instance*, iinstance, getCollection(instanceSet)) {
   // process here each instance of the set
   // (the elements are visited according to the set ordering)
}

Remarks

This approach is a little bit less efficient than the use of STL iterators, not much indeed, but has the advantage to be homogeneous with the remaining code (recall: the created collection doesn't make a copy of the STL container and its creation time is negligible).

Caution: The returned collection is valid whenever the STL container

is valid. Then you should not do the following:

GenericCollection<Instance*> getInstances(...)
{
   set<Instance*> instanceSet;
 
   // we fill the container with the appropriate instances
 
   return getCollection(instanceSet); // instanceSet deleted after return
}

The same will occur anyway if you do:

Cell* cell = ...; // we get the cell
 
Nets nets = cell->getNets();
 
cell->destroy();
 
forEach(Net*, inet, nets) {
   ...
}

Locators

Each type of collection provides an associated Locator for tracing through the corresponding set of elements.

Each locator moves efficiently through the data structure without building (in the form of a list or any other container type) the set of elements defined by the collection (it may however use a stack (or something else) to manage recursive traces).

The elements are therefore visited in the order with which they are internally stored. No assumptions must be made about this ordering. However, collections representing an STL container are visited in the same order than the container's one.

If you need to visit the objects in a given order, you must first fill a STL container: either a vector to be sorted accordingly or a set with the given sort criteria (see the Fill method below).

Constructor & Destructor Documentation

~Collection()

template<class Type >

Hurricane::Collection< Type >::~Collection< Type > ( )

inlinevirtual

Destroys the collection but doesn't acts on elements refered by this collection.

Member Function Documentation

getClone()

template<class Type >

Collection< Type > * Hurricane::Collection< Type >::getClone ( ) const

pure virtual

Allocates and returns a clone (copy) of the collection (whatever be its type).

Remarks

In principle there is no need to use this function. However, if you do so, don't forget to delete the clone after use. It is indeed much easier to use generic collections which do that for you, as we will see later.

getLocator()

template<class Type >

Locator< Type > * Hurricane::Collection< Type >::getLocator ( ) const

pure virtual

Allocates and returns a locator adapted to visit the elements of the collection.

Remarks

In principle there is no need to use this function. Use preferably the macro for_each described below. However, if you do so, don't forget to delete this locator after use, else use generic locators, which do that for you, as we will see later.

Referenced by Hurricane::Collection< Type >::getFirst(), and Hurricane::Collection< Type >::getSize().

getSize()

template<class Type >

unsigned Hurricane::Collection< Type >::getSize ( ) const

inlinevirtual

Returns: the number of objects identified within the collection.

Remarks

Very fast in some cases, but may need to visit the collection in most ones.

References Hurricane::Collection< Type >::getLocator().

getFirst()

template<class Type >

Type Hurricane::Collection< Type >::getFirst ( ) const

inline

Returns: the first element of the collection.

Remarks

The result is meaningful only when the collection is non empty.

References Hurricane::Collection< Type >::getLocator().

getSubSet() [1/3]

template<class Type >

GenericCollection< Type > Hurricane::Collection< Type >::getSubSet ( const Filter< Type > &  filter ) const

inline

Returns: the collection representing the subset of elements accepted by the filter.

Nets Cell::getExternalNets() const
{
   return getNets().getSubSet(Net::getIsExternalFilter());
}

getSubSet() [2/3]

template<class Type >

template<class SubType >

GenericCollection< SubType > Hurricane::Collection< Type >::getSubSet< SubType > ( ) const

inline

Returns: the collection corresponding to the subset of elements of type <SubType>.

Remarks

The returned collection is a collection of objects of type SubType and not of type Type.

Contacts Net::getContacts() const
{
   return getComponents().getSubSet<Contact*>();
}

getSubSet() [3/3]

template<class Type >

template<class SubType >

GenericCollection< SubType > Hurricane::Collection< Type >::getSubSet< SubType > ( const Filter< SubType > &  filter ) const

inline

Returns: the collection representing the subset of elements of type <SubType> accepted by the filter.

Remarks

The returned collection is a collection of elements of type SubType and not of type Type and the filter must be a filter of elements of type SubType.

Sample:\n Filter Hurricane::Segment according to their Layer.

class IsOnLayer : public Filter<Segment*> {
   public:
      Layer* _layer;
   public:
      IsOnLayer(Layer* layer)
        : _layer(layer)
      {
         if (!_layer) throw Error("Can't create IsOnLayer filter : null layer");
      };
 
      IsOnLayer(const IsOnLayer& isOnLayer)
        : _layer(isOnLayer._layer)
      { };
 
      IsOnLayer& operator=(const IsOnLayer& isOnLayer)
      {
         _layer = isOnLayer._layer;
         return *this;
      };
 
      virtual Filter<Net*>* getClone() const
      {
         return new IsOnLayer(*this);
      };
 
      virtual bool Accept(Segment* segment) const
      {
         return (segmentgetLayer() == _layer);
      };
};

And somewher later:

Layer* metal = getDataBase()->getTechnology()->getLayer("metal");
 
Segments segments = net->getComponents()->getSubSet<Segment*>(IsOnLayer(metal));
 
// segments represents here the subset of net components
// which are of type Segment and located on layer metal

---

The documentation for this class was generated from the following files:

• Collection.h
• Collection.dox