API reference - Class GenericNetlistCompareLogger

Notation used in Ruby API documentation

Module: db

Description: An event receiver for the netlist compare feature.

Class hierarchy: GenericNetlistCompareLogger » NetlistCompareLogger

The NetlistComparer class will send compare events to a logger derived from this class. Use this class to implement your own logger class. You can override on of it's methods to receive certain kind of events. This class has been introduced in version 0.26.

Public methods

void_createEnsures the C++ object is created
void_destroyExplicitly destroys the object
[const]bool_destroyed?Returns a value indicating whether the object was already destroyed
[const]bool_is_const_object?Returns a value indicating whether the reference is a const reference
void_manageMarks the object as managed by the script side.
void_unmanageMarks the object as no longer owned by the script side.
[virtual]voidbegin_circuit(const Circuit ptr a,
const Circuit ptr b)
This function is called when a new circuit is compared.
[virtual]voidbegin_netlist(const Netlist ptr a,
const Netlist ptr b)
This function is called at the beginning of the compare process.
[virtual]voidcircuit_mismatch(const Circuit ptr a,
const Circuit ptr b,
string msg)
This function is called when circuits can't be compared.
[virtual]voidcircuit_skipped(const Circuit ptr a,
const Circuit ptr b,
string msg)
This function is called when circuits can't be compared.
[virtual]voiddevice_class_mismatch(const DeviceClass ptr a,
const DeviceClass ptr b,
string msg)
This function is called when device classes can't be compared.
[virtual]voiddevice_mismatch(const Device ptr a,
const Device ptr b,
string msg)
This function is called when two devices can't be paired.
[virtual]voidend_circuit(const Circuit ptr a,
const Circuit ptr b,
bool matching,
string msg)
This function is called at the end of the compare process.
[virtual]voidend_netlist(const Netlist ptr a,
const Netlist ptr b)
This function is called at the end of the compare process.
[virtual]voidmatch_ambiguous_nets(const Net ptr a,
const Net ptr b,
string msg)
This function is called when two nets are identified, but this choice is ambiguous.
[virtual]voidmatch_devices(const Device ptr a,
const Device ptr b)
This function is called when two devices are identified.
[virtual]voidmatch_devices_with_different_device_classes(const Device ptr a,
const Device ptr b)
This function is called when two devices are identified but have different device classes.
[virtual]voidmatch_devices_with_different_parameters(const Device ptr a,
const Device ptr b)
This function is called when two devices are identified but have different parameters.
[virtual]voidmatch_nets(const Net ptr a,
const Net ptr b)
This function is called when two nets are identified.
[virtual]voidmatch_pins(const Pin ptr a,
const Pin ptr b)
This function is called when two pins are identified.
[virtual]voidmatch_subcircuits(const SubCircuit ptr a,
const SubCircuit ptr b)
This function is called when two subcircuits are identified.
[virtual]voidnet_mismatch(const Net ptr a,
const Net ptr b,
string msg)
This function is called when a net can't be paired.
[virtual]voidpin_mismatch(const Pin ptr a,
const Pin ptr b,
string msg)
This function is called when two pins can't be paired.
[virtual]voidsubcircuit_mismatch(const SubCircuit ptr a,
const SubCircuit ptr b,
string msg)
This function is called when two subcircuits can't be paired.

Detailed description

_create

Signature: void _create

Description: Ensures the C++ object is created

Use this method to ensure the C++ object is created, for example to ensure that resources are allocated. Usually C++ objects are created on demand and not necessarily when the script object is created.

_destroy

Signature: void _destroy

Description: Explicitly destroys the object

Explicitly destroys the object on C++ side if it was owned by the script interpreter. Subsequent access to this object will throw an exception. If the object is not owned by the script, this method will do nothing.

_destroyed?

Signature: [const] bool _destroyed?

Description: Returns a value indicating whether the object was already destroyed

This method returns true, if the object was destroyed, either explicitly or by the C++ side. The latter may happen, if the object is owned by a C++ object which got destroyed itself.

_is_const_object?

Signature: [const] bool _is_const_object?

Description: Returns a value indicating whether the reference is a const reference

This method returns true, if self is a const reference. In that case, only const methods may be called on self.

_manage

Signature: void _manage

Description: Marks the object as managed by the script side.

After calling this method on an object, the script side will be responsible for the management of the object. This method may be called if an object is returned from a C++ function and the object is known not to be owned by any C++ instance. If necessary, the script side may delete the object if the script's reference is no longer required.

Usually it's not required to call this method. It has been introduced in version 0.24.

_unmanage

Signature: void _unmanage

Description: Marks the object as no longer owned by the script side.

Calling this method will make this object no longer owned by the script's memory management. Instead, the object must be managed in some other way. Usually this method may be called if it is known that some C++ object holds and manages this object. Technically speaking, this method will turn the script's reference into a weak reference. After the script engine decides to delete the reference, the object itself will still exist. If the object is not managed otherwise, memory leaks will occur.

Usually it's not required to call this method. It has been introduced in version 0.24.

begin_circuit

Signature: [virtual] void begin_circuit (const Circuit ptr a, const Circuit ptr b)

Description: This function is called when a new circuit is compared.

This compare procedure will run the netlist compare circuit vs. circuit in a bottom-up fashion. Before each circuit is compared, this method is called once with the circuits that are about to be compared. After the circuit has been compared, end_circuit will be called.

