Configuration-querying member functions

oneMKL - Data Parallel C++ Developer Reference

Download PDF

ID 772045

Date 10/31/2024

Version

Public

Visible to Intel only — GUID: GUID-BF219345-4515-4E71-9146-066E9C7F6564

View Details

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_paramenumerator), 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.

Behavior of the configuration-querying member function for the type of forward domain.
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.

Behavior of the configuration-querying member function for the floating-point format.
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.

Behavior of the configuration-querying member function for integer-valued parameters (using notations from the introduction).

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` (See the exceptions)	`value_ptr[0]`
`config_param::LENGTHS` if	`value_ptr[0]` (assigned )

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.

Behavior of the configuration-querying member function for integer-valued parameters, when used as deprecated (using notations from the introduction).

Accepted configuration parameter(s)	Value(s) written by oneMKL
`config_param::FORWARD_DOMAIN`, `config_param::PRECISION`, `config_param::COMPLEX_STORAGE`, `config_param::CONJUGATE_EVEN_STORAGE`, `config_param::PACKED_FORMAT`, `config_param::COMMIT_STATUS` and `config_param::DESTROY_INPUT`	`value_ptr[0]`
`config_param::LENGTHS` if	`value_ptr[0], value_ptr[1], ..., value_ptr[d-1]` (assigned , in that order)
`config_param::INPUT_STRIDES`, `config_param::OUTPUT_STRIDES`, `config_param::FWD_STRIDES` and `config_param::BWD_STRIDES`	`value_ptr[0], value_ptr[1], ..., value_ptr[d]` (assigned the queried documented in the page specific to configuring data layouts, in that order)

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.

Behavior of the configuration-querying member function for real-valued parameters.
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.

Behavior of the configuration-querying member function for vector-valued parameters (using notations from the introduction). In this table, std::int64_t* data = value_ptr->data(); is used.

Accepted configuration parameter(s)	Value(s) written by oneMKL	Required vector size
`config_param::LENGTHS`	`data[0], data[1], ..., data[d-1]` (assigned , in that order)
`config_param::INPUT_STRIDES`, `config_param::OUTPUT_STRIDES`, `config_param::FWD_STRIDES` and `config_param::BWD_STRIDES`	`data[0], data[1], ..., data[d]` (assigned the queried documented in the page specific to configuring data layouts, in that order)
All integer-valued configuration parameter	`data[0]`

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.

Behavior of the configuration-querying member function for parameters associated with `config_value` configuration values.
Accepted configuration parameters	Value written by oneMKL
`config_param::CONJUGATE_EVEN_STORAGE`, `config_param::PACKED_FORMAT`, `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]`

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.

Behavior of the configuration-querying member function for parameters associatable with a configuration value of type `DFTI_CONFIG_VALUE` (*deprecated*).
Accepted configuration parameters	Value written by oneMKL
`config_param::CONJUGATE_EVEN_STORAGE`, `config_param::PACKED_FORMAT`, `config_param::FORWARD_DOMAIN`, `config_param::PRECISION`, `config_param::COMPLEX_STORAGE`, `config_param::PLACEMENT`, `config_param::COMMIT_STATUS` and `config_param::DESTROY_INPUT`	`value_ptr[0]`

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).

Behavior of the configuration-querying member function for the only parameter associatable with a C-style string (*deprecated*).
Accepted configuration parameter	Range of values possibly written by oneMKL
`config_param::VERSION`	from `value_ptr[0]` to `value_ptr[DFTI_VERSION_LENGTH-1]` (`DFTI_VERSION_LENGTH` defined in `mkl_dfti.h`)

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.

Assumed pointer type considered by the variadic configuration-querying member function when reading its second argument, *i.e.*, the first in the list of variadic arguments.
Accepted configuration parameter(s)	Assumed pointer type
`config_param::DIMENSION`, `config_param::NUMBER_OF_TRANSFORMS`, `config_param::FWD_DISTANCE`, `config_param::BWD_DISTANCE`, `config_param::THREAD_LIMIT`, `config_param::LENGTHS`, `config_param::INPUT_STRIDES`, `config_param::OUTPUT_STRIDES`, `config_param::FWD_STRIDES` and `config_param::BWD_STRIDES`	`std::int64_t*`
`config_param::WORKSPACE_ESTIMATE_BYTES`, `config_param::WORKSPACE_BYTES` and `config_param::WORKSPACE_EXTERNAL_BYTES`	`size_t*`
`config_param::FORWARD_SCALE` and `config_param::BACKWARD_SCALE`	`float` (resp. `double`) for single-precision (resp. double-precision) descriptors
`config_param::WORKSPACE` and `config_param::WORKSPACE_PLACEMENT`	`config_value*`
`config_param::FORWARD_DOMAIN`, `config_param::PRECISION`, `config_param::COMPLEX_STORAGE`, `config_param::CONJUGATE_EVEN_STORAGE`, `config_param::PACKED_FORMAT`, `config_param::PLACEMENT`, `config_param::COMMIT_STATUS`, `config_param::DESTROY_INPUT`	`DFTI_CONFIG_VALUE*`
`config_param::VERSION`	`char*`

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 or WORKSPACE_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 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.

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

oneMKL - Data Parallel C++ Developer Reference

Configuration-querying member functions

Querying the type of forward domain

Querying the floating-point format

Querying integer-valued parameters

Querying real-valued parameters

Querying vector-valued parameters

Querying other parameters

Deprecated support

Exceptions