197 lines
7.2 KiB
C++
197 lines
7.2 KiB
C++
|
|
// -*- C++ -*-
|
|
|
|
|
|
namespace Hurricane {
|
|
|
|
/*! \class GenericCollection
|
|
* \brief GenericCollection description (\b API)
|
|
*
|
|
* \section secGenericCollectionIntro Introduction
|
|
*
|
|
* Collections are powerful objects but share a common weakness.
|
|
* Indeed they don't allow to bring within a variable of type
|
|
* Collection\c \<Type\> a subset collection whose descriptor,
|
|
* of course, has additional attributes. For instance, the
|
|
* following sequence is rejected by the compiler
|
|
\code
|
|
Collection<Net*> nets = cellGetExternalNets();
|
|
\endcode
|
|
* You must therefore imperatively go through a pointer type
|
|
* variable by generating a clone and must not forget to delete
|
|
* this allocated clone after use.
|
|
\code
|
|
Collection<Net*>* nets = cellGetExternalNets().GetClone();
|
|
...
|
|
// use
|
|
...
|
|
delete nets; // we delete the collection, not the nets
|
|
\endcode
|
|
* Fortunately, the GenericCollection\c \<Type\> type solves
|
|
* this weakness. For this purpose, a generic collection creates
|
|
* at its construction (or by assignment) a clone of the given
|
|
* collection and releases, when deleted (or when assigned to an
|
|
* other collection), the previously allocated clone. Now it is
|
|
* feasible to bring into a variable of type
|
|
* GenericCollection\c \<Type\> any collection of type Type (as
|
|
* well as an other generic collection).
|
|
\code
|
|
GenericCollection<Net*> nets = cellGetExternalNets();
|
|
...
|
|
// use it
|
|
...
|
|
\endcode
|
|
* The variable \c \<nets\> being an automatic one, it will be
|
|
* automatically deleted (when leaving the scope the block where
|
|
* it was declared) carrying with it the clone allocated by the
|
|
* assignment.
|
|
*
|
|
* As far as all defined global collection types (Cells, Nets,
|
|
* Occurences, ...) are GenericCollections (the type Nets being
|
|
* defined by GenericCollection\<Net*\>), the previous sequence
|
|
* is still simpler and becomes:
|
|
\code
|
|
Nets nets = cellGetExternalNets();
|
|
...
|
|
// use
|
|
...
|
|
\endcode
|
|
* Furthermore a generic collection being able to get any other
|
|
* collection, provided it handles the same type of elements,
|
|
* you may well write:
|
|
\code
|
|
Nets nets;
|
|
|
|
nets = cellGetExternalNets();
|
|
...
|
|
// use
|
|
...
|
|
|
|
// and somewhere later, with the same variable
|
|
nets = cellGetNets();
|
|
...
|
|
// use
|
|
...
|
|
\endcode
|
|
*
|
|
*
|
|
* \section secGenericCollectionRemark Remark
|
|
*
|
|
* When writing the following code :
|
|
\code
|
|
Collection<Net*>* nets = cellGetExternalNets().GetClone();
|
|
...
|
|
// use
|
|
...
|
|
delete nets;
|
|
\endcode
|
|
* If an exception happens in the use phase, the nets variable
|
|
* will never be released. This is not critical in most cases,
|
|
* but may become dramatic in some other ones : notably within
|
|
* graphic display phases where frequent interruptions may
|
|
* occur.
|
|
*
|
|
* On the other hand, when writting:
|
|
\code
|
|
GenericCollection<Net*> nets = cellGetExternalNets();
|
|
...
|
|
// use
|
|
...
|
|
\endcode
|
|
* If an exception occurs within the usage phase, the nets
|
|
* variable will be deleted as well as the allocated clone.
|
|
*
|
|
*
|
|
* \section secGenericCollectionDestruction Destruction
|
|
*
|
|
* When the generic collection is deleted, the clone (if any) is
|
|
* then deleted.
|
|
*
|
|
*
|
|
* \section secGenericCollectionRemark Remark
|
|
*
|
|
* On the following example you can see an interesting effect.
|
|
* We get two different Nets objects which represent the same
|
|
* set of nets. Any modification on the elements of one set has
|
|
* immediate repercussion on the elements of the other.
|
|
\code
|
|
Cell* cell = ...; // we get a cell
|
|
|
|
if (cell) {
|
|
|
|
Nets nets1 = cellGetNets();
|
|
Nets nets2 = cellGetNets();
|
|
|
|
for_each_net(net, nets1) netDelete(); end_for;
|
|
|
|
assert(nets1.IsEmpty());
|
|
assert(nets2.IsEmpty());
|
|
}
|
|
\endcode
|
|
* Therefore we can get the set of all nets of a cell at program
|
|
* begining, this set will remain, even after many cell changes,
|
|
* the set of nets of that cell (as much as, of course, the cell
|
|
* is not destroyed).
|
|
*/
|
|
|
|
|
|
|
|
/*! \typedef GenericCollection::Inherit
|
|
* Useful for calling methods on the base class without knowing
|
|
* it.
|
|
*/
|
|
|
|
|
|
/*! \function GenericCollection<Type>::GenericCollection();
|
|
* Default constructor : The generic collection is unbound and
|
|
* therefore empty.
|
|
*/
|
|
|
|
/*! \function GenericCollection<Type>::GenericCollection(const Collection<Type>& collection);
|
|
* Standard constructor: the generic collection is initialized
|
|
* with a clone of \c \<collection\> (which may be empty).
|
|
*/
|
|
|
|
/*! \function GenericCollection<Type>::GenericCollection(Collection<Type>* collection);
|
|
* Standard constructor: the generic collection is here directly
|
|
* initialized with the collection (pointer) and not with a
|
|
* clone of it.
|
|
*
|
|
* \important In consequence this collection will be automatically
|
|
* destroyed by the generic collection when time comes. This may
|
|
* be useful when some collection clone has been created and
|
|
* needs to be automatically deleted, allocating it to a generic
|
|
* collection which will manage that.
|
|
*
|
|
* \remark You can do that only once ... else you get in trouble.
|
|
*/
|
|
|
|
/*! \function GenericCollection<Type>::GenericCollection(const GenericCollection<Type>& genericCollection);
|
|
* Copy constructor: the generic collection is here initialized
|
|
* with a clone of genericCollection (which, here also, may be
|
|
* empty).
|
|
*/
|
|
|
|
|
|
/*! \function GenericCollection<Type>& GenericCollection::operator=(const Collection<Type>& collection);
|
|
* Assignment operator : if the generic collection was bound to
|
|
* a clone, this one is first deleted and then a new clone of
|
|
* \c \<collection\> is allocated (which will be deleted when
|
|
* time comes either by a new assignment or by the generic
|
|
* collection deletion).
|
|
*/
|
|
|
|
/*! \function GenericCollection<Type>& GenericCollection::operator=(Collection<Type>* collection);
|
|
* Assignment operator : The behaviour is identical to the
|
|
* standard assignment, but it's the \c \<collection\>
|
|
* collection itself which is bound to the generic collection
|
|
* and not a clone.
|
|
*
|
|
* \important This \<collection> will be automatically deleted when the
|
|
* time comes.
|
|
*
|
|
* \remark Here, again, you can do that only once ...
|
|
*/
|
|
|
|
}
|