In some cases, the compare algorithm will decide that circuits can't be compared. This happens if for some or all subcircuits the pin assignment can't be derived. In this case, circuit_skipped will be called once instead of begin_circuit and end_circuit.

begin_netlist

Signature: [virtual] void begin_netlist (const Netlist ptr a, const Netlist ptr b)

Description: This function is called at the beginning of the compare process.

This method is called once when the compare run begins.

circuit_mismatch

Signature: [virtual] void circuit_mismatch (const Circuit ptr a, const Circuit ptr b, string msg)

Description: This function is called when circuits can't be compared.

This method is called when a circuit can't be mapped to a partner in the other netlist. In this case, this method is called with the one circuit and nil for the other circuit.

This method is called instead of begin_circuit and end_circuit.

circuit_skipped

Signature: [virtual] void circuit_skipped (const Circuit ptr a, const Circuit ptr b, string msg)

Description: This function is called when circuits can't be compared.

If there is a known circuit pair, but the circuits can be compared - for example because subcircuits can't be identified - this method will be called with both circuits.

This method is called instead of begin_circuit and end_circuit.

device_class_mismatch

Signature: [virtual] void device_class_mismatch (const DeviceClass ptr a, const DeviceClass ptr b, string msg)

Description: This function is called when device classes can't be compared.

This method is called when a device class can't be mapped to a partner in the other netlist. In this case, this method is called with the one device class and nil for the other class.

device_mismatch

Signature: [virtual] void device_mismatch (const Device ptr a, const Device ptr b, string msg)

Description: This function is called when two devices can't be paired.

This will report the device considered in a or b. The other argument is nil. See match_devices for details.

end_circuit

Signature: [virtual] void end_circuit (const Circuit ptr a, const Circuit ptr b, bool matching, string msg)

Description: This function is called at the end of the compare process.

The 'matching' argument indicates whether the circuits have been identified as identical. See begin_circuit for details.

end_netlist

Signature: [virtual] void end_netlist (const Netlist ptr a, const Netlist ptr b)

Description: This function is called at the end of the compare process.

This method is called once when the compare run ended.

match_ambiguous_nets

Signature: [virtual] void match_ambiguous_nets (const Net ptr a, const Net ptr b, string msg)

Description: This function is called when two nets are identified, but this choice is ambiguous.

This choice is a last-resort fallback to allow continuation of the compare procedure. It is likely that this compare will fail later. Looking for ambiguous nets allows deduction of the origin of this faulty decision. See match_nets for more details.

match_devices

Signature: [virtual] void match_devices (const Device ptr a, const Device ptr b)

Description: This function is called when two devices are identified.

If two devices are identified as a corresponding pair, this method will be called with both devices. If the devices can be paired, but the device parameters don't match, match_devices_with_different_parameters will be called instead. If the devices can be paired, but the device classes don't match, match_devices_with_different_device_classes will be called instead. If devices can't be matched, device_mismatch will be called with the one device considered and the other device being nil.

match_devices_with_different_device_classes

Signature: [virtual] void match_devices_with_different_device_classes (const Device ptr a, const Device ptr b)

Description: This function is called when two devices are identified but have different device classes.

See match_devices for details.

match_devices_with_different_parameters

Signature: [virtual] void match_devices_with_different_parameters (const Device ptr a, const Device ptr b)

Description: This function is called when two devices are identified but have different parameters.

See match_devices for details.

match_nets

Signature: [virtual] void match_nets (const Net ptr a, const Net ptr b)

Description: This function is called when two nets are identified.

If two nets are identified as a corresponding pair, this method will be called with both nets. If the nets can be paired, but this match is ambiguous, match_ambiguous_nets will be called instead. If nets can't be matched to a partner, net_mismatch will be called.

match_pins

Signature: [virtual] void match_pins (const Pin ptr a, const Pin ptr b)

Description: This function is called when two pins are identified.

If two pins are identified as a corresponding pair, this method will be called with both pins. If pins can't be matched, pin_mismatch will be called with the one pin considered and the other pin being nil.

match_subcircuits

Signature: [virtual] void match_subcircuits (const SubCircuit ptr a, const SubCircuit ptr b)

Description: This function is called when two subcircuits are identified.

If two subcircuits are identified as a corresponding pair, this method will be called with both subcircuits. If subcircuits can't be matched, subcircuit_mismatch will be called with the one subcircuit considered and the other subcircuit being nil.

net_mismatch

Signature: [virtual] void net_mismatch (const Net ptr a, const Net ptr b, string msg)

Description: This function is called when a net can't be paired.

This method will be called, if a net cannot be identified as identical with another net. The corresponding argument will identify the net and source netlist. The other argument will be nil.

In some cases, a mismatch is reported with two nets given. This means, nets are known not to match. Still the compare algorithm will proceed as if these nets were equivalent to derive further matches.

pin_mismatch

Signature: [virtual] void pin_mismatch (const Pin ptr a, const Pin ptr b, string msg)

Description: This function is called when two pins can't be paired.

This will report the pin considered in a or b. The other argument is nil. See match_pins for details.

subcircuit_mismatch

Signature: [virtual] void subcircuit_mismatch (const SubCircuit ptr a, const SubCircuit ptr b, string msg)

Description: This function is called when two subcircuits can't be paired.

This will report the subcircuit considered in a or b. The other argument is nil. See match_subcircuits for details.