Fix: Memory leakage in QkCountOps creation. (backport Qiskit#14930) (Qiskit#14959)

* Fix: Memory leakage in `QkCountOps` creation. (Qiskit#14930)

* Fix: Memory leakage in `QkCountOps` creation.
The following commits attempt to fix some memoery issues that the struct `QkOpCounts`. The `qk_opcounts_free` method would segfault if an empty object was passed. The function now checks whether the passed option includes a null pointer or an empty instance. The commits also change how the `data` attribute is generated without using `std::mem::forget`, but instead collection the `OpCount` vec into a boxed_slice and consuming it into a `Box`. Inspired by what was done for Qiskit#14884.

* Docs: Add release note.

* Fix: Ironic memory leakage

* Fix c opcounts free suggestion (Qiskit#7)

* Rename to _clear, free name

* rm dangling file

* use pointers

* ... forgot to register test

* fix `size_t`

* Fix: Missed some renaming

* add note on clearing opscount

* be explicit about loading Box<[OpCount]>

* fix merge artifact

* Apply suggestions from code review

Co-authored-by: Eli Arbel <[email protected]>

* goto

* happy miri happy life

* Fix merge artifacts

---------

Co-authored-by: Julien Gacon <[email protected]>
Co-authored-by: Julien Gacon <[email protected]>
Co-authored-by: Eli Arbel <[email protected]>
(cherry picked from commit 28aa4bd)

# Conflicts:
#	test/c/test_elide_permutations.c
#	test/c/test_optimize_1q_sequences.c
#	test/c/test_sabre_layout.c
#	test/c/test_split_2q_unitaries.c

* rm merge artifacts

---------

Co-authored-by: Raynel Sanchez <[email protected]>
Co-authored-by: Julien Gacon <[email protected]>

Author: 3 people

crates/cext/src/circuit.rs

@@ -755,16 +755,22 @@ pub unsafe extern "C" fn qk_circuit_unitary(
 /// @ingroup QkCircuit
 /// Return a list of string names for instructions in a circuit and their counts.
 ///
+/// To properly free the memory allocated by the struct, you should call ``qk_opcounts_clear``.
+/// Dropping the ``QkOpCounts`` struct without doing so will leave the stored array of ``QkOpCount``
+/// allocated and produce a memory leak.
+///
 /// @param circuit A pointer to the circuit to get the counts for.
 ///
-/// @return An ``OpCounts`` struct containing the circuit operation counts.
+/// @return An ``QkOpCounts`` struct containing the circuit operation counts.
 ///
 /// # Example
 /// ```c
 ///     QkCircuit *qc = qk_circuit_new(100, 0);
 ///     uint32_t qubits[1] = {0};
 ///     qk_circuit_gate(qc, QkGate_H, qubits, NULL);
 ///     QkOpCounts counts = qk_circuit_count_ops(qc);
+///     // .. once done
+///     qk_opcounts_clear(&counts);
 /// ```
 ///
 /// # Safety
@@ -776,16 +782,18 @@ pub unsafe extern "C" fn qk_circuit_count_ops(circuit: *const CircuitData) -> Op
     // SAFETY: Per documentation, the pointer is non-null and aligned.
     let circuit = unsafe { const_ptr_as_ref(circuit) };
     let count_ops = circuit.count_ops();
-    let mut output: Vec<OpCount> = count_ops
-        .into_iter()
-        .map(|(name, count)| OpCount {
-            name: CString::new(name).unwrap().into_raw(),
-            count,
-        })
-        .collect();
-    let data = output.as_mut_ptr();
+    let output = {
+        let vec: Vec<OpCount> = count_ops
+            .into_iter()
+            .map(|(name, count)| OpCount {
+                name: CString::new(name).unwrap().into_raw(),
+                count,
+            })
+            .collect();
+        vec.into_boxed_slice()
+    };
     let len = output.len();
-    std::mem::forget(output);
+    let data = Box::into_raw(output) as *mut OpCount;
     OpCounts { data, len }
 }
 
@@ -993,7 +1001,7 @@ pub unsafe extern "C" fn qk_circuit_instruction_clear(inst: *mut CInstruction) {
 }
 
 /// @ingroup QkCircuit
-/// Free a circuit op count list.
+/// Clear the content in a circuit operation count list.
 ///
 /// @param op_counts The returned op count list from ``qk_circuit_count_ops``.
 ///
@@ -1002,14 +1010,29 @@ pub unsafe extern "C" fn qk_circuit_instruction_clear(inst: *mut CInstruction) {
 /// Behavior is undefined if ``op_counts`` is not the object returned by ``qk_circuit_count_ops``.
 #[no_mangle]
 #[cfg(feature = "cbinding")]
-pub unsafe extern "C" fn qk_opcounts_free(op_counts: OpCounts) {
-    // SAFETY: Loading data contained in OpCounts as a slice which was constructed from a Vec
-    let data = unsafe { std::slice::from_raw_parts_mut(op_counts.data, op_counts.len) };
-    let data = data.as_mut_ptr();
-    // SAFETY: Loading a box from the slice pointer created above
-    unsafe {
-        let _ = Box::from_raw(data);
+pub unsafe extern "C" fn qk_opcounts_clear(op_counts: *mut OpCounts) {
+    // SAFETY: The user guarantees the input is a valid OpCounts pointer.
+    let op_counts = unsafe { mut_ptr_as_ref(op_counts) };
+
+    if op_counts.len > 0 && !op_counts.data.is_null() {
+        // SAFETY: We load the box from a slice pointer created from
+        // the raw parts from the OpCounts::data attribute.
+        unsafe {
+            let slice: Box<[OpCount]> = Box::from_raw(std::slice::from_raw_parts_mut(
+                op_counts.data,
+                op_counts.len,
+            ));
+            // free the allocated strings in each OpCount
+            for count in slice.iter() {
+                if !count.name.is_null() {
+                    let _ = CString::from_raw(count.name as *mut c_char);
+                }
+            }
+            // the variable vec goes out of bounds and is freed too
+        }
     }
+    op_counts.len = 0;
+    op_counts.data = std::ptr::null_mut();
 }
 
 /// @ingroup QkCircuit

releasenotes/notes/c-api-ops-count-bug-f633d349de315e89.yaml

@@ -0,0 +1,6 @@
+---
+fixes:
+  - |
+    Fixed memory leakage issues during the creation of
+    a :cpp:struct:`QkOpCounts` instance and during any calls to
+    :cpp:func:`qk_opcounts_clear` whenever an empty instance is passed.

test/c/test_circuit.c

@@ -27,8 +27,17 @@ int test_empty(void) {
     uint32_t num_qubits = qk_circuit_num_qubits(qc);
     uint32_t num_clbits = qk_circuit_num_clbits(qc);
     size_t num_instructions = qk_circuit_num_instructions(qc);
+
+    QkOpCounts counts = qk_circuit_count_ops(qc);
+    size_t opcount = counts.len;
+
+    qk_opcounts_clear(&counts);
     qk_circuit_free(qc);
 
+    if (opcount != 0) {
+        printf("The operation count %zu is not 0", opcount);
+        return EqualityError;
+    }
     if (num_qubits != 0) {
         printf("The number of qubits %d is not 0", num_qubits);
         return EqualityError;
@@ -254,6 +263,45 @@ int test_gate_num_params(void) {
     return Ok;
 }
 
+/**
+ * Test edge cases for getting the op counts.
+ */
+int test_get_gate_counts(void) {
+    QkCircuit *qc = qk_circuit_new(3, 3);
+
+    // test empty circuit
+    int result = Ok;
+    QkOpCounts c1 = qk_circuit_count_ops(qc);
+    if (c1.len != 0) {
+        result = EqualityError;
+        qk_opcounts_clear(&c1);
+        goto circuit_cleanup;
+    }
+    qk_opcounts_clear(&c1);
+
+    // add some instructions
+    uint32_t qubits[2] = {1, 0};
+    double params[1] = {0.12};
+    qk_circuit_gate(qc, QkGate_CRX, qubits, params);
+    QkOpCounts c2 = qk_circuit_count_ops(qc);
+
+    if (c2.len != 1) {
+        result = EqualityError;
+        qk_opcounts_clear(&c1);
+        goto circuit_cleanup;
+    }
+    qk_opcounts_clear(&c2);
+
+    // check that after clearing, the object is still valid
+    if (c2.len != 0 || c2.data != NULL) {
+        result = EqualityError;
+    }
+
+circuit_cleanup:
+    qk_circuit_free(qc);
+    return result;
+}
+
 int test_get_gate_counts_bv_no_measure(void) {
     QkCircuit *qc = qk_circuit_new(1000, 1000);
     double *params = NULL;
@@ -304,7 +352,7 @@ int test_get_gate_counts_bv_no_measure(void) {
     }
 cleanup:
     qk_circuit_free(qc);
-    qk_opcounts_free(op_counts);
+    qk_opcounts_clear(&op_counts);
     return result;
 }
 
@@ -369,7 +417,7 @@ int test_get_gate_counts_bv_measures(void) {
     }
 cleanup:
     qk_circuit_free(qc);
-    qk_opcounts_free(op_counts);
+    qk_opcounts_clear(&op_counts);
     return result;
 }
 
@@ -443,13 +491,12 @@ int test_get_gate_counts_bv_barrier_and_measures(void) {
         goto cleanup;
     }
     if (op_counts.data[3].count != 2) {
-        return EqualityError;
         result = EqualityError;
         goto cleanup;
     }
 cleanup:
     qk_circuit_free(qc);
-    qk_opcounts_free(op_counts);
+    qk_opcounts_clear(&op_counts);
     return result;
 }
 
@@ -671,7 +718,7 @@ int test_get_gate_counts_bv_resets_barrier_and_measures(void) {
     }
 cleanup:
     qk_circuit_free(qc);
-    qk_opcounts_free(op_counts);
+    qk_opcounts_clear(&op_counts);
     return result;
 }
 
@@ -707,10 +754,10 @@ int test_unitary_gate(void) {
     if (op_counts.len != 1 || strcmp(op_counts.data[0].name, "unitary") != 0 ||
         op_counts.data[0].count != 1) {
         result = EqualityError;
-        qk_opcounts_free(op_counts);
+        qk_opcounts_clear(&op_counts);
         goto cleanup;
     }
-    qk_opcounts_free(op_counts);
+    qk_opcounts_clear(&op_counts);
 
     QkCircuitInstruction inst;
     qk_circuit_get_instruction(qc, 0, &inst);
@@ -755,10 +802,10 @@ int test_unitary_gate_1q(void) {
     if (op_counts.len != 1 || strcmp(op_counts.data[0].name, "unitary") != 0 ||
         op_counts.data[0].count != 1) {
         result = EqualityError;
-        qk_opcounts_free(op_counts);
+        qk_opcounts_clear(&op_counts);
         goto cleanup;
     }
-    qk_opcounts_free(op_counts);
+    qk_opcounts_clear(&op_counts);
 
     QkCircuitInstruction inst;
     qk_circuit_get_instruction(qc, 0, &inst);
@@ -809,10 +856,10 @@ int test_unitary_gate_3q(void) {
     if (op_counts.len != 1 || strcmp(op_counts.data[0].name, "unitary") != 0 ||
         op_counts.data[0].count != 1) {
         result = EqualityError;
-        qk_opcounts_free(op_counts);
+        qk_opcounts_clear(&op_counts);
         goto cleanup;
     }
-    qk_opcounts_free(op_counts);
+    qk_opcounts_clear(&op_counts);
     QkCircuitInstruction inst;
     qk_circuit_get_instruction(qc, 0, &inst);
     if (strcmp(inst.name, "unitary") != 0 || inst.num_clbits != 0 || inst.num_params != 0 ||
@@ -886,6 +933,7 @@ int test_circuit(void) {
     num_failed += RUN_TEST(test_circuit_copy);
     num_failed += RUN_TEST(test_circuit_copy_with_instructions);
     num_failed += RUN_TEST(test_no_gate_1000_bits);
+    num_failed += RUN_TEST(test_get_gate_counts);
     num_failed += RUN_TEST(test_get_gate_counts_bv_no_measure);
     num_failed += RUN_TEST(test_get_gate_counts_bv_measures);
     num_failed += RUN_TEST(test_get_gate_counts_bv_barrier_and_measures);