Configuration-querying member functions
This page describes the overloaded configuration-querying member functions get_value of the descriptor class template, which belongs to the oneapi::mkl::dft namespace and is declared in oneapi/mkl/dft.hpp (file to be included).
namespace oneapi::mkl::dft {
template <precision prec, domain dom>
class descriptor {
using real_scalar_t = std::conditional_t<prec == precision::DOUBLE, double, float>;
public:
// for the type of forward domain:
void get_value(config_param param, domain* value_ptr) const;
// for the floating-point format:
void get_value(config_param param, precision* value_ptr) const;
// for integer-valued parameters:
void get_value(config_param param, std::int64_t* value_ptr) const;
// for real-valued parameters:
void get_value(config_param param, real_scalar_t* value_ptr) const;
// for vector-valued parameters:
void get_value(config_param param, std::vector<std::int64_t>* value_ptr) const;
// for other parameters:
void get_value(config_param param, config_value* value_ptr) const;
}
}The usage of prepended namespace specifiers oneapi::mkl::dft is omitted below for conciseness.
The get_value functions enable oneMKL users to query the configuration value associated with a configuration parameter of a descriptor object. All get_value functions expect exactly two arguments: first the calling object’s configuration parameter to be queried (as a config_param enumerator), second a pointer to an element (or elements) of the appropriate parameter-dependent type (documented below) wherein oneMKL is allowed to write the configuration value associated with that parameter. The calling descriptor object is left unchanged by any call to a configuration-querying member function.
Querying the type of forward domain
The following member function
template <precision prec, domain dom>
void descriptor<prec, dom>::get_value(config_param param, domain* value_ptr) const;enables users to query the configuration value for the configuration parameter in the table below.
Accepted configuration parameter |
Value written by oneMKL |
|---|---|
config_param::FORWARD_DOMAIN |
value_ptr[0] (assigned dom) |
Querying the floating-point format
The following member function
template <precision prec, domain dom>
void descriptor<prec, dom>::get_value(config_param param, precision* value_ptr) const;enables users to query the configuration value for the configuration parameter in the table below.
Accepted configuration parameter |
Value written by oneMKL |
|---|---|
config_param::PRECISION |
value_ptr[0] (assigned prec) |
Querying integer-valued parameters
The following member function
template <precision prec, domain dom>
void descriptor<prec, dom>::get_value(config_param param, std::int64_t* value_ptr) const;enables users to query the configuration value for the configuration parameters in the table below.
Accepted configuration parameters |
Value written by oneMKL |
|---|---|
config_param::DIMENSION, config_param::NUMBER_OF_TRANSFORMS, config_param::PLACEMENT, config_param::FWD_DISTANCE, config_param::BWD_DISTANCE, config_param::THREAD_LIMIT, config_param::WORKSPACE_ESTIMATE_BYTES, config_param::WORKSPACE_BYTES and config_param::WORKSPACE_EXTERNAL_BYTES |
value_ptr[0] |
config_param::FORWARD_SCALE and config_param::BACKWARD_SCALE |
value_ptr[0] |
config_param::LENGTHS if |
value_ptr[0] (assigned |
)Querying real-valued parameters
The following member function
template <precision prec, domain dom>
void descriptor<prec, dom>::get_value(config_param param, real_scalar_t* value_ptr) const;enables users to query the configuration value for the configuration parameters in the table below.
Accepted configuration parameters |
Value written by oneMKL |
|---|---|
config_param::FORWARD_SCALE and config_param::BACKWARD_SCALE |
value_ptr[0] |
Querying vector-valued parameters
The following member function
template <precision prec, domain dom>
void descriptor<prec, dom>::get_value(config_param param, std::vector<std::int64_t>* value_ptr) const;enables users to query the configuration value for the configuration parameters in the table below.
Accepted configuration parameter(s) |
Value(s) written by oneMKL |
Required vector size |
|---|---|---|
config_param::LENGTHS |
data[0], data[1], ..., data[d-1] (assigned |
|
config_param::FWD_STRIDES and config_param::BWD_STRIDES |
data[0], data[1], ..., data[d] (assigned the queried |
|
data[0] |
|
, in that order)
documented in the page specific to 
Querying other parameters
The following member function
template <precision prec, domain dom>
void descriptor<prec, dom>::get_value(config_param param, config_value* value_ptr) const;enables users to query the configuration value for the configuration parameters in the table below.
Accepted configuration parameters |
Value written by oneMKL |
|---|---|
config_param::COMPLEX_STORAGE, config_param::PLACEMENT, config_param::WORKSPACE, config_param::WORKSPACE_PLACEMENT, config_param::COMMIT_STATUS, config_param::DESTROY_INPUT |
value_ptr[0] |
Exceptions
The configuration-querying member functions may throw
an std::runtime_error exception if an issue is found with the calling object;
a oneapi::mkl::uninitialized exception if the calling object is uncommitted yet queried about a configuration parameter that requires the calling object to be committed (e.g., config_param::WORKSPACE_BYTES or WORKSPACE_EXTERNAL_BYTES) or if the descriptor object has been moved-from and not reinitialized;
a oneapi::mkl::unimplemented exception if the queried parameter corresponds to a feature that is not implemented for the calling object (e.g., config_param::WORKSPACE_BYTES or WORKSPACE_EXTERNAL_BYTES for a CPU-committed descriptor);
a oneapi::mkl::invalid_argument exception if
the second argument is nullptr;
the parameter being queried is rejected, e.g., if it is inconsistent with the pointer type used as second argument;
the size of the vector pointed by value_ptr is not as required, for vector-valued-parameters;
the configuration value to be returned cannot be safely or accurately converted into the desired type, e.g., if querying a scaling factor that happens to be
using the configuration-querying member function specific to integer-valued configuration parameters.