構成と照会するメンバー関数#
ここでは、oneapi::mkl::dft 名前空間に属し、oneapi/mkl/dft.hpp (インクルードするファイル) で宣言されている descriptor クラス・テンプレートの照会メンバー関数 get_value について説明します。
namespace oneapi::mkl::dft {
template <precision prec, domain dom>
class descriptor {
using real_scalar_t = std::conditional_t<prec == precision::DOUBLE, double, float>;
public: // 転送ドメインの種類:
void get_value(config_param param, domain* value_ptr) const;
// 浮動小数点形式の場合:
void get_value(config_param param, precision* value_ptr) const;
// 整数値パラメーターの場合:
void get_value(config_param param, std::int64_t* value_ptr) const;
// 実数値パラメーターの場合:
void get_value(config_param param, real_scalar_t* value_ptr) const;
// ベクトル値パラメーターの場合:
void get_value(config_param param, std::vector<std::int64_t>* value_ptr) const;
// その他のパラメーター:
void get_value(config_param param, config_value* value_ptr) const;
// 非推奨の使用法。将来のリリースで削除される予定: [[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;
}
}簡潔にするため、先頭に付加された名前空間指定子 oneapi::mkl::dft は以下では省略されています。
get_value 関数を使用すると、oneMKL ユーザーは記descriptor オブジェクトの構成パラメーターに関連付けられた構成値を照会できます。すべての get_value 関数は、2 つの引数を必要とします。1 つ目は、照会する呼び出し元オブジェクトの構成パラメーター (config_param 列挙子として)、2 つ目は適切なパラメーター依存タイプ (以下に説明) の要素 (または複数の要素) へのポインターで、oneMKL はこのパラメーターに関連付けられた構成値を書き込むことができます。呼び出し descriptor オブジェクトは、構成と照会するメンバー関数の呼び出しによって変更されることはありません。
転送ドメインの種類を照会#
次のメンバー関数
template <precision prec, domain dom>
void descriptor<prec, dom>::get_value(config_param param, domain* value_ptr) const;ユーザーは、以下の表にある構成パラメーターの構成値を照会できます。
受け入れられる構成パラメーター |
oneMKLによって書き込まれた値 |
|---|---|
|
|
浮動小数点形式を照会#
次のメンバー関数
template <precision prec, domain dom>
void descriptor<prec, dom>::get_value(config_param param, precision* value_ptr) const;ユーザーは、以下の表にある構成パラメーターの構成値を照会できます。
受け入れられる構成パラメーター |
oneMKLによって書き込まれた値 |
|---|---|
|
|
整数値パラメーターの照会#
次のメンバー関数
template <precision prec, domain dom>
void descriptor<prec, dom>::get_value(config_param param, std::int64_t* value_ptr) const;ユーザーは、以下の表にある構成パラメーターの構成値を照会できます。
受け入れられる構成パラメーター |
oneMKLによって書き込まれた値 |
|---|---|
|
|
config_param::FORWARD_SCALE と config_param::BACKWARD_SCALE(例外を参照)
|
|
|
|
非推奨#
次の表にリストされているパラメーターは、以前は整数値のように値を照会するために受け入れられていました。このような使用法は、より安全でより適切なタイプの代替手段 (ベクトル値パラメータの場合は oneMKL による適切な入力検証を有効にする) を優先するために非推奨になりました。以下にリストされている構成パラメーターのいずれかを整数値であるかのように照会すると、実行時警告が発行されます。
受け入れられる構成パラメーター |
oneMKL によって書き込まれた値 |
|---|---|
|
|
|
|
|
|
実数数値パラメーターの照会#
次のメンバー関数
template <precision prec, domain dom>
void descriptor<prec, dom>::get_value(config_param param, real_scalar_t* value_ptr) const;ユーザーは、以下の表にある構成パラメーターの構成値を照会できます。
受け入れられる構成パラメーター |
oneMKLによって書き込まれた値 |
|---|---|
|
|
ベクトル数値パラメーターの照会#
次のメンバー関数
template <precision prec, domain dom>
void descriptor<prec, dom>::get_value(config_param param, std::vector<std::int64_t>* value_ptr) const;ユーザーは、以下の表にある構成パラメーターの構成値を照会できます。
受け入れられる構成パラメーター |
oneMKL によって書き込まれた値 |
必要なベクトルサイズ |
|---|---|---|
|
|
\(d\) |
|
|
\(d + 1\) |
すべての整数値の構成パラメーター |
|
\(1\) |
そのほかのパラメーターの照会#
次のメンバー関数
template <precision prec, domain dom>
void descriptor<prec, dom>::get_value(config_param param, config_value* value_ptr) const;ユーザーは、以下の表にある構成パラメーターの構成値を照会できます。
受け入れられる構成パラメーター |
oneMKLによって書き込まれた値 |
|---|---|
|
|
非推奨のサポート#
非推奨のメンバー関数
template <precision prec, domain dom>
void descriptor<prec, dom>::get_value(config_param param, size_t* value_ptr) const;上記で説明した std::int64_t* タイプの value_ptr を使用するメンバー関数と同じサポートを提供します。前者の関数を使用すると、コンパイル時に非推奨の警告が発生します。
非推奨のメンバー関数
template <precision prec, domain dom>
void descriptor<prec, dom>::get_value(config_param param, DFTI_CONFIG_VALUE* value_ptr) const;oneMKL C インターフェイスの DFTI_CONFIG_VALUE 列挙子 (oneMKL DPC++ インターフェイスでは非推奨) を使用して、以下の表の構成パラメーターの構成値を照会できるようになります。この関数を使用すると、コンパイル時に非推奨の警告が発生します。
受け入れられる構成パラメーター |
oneMKLによって書き込まれた値 |
|---|---|
|
|
非推奨のメンバー関数
template <precision prec, domain dom>
void descriptor<prec, dom>::get_value(config_param param, char* value_ptr) const;使用されている oneMKL のバージョンに関するテキスト情報を照会する以外の目的はありません。同じ情報は、MKL_Get_Version_String (mkl_service.h で宣言) で取得することもできます。
受け入れられる構成パラメーター |
oneMKL によって書き込まれる可能性のある値の範囲 |
|---|---|
|
|
非推奨の可変長引数メンバー関数
template <precision prec, domain dom>
void descriptor<prec, dom>::get_value(config_param param, ...) const;すべての構成パラメーターをサポートします。照会されるパラメーターに関係なく、この関数は 2 つの引数を必要とし、可変長引数リストから一意の引数を読み取る際に、以下の表に記載されているパラメーター依存のポインタータイプを想定します (該当する場合は、可変長引数のデフォルトの引数プロモーションの後)。このルーチンのすべての呼び出しは、想定されるポインタータイプの値 (上記に記載されているもの、非推奨かどうかに関係なく) と一致する適切な構成の照会メンバー関数に内部的にリダイレクトされます。この可変長メンバー関数を使用すると、コンパイル時および実行時に非推奨の警告が発行されます。
受け入れられる構成パラメーター |
想定されるポインタータイプ |
|---|---|
|
|
|
|
|
単精度 (倍精度) 記述子の場合は |
|
|
|
|
|
|
警告
可変長構成と照会するメンバー関数の使い方がドキュメントと異なる場合、動作は未定義になります。
例外#
設定を照会するメンバー関数は、以下をスローします
呼び出し元のオブジェクトに問題が見つかった場合は
std::runtime_error例外が発生します;呼び出し元のオブジェクトがコミットされていないのに、呼び出し元オブジェクトのコミットを必要とする構成パラメーターを照会した場合、
oneapi::mkl::uninitialized例外が発生します (例:config_param::WORKSPACE_BYTESまたはWORKSPACE_EXTERNAL_BYTES);照会されたパラメーターが呼び出し元オのブジェクトに実装されていない機能である場合、
oneapi::mkl::unimplemented例外が発生します (例: CPU コミットdescriptorのconfig_param::WORKSPACE_BYTESまたはWORKSPACE_EXTERNAL_BYTES)。次の場合、
oneapi::mkl::invalid_argument例外が発生します2 番目の引数が
nullptrである;照会されているパラメーターが拒否された (例: 2 番目の引数として使用されているポインタータイプと一致しない場合);
ベクトル値パラメーターの場合、
value_ptrが指すベクトルのサイズが要求どおりではない;返される構成値は、安全かつ正確に目的のタイプに変換できない場合。たとえば、整数値の構成パラメーターに固有の構成と照会するメンバー関数を使用して、偶然 \(0.5\) となるスケーリング係数を照会するなどです。