Question

In order to read data efficiently, it can be necessary to specify a group of objects. For example, when traversing data a user might wish to specify a list of objects to be marked as targets of data traversal. To do this grouping requires the notion of a collection. A collection represents a user-defined collection of VPI handles. The collection is an ordered list of VPI handles. The vpiType of a collection handle can be vpiCollection, vpi-ObjCollection, or vpiTrvsCollection:

• A collection of type vpiCollection is a general collection of VPI handles of objects of any type.
• The collection object of type vpiObjCollection represents a collection of VPI traversable objects in the design.
• A vpiTrvsCollection is a collection of traverse objects of type vpiTrvsObj.

The usage here in the read API is of either:

• Collections of traversable design objects: Used for example in vpi_handle() to create traverse handles for the collection. A collection of traversable design objects is of type vpiObjCollection (the elements can be any object type in the design except traverse objects of type vpiTrvsObj).
• Collections of data traverse objects: Used for example in vpi_goto() to move the traverse handles of all the objects in the collection (all are of type vpiTrvsObj). A collection of traverse objects is a vpiTrvsCollection.

The collection contains a set of member VPI objects and can take on an arbitrary size. The collection can be created at any time and existing objects can be added to it. The reader implementation can perform a type check on the items being added to the collection and generate an error if the item added does not belong to the allowed vpiType.

The purpose of a collection is to group design objects and permit operating on each element with a single operation applied to the whole collection group. vpi_iterate(vpiMember, <collection_handle>) is used to create a member iterator. vpi_scan() can then be used to scan the iterator for the elements of the collection.

A collection object is created with vpi_create(). The first call provides NULL handles to the collection object and the object to be added. Following calls, which can be performed at any time, provide the collection handle and a handle to the object for addition. The return argument is a handle to the collection object.

For example:

vpiHandle designCollection;
vpiHandle designObj;
vpiHandle trvsCollection;
vpiHandle trvsObj;
/* Create a collection of design objects */
designCollection = vpi_create(vpiObjCollection, NULL, NULL);
/* Add design object designObj into it */
designCollection = vpi_create(vpiObjCollection, designCollection, designObj);
/* Create a collection of traverse objects*/
trvsCollection = vpi_create(vpiTrvsCollection, NULL, NULL);
/* Add traverse object trvsObj into it */
trvsCollection = vpi_create(vpiTrvsCollection, trvsCollection, trvsObj);

Sometimes it is necessary to filter a collection and extract a set of handles which meet, or do not meet, a specific criterion for a given collection. The function vpi_filter() can be used for this purpose in the form of:

vpiHandle colFilterHdl = vpi_filter((vpiHandle) colHdl, (PLI_INT32)
filterType, (PLI_INT32) flag);

The first argument of vpi_filter(), colHdl, shall be the collection on which to apply the filter operation. The second argument, filterType can be any vpiType or VPI boolean property. This argument is the criterion used for filtering the collection members. The third argument, flag, is a boolean value. If set to TRUE, vpi_filter() shall return a collection of handles which match the criterion indicated by filterType, if set to FALSE, vpi_filter() shall return a collection of handles which do not match the criterion indicated by filterType. The original collection passed as a first argument remains unchanged.

A collection object exists from the time it is created until its handle is released. It is the application’s responsibility to keep a handle to the created collection, and to release it when it is no longer needed.