Question

Alternatively, a user might wish to do a time-ordered traversal i.e. a time-based examination of values of several objects. This can be done by using a collection. The first step is to create a traverse collection of type vpiTrvsCollection of the objects to be traversed from the design object collection of type vpiObjCollection using vpi_handle() with a vpiTrvsCollection type and collection handle argument.

vpi_goto() can then be called on the traverse collection to move to next or previous or do jump in time for the collection as a whole. A move to next (previous) VC means move to the next (previous) earliest VC among the objects in the collection; any traverse handle that does not have any VC is ignored; on return its new handle points to the same place as its old. A jump to a specific time aligns the new returned handles of all the objects in the collection (as if this had been done object by object, but here it is done in one-shot for all elements).

It is possible to loop in time by incrementing the time, and doing a jump to those time increments. This is shown in the following code snippet.

vpiHandle objCollection = ...;
vpiHandle trvsCollection;
p_vpi_time time_p;
PLI_INT32 code;
/* Obtain (create) traverse collection from object collection */
trvsCollection = vpi_handle(vpiTrvsCollection, objCollection);
/* Loop in time: increments of 100 units */
for (i = 0; i < 1000; i = i + 100) {
    time_p = ...;
    /* Go to point in time */
    trvsCollection = vpi_goto(vpiTime, trvsCollection, time_p, &code);
    ...
}

Alternatively, the user might wish to get a new collection returned of all the objects that have a value change at the given time the traverse collection was moved to. In this case vpi_filter() follows the call to vpi_goto(). The latter returns a new collection with all the new traverse objects, whether they have a VC or not. vpi_filter() allows us to filter the members that have a VC at that time. This is shown in the code snippet that follows.

...
vpiHandle rettrvsCollection; /* Collection for all the objects */
vpiHandle vctrvsCollection; /* collection for the objects with VC */
vpiHandle itr; /* collection member iterator */
...
/* Go to earliest next VC in the collection */
for (;;) { /* for all collection VCs in time */
rettrvsCollection = vpi_goto(vpiNextVC, trvsCollection, NULL, &code);
if (!code) {
/* failure (e.g. already at MaxTime or no more VCs) */
break; /* cannot go further */
}
vctrvsCollection = vpi_filter(rettrvsCollection, vpiHasVC, 1);
/* create iterator then scan the VC collection */
itr = vpi_iterate(vpiMember, vctrvsCollection);
while (vc_trvs1_hdl = vpi_scan(itr)) {
/* Element has a VC */
vpi_get_value(vc_trvs1_hdl, value_p); /* VC data */
/* Do something at this VC point */
...
}
...
}