Struct Handle 

pub struct Handle { /* private fields */ }

Wrapper around a raw VPI object handle.

This type provides convenience helpers for common handle operations and iteration over child objects.

Implementations

impl Handle

pub fn register_cb<F>(&self, reason: CbReason, callback: F) -> Handle

where F: Fn(&CbData) + 'static,

Registers a callback associated with this handle.

Returns a callback handle that can be removed with remove_cb.

pub fn register_full_cb<F>(&self, reason: CbReason, callback: F) -> Handle

where F: Fn(&CbData) + 'static,

Registers a callback with persistent time/value registration buffers.

This variant populates t_cb_data.time and t_cb_data.value at registration time so simulators can write callback payloads through those pointers.

pub fn register_value_change_cb<F>( &self, value_type: ValueType, callback: F, ) -> Handle

where F: Fn(&CbData) + 'static,

Registers a value-change callback with an explicit value format.

Some simulators require t_cb_data.value.format to match the expected callback value encoding for cbValueChange callbacks. This helper sets that format during registration.

impl Handle

pub fn get_delays( &self, capacity: usize, time_type: DelayTimeType, ) -> Option<DelayData>

Reads delay values from an object using vpi_get_delays.

capacity controls how many delay entries are allocated for the C API. Use 1 for simple delays and 3 for min/typ/max delay sets.

pub fn put_delays(&self, data: &DelayData) -> bool

Writes delay values to an object using vpi_put_delays.

Returns false for null handles or when the delay count does not fit in the VPI ABI integer type.

impl Handle

pub fn null() -> Self

Creates a null handle.

pub fn is_null(&self) -> bool

Returns true if this handle is null.

pub fn as_raw(&self) -> vpiHandle

Returns the underlying raw VPI handle.

pub fn clear(&mut self)

Replaces the current handle with null.

This is used when ownership of the raw handle is not held by this type.

pub fn from_raw(raw: vpiHandle) -> Self

Constructs a Handle from a raw VPI handle pointer.

pub fn handle_by_name(name: &str) -> Self

Looks up a handle by hierarchical name.

Wraps vpi_handle_by_name. Pass a null handle as scope to resolve against the root (absolute hierarchical names). Returns a null handle when the name cannot be resolved.

pub fn handle_by_name_and_scope(name: &str, scope: &Handle) -> Self

Returns a handle located by name within a scope.

Passing Handle::null() as the scope will resolve the name against the root of the hierarchy.

Returns a null handle when the object is not found.

pub fn iterator(&self, typ: ObjectType) -> HandleIterator

Returns an iterator handle for objects of typ under this handle.

pub fn get(&self, typ: ObjectType) -> Self

Returns a related object handle selected by typ.

Returns a null handle when the relation is unavailable.

pub fn handle_by_index(&self, index: i32) -> Self

Returns a child handle by index.

Returns a null handle when index is out of range.

pub fn iterators<'a>( &'a self, typ: &'a [ObjectType], ) -> impl Iterator<Item = Handle> + 'a

Iterates across multiple object kinds and flattens all resulting handles.

pub fn get_multi(&self, typ: ObjectType, other: &Handle) -> Self

Returns a related object handle selected by typ using two reference handles.

This wraps vpi_handle_multi for APIs that require two source handles. Returns a null handle when this handle or other is null, or when the relation is unavailable.

pub fn handle_by_multi_index(&self, indices: impl AsRef<[i32]>) -> Self

Returns a child handle by multiple indices.

This wraps vpi_handle_by_multi_index and is used for multidimensional arrays. Returns a null handle when this handle is null, when indices is empty, when the index count exceeds VPI limits, or when no object exists at the requested index tuple.

pub fn multi_handle_traversal( &self, typ: ObjectType, indices: impl AsRef<[i32]>, ) -> Self

Convenience helper for multi-handle traversal.

First traverses to typ via vpi_handle, then resolves a multidimensional element with vpi_handle_by_multi_index.

impl Handle

pub fn get_i64(&self, property: Property) -> Option<i64>

Reads a numeric property using vpi_get64 and returns it as i64.

Returns None for null handles.

pub fn get_u64(&self, property: Property) -> Option<u64>

Reads a numeric property using vpi_get64 and returns it as u64.

Returns None for null handles or negative raw values.

pub fn get_u32(&self, property: Property) -> Option<u32>

Reads a numeric property and returns it as u32 when supported.

