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;
// deprecated usage, will be removed in a future release:
[[deprecated("Use MKL_Get_Version_String(char*, int) instead.")]]
void get_value(config_param param, char* value_ptr) const;
[[deprecated("Use get_value(config_param, config_value*), "
"get_value(config_param, domain*) or "
"get_value(config_param, precision*) instead.")]]
void get_value(config_param param, DFTI_CONFIG_VALUE* value_ptr) const;
[[deprecated("Use get_value(config_param, std::int64_t*) instead.")]]
void get_value(config_param param, size_t* value_ptr) const;
[[deprecated("This get_value member function is deprecated.")]]
void get_value(config_param param, ...) 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 |
---|---|
|
|
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 |
---|---|
|
|
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::FORWARD_SCALE and config_param::BACKWARD_SCALE (See the exceptions)
|
|
|
|
Deprecations#
The parameters listed in the following table had been previously accepted for querying their values as if they were integer-valued. Such usage is now deprecated in favor of safer or more-appropriately-typed alternatives (enabling proper input validation by oneMKL in case of vector-valued parameters). Querying any of the configuration parameter listed below as if it was integer-valued triggers a runtime warning to be emitted.
Accepted configuration parameter(s) |
Value(s) written by oneMKL |
---|---|
|
|
|
|
|
|
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 |
---|---|
|
|
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 |
---|---|---|
|
|
\(d\) |
|
|
\(d + 1\) |
|
\(1\) |
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 |
---|---|
|
|
Deprecated support#
The deprecated member function
template <precision prec, domain dom>
void descriptor<prec, dom>::get_value(config_param param, size_t* value_ptr) const;
offers the same support as the member function using a value_ptr
of type std::int64_t*
documented above. Using the former function triggers a compile-time deprecation warning.
The deprecated member function
template <precision prec, domain dom>
void descriptor<prec, dom>::get_value(config_param param, DFTI_CONFIG_VALUE* value_ptr) const;
enables users to query the configuration value for the configuration parameters in the table below, using the oneMKL C interface’s DFTI_CONFIG_VALUE
enumerators that are now deprecated via the oneMKL DPC++ interface. Using this function triggers a compile-time deprecation warning.
Accepted configuration parameters |
Value written by oneMKL |
---|---|
|
|
The deprecated member function
template <precision prec, domain dom>
void descriptor<prec, dom>::get_value(config_param param, char* value_ptr) const;
serves no other purpose than querying textual information about the version of oneMKL being used. The very same information may be obtained via MKL_Get_Version_String
(declared in mkl_service.h
).
Accepted configuration parameter |
Range of values possibly written by oneMKL |
---|---|
|
from |
The deprecated variadic member function
template <precision prec, domain dom>
void descriptor<prec, dom>::get_value(config_param param, ...) const;
offers support for all configuration parameters. Regardless of the parameter being queried, this function requires exactly two arguments and assumes a parameter-dependent pointer type documented in the table below when reading the unique argument from the list of variadic arguments (after default argument promotions of variadic arguments, if applicable). Any call to this routine is redirected internally to the appropriate configuration-querying member function that is consistent with that assumed pointer type of value (among those documented above, deprecated or not). Using this variadic member function triggers compile-time and runtime deprecation warnings to be emitted.
Accepted configuration parameter(s) |
Assumed pointer type |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
Warning
The behavior of the variadic configuration-querying member function is undefined if its usage is not strictly as documented.
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
orWORKSPACE_EXTERNAL_BYTES
);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
orWORKSPACE_EXTERNAL_BYTES
for a CPU-committeddescriptor
);a
oneapi::mkl::invalid_argument
exception ifthe 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 \(0.5\) using the configuration-querying member function specific to integer-valued configuration parameters.