Function dqcsim::bindings::dqcs_gm_add_custom

#[no_mangle]pub extern "C" fn dqcs_gm_add_custom(
    gm: dqcs_handle_t, 
    key_free: Option<extern "C" fn(key_data: *mut c_void)>, 
    key_data: *mut c_void, 
    detector: Option<extern "C" fn(user_data: *const c_void, gate: dqcs_handle_t, qubits: *mut dqcs_handle_t, param_data: *mut dqcs_handle_t) -> dqcs_bool_return_t>, 
    detector_user_free: Option<extern "C" fn(user_data: *mut c_void)>, 
    detector_user_data: *mut c_void, 
    constructor: Option<extern "C" fn(user_data: *const c_void, qubits: dqcs_handle_t, param_data: dqcs_handle_t) -> dqcs_handle_t>, 
    constructor_user_free: Option<extern "C" fn(user_data: *mut c_void)>, 
    constructor_user_data: *mut c_void
) -> dqcs_return_t

Adds a fully customizable gate mapping to the given gate map. >

Note that this is the only type of mapping that can handle custom/named gates.

detector is the detector function pointer. It is optional; if null, this mapping only supports construction. detector_user_free is an optional callback function used to free detector_user_data when the gate map is destroyed, when this function fails, or when detector was null. detector_user_data is a user-specified value that is passed to the detector callback function. It is not used by DQCsim. constructor is the constructor function pointer. It is optional; if null, this mapping only supports detection. constructor_user_free is an optional callback function used to free constructor_user_data when the gate map is destroyed, when this function fails, or when constructor was null. constructor_user_data is a user-specified value that is passed to the constructor callback function. It is not used by DQCsim.

If both constructor and detector are null for some reason, the function is no-op (besides possibly calling the *_free() callbacks.

The detector callback receives the complete gate passed to the gate map for it to match as it pleases. If the gate matches, the detector function must return DQCS_TRUE. It may assign qubits to a qbset object representing the qubit arguments (substituted with an empty set if it doesn't), and may assign param_data to an arb handle with the parameterization data (if it doesn't, the data from the gate is used; if this was modified by the callback, the modified data is used). If the gate doesn't match, it must return DQCS_FALSE. If an error occurs, it must call dqcs_error_set() with the error message and return DQCS_BOOL_FAILURE.

The constructor callback performs the reverse operation. It receives an ArbData handle containing the parameterization data and a qubit set, and must construct a gate based on this information. If construction succeeds, the constructor function must return the gate handle. If an error occurs, it must call dqcs_error_set() with the error message and return 0.

It is up to the user how to do the matching and constructing, but the converter functions must always return the same value for the same input. In other words, they must be pure functions. Otherwise, the caching behavior of the GateMap will make the results inconsistent.