Returns None for null handles or unsupported properties.

pub fn get_str(&self, property: Property) -> Option<String>

Reads a string property when supported.

Returns None for null handles, unsupported properties, or invalid UTF-8.

pub fn get_bool(&self, property: Property) -> Option<bool>

Reads a boolean property when supported.

Returns None for null handles or unsupported properties.

pub fn get_direction(&self) -> Option<Direction>

Returns this object’s port direction, if available.

pub fn get_op_type(&self) -> Option<OpType>

Returns this object’s operation subtype, if available.

pub fn get_prim_type(&self) -> Option<PrimType>

Returns this object’s primitive subtype, if available.

pub fn get_tchk_type(&self) -> Option<TchkType>

Returns this object’s timing check subtype, if available.

pub fn get_const_type(&self) -> Option<ConstType>

Returns this object’s constant subtype, if available.

pub fn get_name(&self) -> Option<String>

Returns this object’s name, if available.

pub fn get_full_name(&self) -> Option<String>

Returns this object’s full hierarchical name, if available.

pub fn get_func_type(&self) -> Option<FuncType>

Returns this object’s function type, if available.

pub fn get_sys_func_type(&self) -> Option<SysFuncType>

Returns this object’s system function type, if available.

pub fn get_edge(&self) -> Option<Edge>

Returns this object’s edge mask, if available.

pub fn get_type(&self) -> Option<ObjectType>

Returns this object’s VPI object type.

pub fn get_index(&self) -> Option<i32>

Returns this object’s index value, if available.

pub fn get_left_range(&self) -> Option<i32>

Returns this object’s left range value, if available.

pub fn get_right_range(&self) -> Option<i32>

Returns this object’s right range value, if available.

pub fn get_packages(&self) -> Vec<Handle>

Available on crate feature sv only.

Iterates packages visible from this scope/root.

pub fn get_interfaces(&self) -> Vec<Handle>

Available on crate feature sv only.

Iterates interface instances visible from this scope/root.

pub fn get_programs(&self) -> Vec<Handle>

Available on crate feature sv only.

Iterates program instances visible from this scope/root.

pub fn get_virtual_interfaces(&self) -> Vec<Handle>

Available on crate feature sv only.

Iterates virtual interface variables visible from this scope/root.

pub fn is_randomized(&self) -> Option<bool>

Available on crate feature sv only.

Returns whether this object participates in randomization.

pub fn get_rand_type(&self) -> Option<RandType>

Available on crate feature sv only.

Returns the SystemVerilog randomization qualifier (rand, randc, etc.).

pub fn is_constraint_enabled(&self) -> Option<bool>

Available on crate feature sv only.

Returns whether this constraint object is enabled.

pub fn is_constraint_soft(&self) -> Option<bool>

Available on crate feature sv only.

Returns whether this constraint object is declared soft.

pub fn get_dist_type(&self) -> Option<DistType>

Available on crate feature sv only.

Returns distribution style metadata for distribution constraints.

pub fn get_constraints(&self) -> Vec<Handle>

Available on crate feature sv only.

Iterates class constraints reachable from this object.

pub fn get_constraint_ordering(&self) -> Vec<Handle>

Available on crate feature sv only.

Iterates constraint-ordering nodes (solve ... before ...) on this object.

pub fn get_constraint_items(&self) -> Vec<Handle>

Available on crate feature sv only.

Iterates constraint items for this constraint object.

pub fn get_solve_before(&self) -> Vec<Handle>

Available on crate feature sv only.

Iterates solve before edges under a constraint-ordering object.

pub fn get_solve_after(&self) -> Vec<Handle>

Available on crate feature sv only.

Iterates solve after edges under a constraint-ordering object.

pub fn get_distribution_items(&self) -> Vec<Handle>

Available on crate feature sv only.

Iterates distribution-item nodes (dist list entries).

pub fn get_typespec(&self) -> Option<Typespec>

Available on crate feature sv only.

Returns the typespec kind associated with this object, if any.

Calls vpi_handle(vpiTypespec, h) to obtain the typespec object and then reads its vpiType property to determine the concrete typespec variant.

pub fn member_iterator(&self) -> HandleIterator

Available on crate feature sv only.

Iterates class/struct members reachable from this object.

pub fn get_type_name(&self) -> Option<String>

Returns a human-readable type name for this object.

Resolution order:

