SystemVerilog Class Handle

A class variable such as pkt is only a name by which an object is known — it can hold the handle to an object of a class, but until it's assigned something, it is always null. This article looks closely at the difference between a handle and the object it points to, what happens when two handles point to the same object, and how to build arrays of objects using fixed, dynamic, and associative arrays.

7 min read | Intermediate Level

What You'll Learn

• The difference between a class handle and a class object
• Why accessing a property through a null handle causes a runtime error
• What happens when two handles are assigned to the same object
• How to build fixed, dynamic, and associative arrays of class objects

What Is a Class Handle?

When you declare a variable of a class type, SystemVerilog does not create an object — it only creates a handle, a reference that can later point to an object. Until that handle is assigned the result of a new() call, it points to nothing, and its value is null.

// Create a new class with a single member called
// count that stores integer values
class Packet;
	int count;
endclass

module tb;
  	// Create a "handle" for the class Packet that can point to an
  	// object of the class type Packet
  	// Note: This "handle" now points to NULL
	Packet pkt;
  
  	initial begin
      if (pkt == null)
        $display ("Packet handle 'pkt' is null");
  
      // Display the class member using the "handle"
      // Expect a run-time error because pkt is not an object
      // yet, and is still pointing to NULL. So pkt is not
      // aware that it should hold a member
      $display ("count = %0d", pkt.count);
  	end
endmodule

Output

ncsim> run
Packet handle 'pkt' is null
count = ncsim: *E,TRNULLID: NULL pointer dereference.
          File: ./testbench.sv, line = 18, pos = 33
         Scope: tb
          Time: 0 FS + 0

./testbench.sv:18       $display ("count = %0d", pkt.count);
ncsim> exit

Accessing a property or method through a handle that is still null is one of the most common simulation errors in SystemVerilog — reported as a null pointer dereference (or "null object access"). The fix is always the same: make sure new() has been called before the handle is used.

null is a keyword, not a string. Comparing a handle to the literal text "null" is a type mismatch and will not compile — always compare with pkt == null.

What Is a Class Object?

An instance of a class is created only when its new() function is invoked. To reference that object again later, you assign its handle to a variable of the matching class type.

// Create a new class with a single member called
// count that stores integer values
class Packet;
	int count;
endclass

module tb;
  	// Create a "handle" for the class Packet that can point to an
  	// object of the class type Packet
  	// Note: This "handle" now points to NULL
	Packet pkt;
  
  	initial begin
      if (pkt == null)
        $display ("Packet handle 'pkt' is null");
  
      // Call the new() function of this class
      pkt = new();
  
      if (pkt == null)
        $display ("What's wrong, pkt is still null ?");
      else
        $display ("Packet handle 'pkt' is now pointing to an object, and not NULL");
  
      // Display the class member using the "handle"
      $display ("count = %0d", pkt.count);
  	end
endmodule

Output

ncsim> run
Packet handle 'pkt' is null
Packet handle 'pkt' is now pointing to an object, and not NULL
count = 0
ncsim: *W,RNQUIE: Simulation is complete.

Notice that count prints as 0 even though it was never explicitly assigned. SystemVerilog initializes integer-type class properties to their default value (0 for int) at the moment the object is constructed, the same way module-level variables default to a known value.

What Happens When Two Handles Point to the Same Object?

If you assign one handle to another, the second handle does not get its own copy of the object — it simply starts pointing to the same memory as the first.

// Create a new class with a single member called
// count that stores integer values
class Packet;
	int count;
endclass

module tb;
  	// Create two "handles" for the class Packet
  	// Note: These "handles" now point to NULL
	Packet pkt, pkt2;
  
  	initial begin

  
      // Call the new() function of this class and
      // assign the member some value
      pkt = new();
      pkt.count = 16'habcd;
  
      // Display the class member using the "pkt" handle
      $display ("[pkt] count = 0x%0h", pkt.count);
  
      // Make pkt2 handle to point to pkt and print member variable
      pkt2 = pkt;
      $display ("[pkt2] count = 0x%0h", pkt2.count);
  	end
endmodule

Output

ncsim> run
[pkt] count = 0xabcd
[pkt2] count = 0xabcd
ncsim: *W,RNQUIE: Simulation is complete.

Now pkt and pkt2 both point to the same instance of Packet. This is because pkt2 = pkt did not create a new object — it only copied the handle, so both names now refer to the same memory. If you changed pkt2.count after this point, reading pkt.count would show the new value too, since there's only one object behind both names.

This handle-copy behavior is exactly why SystemVerilog provides a separate copy() convention (often hand-written, or via the built-in shallow-copy method) when you actually want a second, independent object with the same property values rather than two names for the same one.

Arrays of Class Objects

Just like a single class variable, each element of an array of class objects is its own handle, and starts out as null until it's individually constructed with new().

Fixed Array

A fixed-size array, also known as a static array, is declared with a specific size at compile time. In this example, fixed_array can hold exactly 5 Packet objects, and that size is locked in when the code compiles.

Packet fixed_array [5]; // Declares a fixed array of 5 Packet objects

// Define the Packet class
class Packet;
    int count;
    // Constructor to initialize count
    function new(int c = 0);
        count = c;
    endfunction
