Function dqcsim::bindings::dqcs_pdef_set_gate_cb

#[no_mangle]pub extern "C" fn dqcs_pdef_set_gate_cb(
    pdef: dqcs_handle_t, 
    callback: Option<extern "C" fn(user_data: *mut c_void, state: dqcs_plugin_state_t, gate: dqcs_handle_t) -> dqcs_handle_t>, 
    user_free: Option<extern "C" fn(user_data: *mut c_void)>, 
    user_data: *mut c_void
) -> dqcs_return_t

Sets the gate execution callback for operators and backends.

Besides the common arguments, the callback receives a handle to the to-be-executed gate. This is a borrowed handle; the caller will delete it.

The callback must return one of the following things:

• a valid handle to a measurement set, created using dqcs_mset_new() (this object is automatically deleted after the callback returns);
• a valid handle to a single qubit measurement, created using dqcs_meas_new() (this object is automatically deleted after the callback returns);
• the handle to the supplied gate, a shortcut for not returning any measurements (this is less clear than returning an empty measurement set, but slightly faster); or
• 0 to report an error, after calling the error string using dqcs_set_error().

Backend plugins must return a measurement result set containing exactly those qubits specified in the measurement set. For operators, however, the story is more complicated. Let's say we want to make a silly operator that inverts all measurements. The trivial way to do this would be to forward the gate, query all the measurement results using dqcs_plugin_get_measurement(), invert them, stick them in a measurement result set, and return that result set. However, this approach is not very efficient, because dqcs_plugin_get_measurement() has to wait for all downstream plugins to finish executing the gate, forcing the OS to switch threads, etc. Instead, operators are allowed to return only a subset (or none) of the measured qubits, as long as they return the measurements as they arrive through the modify_measurement() callback.

The default implementation for this callback for operators is to pass the gate through to the downstream plugin and return an empty set of measurements. Combined with the default implementation of modify_measurement(), this behavior is sane. Backends must override this callback; the default is to return a not-implemented error.

Note that for our silly example operator, the default behavior for this function is sufficient; you'd only have to override modify_measurement() to, well, modify the measurements.