1. Port unwrapping — if the object is a ObjectType::Port or ObjectType::PortBit, follows vpiLowConn (the internal signal) to obtain the underlying net or variable, then applies the remaining steps to that handle. Falls back to vpiHighConn when vpiLowConn is absent.
2. sv feature only — retrieves the associated typespec handle via vpi_handle(vpiTypespec, h) and returns its DefName (user-defined types such as structs, enums, typedefs) or Name if DefName is absent.
3. Attempts to classify the object as a known VarType and returns its Display string (e.g. "logic", "int").
4. Falls back to vpi_get_str(vpiType, h) which returns the raw VPI object-type string (e.g. "vpiNet", "vpiReg").

Returns None for null handles or when none of the above produce a valid string.

pub fn get_var_type(&self) -> Option<VarType>

Returns this object’s variable kind, if the handle refers to a variable.

Reads vpiType and maps the result to a VarType variant. Returns None for null handles or non-variable object types.

pub fn get_size(&self) -> Option<u32>

Returns this object’s size, i.e., number of elements, if available.

pub fn get_raw_property(&self, property: Property) -> Option<PLI_INT32>

Reads a numeric property using vpi_get and returns it as PLI_INT32.

Returns None for null handles.

To obtain specific types like u32, u64, or i64, use the corresponding methods: get_u32, get_u64, or get_i64.

To obtain other types use the corresponding methods.

pub fn is_port(&self) -> bool

Returns true if this object is a port or port bit.

impl Handle

pub fn get_time(&self) -> Option<Time>

Returns the current simulation time for this handle.

Returns None when called on a null handle.

impl Handle

pub fn put_value(&self, value: &Value) -> Handle

Writes a value to this handle using vpi_put_value with no delay.

Returns a null handle when this handle is null. Otherwise returns the event handle returned by the simulator (which may also be null).

pub fn put_value_scheduled( &self, value: &Value, time: Option<&Time>, delay: PutValueDelay, flags: &PutValueFlags, ) -> Handle

Writes a value to this handle using vpi_put_value with optional scheduling.

time is ignored when delay is PutValueDelay::NoDelay. Returns a null handle when this handle is null. Otherwise returns the event handle returned by the simulator (which may also be null).

pub fn put_int_value(&self, value: i32) -> Handle

Writes an integer value to this handle using vpi_put_value with no delay.

Returns a null handle when this handle is null. Otherwise returns the event handle returned by the simulator (which may also be null).

pub fn put_value_array(&self, values: impl AsRef<[Value]>) -> bool

Available on crate feature value_array only.

Writes an array of values to this handle using vpi_put_value_array.

The input slice must be homogeneous and currently supports integer, short integer, long integer, real, short real, and time values. Returns false for null handles or unsupported/mixed value slices.

pub fn put_value_array_with_flags( &self, values: impl AsRef<[Value]>, start_index: i32, flags: PutValueArrayFlags, ) -> bool

Available on crate feature value_array only.

Writes an array of values to this handle using vpi_put_value_array.

start_index selects the first array element to update. Returns false for null handles or unsupported/mixed value slices.

pub fn get_value(&self, format: ValueType) -> Option<Value>

Reads a value from this handle in the requested format.

If format is ValueType::ObjType, the simulator may override the requested format with the object’s native value format. In that case, this method returns the matching concrete Value variant rather than always returning Value::ObjType.

Returns None for null handles or unsupported formats.

pub fn get_value_array(&self, format: ValueType) -> Option<Vec<Value>>

Available on crate feature value_array only.

Retrieve an array of values from a Verilog object (e.g., memory array, packet array).

This function calls vpi_get_value_array to fetch multiple values at once. It handles various value formats and automatically allocates the necessary memory.

Arguments

• format - The format of values to retrieve (Int, Real, Time, etc.)

Returns

• Some(Vec<Value>) - A vector of retrieved values
• None - If the handle is null or the operation fails

Example

let mem = root.scan(vpi_sys::vpiMem)?;
if let Some(values) = mem.get_value_array(ValueType::Int) {
    for (i, val) in values.iter().enumerate() {
        println!("Memory[{}] = {}", i, val);
    }
}

pub fn is_array(&self) -> bool

Returns whether this handle represents an array object.

Trait Implementations

impl Clone for Handle

fn clone(&self) -> Handle

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Handle

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Handle

fn default() -> Self

Returns the “default value” for a type.

impl Drop for Handle

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl PartialEq for Handle

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.