endclass

module tb;

    // Declare a fixed array of Packet objects
    Packet fixed_array[5];

    initial begin
        $display("--- Fixed Array Example ---");

        // Initialize each element of the fixed array
        for (int i = 0; i < 5; i++) begin
            fixed_array[i] = new(i * 10); // Create a new Packet object and assign it
        end

        // Access and display data from the fixed array
        for (int i = 0; i < 5; i++) begin
            $display("fixed_array[%0d].count = %0d", i, fixed_array[i].count);
        end

        // Example of accessing a null element if not initialized (would cause an error if dereferenced)
        // assert(fixed_array[0] != null); // Check if initialized
    end

endmodule

Output

xcelium> run
--- Fixed Array Example ---
fixed_array[0].count = 0
fixed_array[1].count = 10
fixed_array[2].count = 20
fixed_array[3].count = 30
fixed_array[4].count = 40
xmsim: *W,RNQUIE: Simulation is complete.  

Dynamic Array

A dynamic array is declared without a specific size and can grow or shrink at runtime. You allocate it using the new[size] syntax.

Packet   dynamic_array[];       // Declares a dynamic array of Packet objects
dynamic_array = new[10];        // Initializes the array with a size of 10

Here, dynamic_array starts out empty. The call to new[10] allocates space for 10 handles, each of which still needs its own new() call before it points to an actual Packet object.

module tb;

    initial begin
        // Declare a dynamic array of Packet objects
        Packet dynamic_array[];

        $display("--- Dynamic Array Example ---");

        // Initialize the dynamic array with a specific size
        dynamic_array = new[3]; // Creates space for 3 Packet references

        // Initialize each element of the dynamic array
        for (int i = 0; i < dynamic_array.size(); i++) begin
            dynamic_array[i] = new(i + 1); // Create new Packet objects
        end

        // Access and display data
        foreach (dynamic_array[i]) begin
            $display("dynamic_array[%0d].count = %0d", i, dynamic_array[i].count);
        end
    end

endmodule  

Output

xcelium> run

--- Dynamic Array Example ---
dynamic_array[0].count = 1
dynamic_array[1].count = 2
dynamic_array[2].count = 3
xmsim: *W,RNQUIE: Simulation is complete.  

Associative Array

An associative array uses a key, rather than a numerical index, to access elements. The key can be an integer, a string, or another data type, and the array only stores elements that have been explicitly added.

Packet assoc_array[*];           // Declares an associative array of Packet objects
assoc_array[100] = new;          // Adds a Packet object with key 100
assoc_array["header"] = new;     // Adds a Packet object with key "header"

Here, assoc_array is declared with a wildcard index [*], so it can be indexed by any integral expression. The integer 100 is used directly, and the string literal "header" is automatically cast to a bit vector of equivalent size, so it is still an integral key. Non-integral index values are illegal for a wildcard array, and an associative array has only one index type, declared once; to use real string keys, declare it as Packet assoc_array[string], as in the example below. This is useful when the range of indices isn't known up front, or when you want to associate an object with a meaningful label instead of a plain number.

module tb;

    // Declare an associative array where the key is a string and the value is a Packet object
    Packet assoc_array[string];

    initial begin
        $display("--- Associative Array Example ---");

        // Assign Packet objects to the associative array using string keys
        assoc_array["packet_A"] = new(50);
        assoc_array["packet_B"] = new(75);
        assoc_array["packet_C"] = new(100);

        // Access and display data using keys
        $display("assoc_array[\"packet_A\"].count = %0d", assoc_array["packet_A"].count);
        $display("assoc_array[\"packet_C\"].count = %0d", assoc_array["packet_C"].count);

        // Iterate through the associative array (order is not guaranteed unless specified)
      foreach (assoc_array[k]) begin
            $display("Key: %s, Count: %0d", k, assoc_array[k].count);
        end

        // Check if a key exists
        if (assoc_array.exists("packet_B")) begin
            $display("Packet_B exists in the associative array.");
        end
    end

endmodule  

Output

xcelium> run

--- Associative Array Example ---
assoc_array["packet_A"].count = 50
assoc_array["packet_C"].count = 100
Key: packet_A, Count: 50
Key: packet_B, Count: 75
Key: packet_C, Count: 100
Packet_B exists in the associative array.
xmsim: *W,RNQUIE: Simulation is complete.  

The foreach loop above happens to iterate in insertion order in this run, but the code's own comment is correct to caution that associative array iteration order isn't formally guaranteed — don't rely on it matching insertion order.

Common Beginner Mistakes

class Packet;
    int count;
    function new (int c = 0);
        count = c;
    endfunction
endclass

module tb;
    Packet pkt, pkt_alias, pkt_copy;

    initial begin
        pkt = new (5);
        pkt_alias = pkt;        // Same object as pkt
        pkt_copy  = new (5);    // A separate, independent object

        pkt.count = 99;

        $display ("pkt.count       = %0d", pkt.count);
        $display ("pkt_alias.count = %0d", pkt_alias.count);
        $display ("pkt_copy.count  = %0d", pkt_copy.count);
    end
endmodule