外部に割り当てられたワークスペースを提供

外部に割り当てられたワークスペースを提供#

このページでは、oneapi::mkl::dft 名前空間に属し、oneapi/mkl/dft.hpp (インクルードするファイル) で宣言されている descriptor クラス・テンプレートのメンバー関数テンプレート set_workspace について説明します。

namespace oneapi::mkl::dft { 
    template <precision prec, domain dom> 
    class descriptor { 
        using real_scalar_t = std::conditional_t<prec == precision::DOUBLE, double, float>; 
    public: 
        template<typename data_type> 
        void set_workspace(sycl::buffer<data_type, 1> &workspace); 
        template<typename data_type> 
        void set_workspace(data_type* workspace); 
    } 
}

簡潔にするため、先頭に付加された名前空間指定子 oneapi::mkl::dft は以下では省略されています。

定義と説明#

定義する DFT の計算中に、descriptor オブジェクトは、中間結果や事前計算されたデータを格納する追加のメモリーを必要とする場合があります。この追加メモリーは、オブジェクトの「ワークスペース」と呼ばれます。

内部に割り当てられたワークスペース#

descriptor オブジェクトは、その構成パラメーター config_param::WORKSPACE_PLACEMENT (またはそのエイリアス config_param::WORKSPACE) に関連付けられた構成値が config_value::WORKSPACE_AUTOMATIC (または同等の config_value::WORKSPACE_INTERNAL) である場合、内部的に割り当てられたワークスペースを使用します。このようなオブジェクトはワークスペースを割り当てて所有します。オブジェクトがコミットされると、ワークスペースが割り当てられます (該当する場合は初期化されます)。これは、oneMKL のデフォルト動作です。

外部に割り当てられたワークスペース#

descriptor オブジェクトは、その構成パラメーター config_param::WORKSPACE_PLACEMENT (またはそのエイリアス config_param::WORKSPACE) に関連付けられた構成値が config_value::WORKSPACE_EXTERNAL である場合、外部的に割り当てられたワークスペースを使用します。このようなオブジェクトはワークスペースを割り当ておよび所有しないため、oneMKL ユーザーは、オブジェクトがコミットされた後に、デバイスがアクセス可能なメモリーを割り当てて (oneMKL によって管理されない)、オブジェクトに提供する必要があります。

上記の set_workspace メンバー関数を使用すると、ユーザーは、SYCL* バッファーまたはデバイスがアクセス可能な USM 割り当て形式で (いずれかの関数テンプレートの唯一の引数)、コミットされた呼び出し元のオブジェクトに外部割り当てのワークスペースを提供できます。提供されるワークスペースの形式 (SYCL* バッファーまたは USM 割り当て) は、計算関数で使用される入力および出力データコンテナーの形式と同一である必要があります。

ワークスペースとして提供される割り当ての最小サイズ (バイト単位) は、コミットされたオブジェクトの構成パラメーター config_param::WORKSPACE_BYTES (またはそのエイリアス config_param::WORKSPACE_EXTERNAL_BYTES) に関連付けられた構成値です。最小サイズはオブジェクトがコミットされない限り不明ですが、config_param::WORKSPACE_ESTIMATE_BYTES に関連付けられた構成値を照会することにより、コミットされていないオブジェクトから推定値を取得できます。どちらの場合でも、整数値パラメーターを照会するオブジェクトのメンバー関数を使用して、(読み取り専用の) 構成値を取得する必要があります。

呼び出し元オブジェクトの構成がコミット時に内部的に割り当てられたワークスペースを使用するように設定されていた場合、後続の set_workspace メンバー関数の呼び出しによって、その既存のステータスがオーバーライドされます。つまり、オブジェクトに対して、独自に内部的に割り当てられたワークスペースを解放し、代わりにユーザーが指定したワークスペースを使用し、config_param::WORKSPACE (または同等の config_param::WORKSPACE_PLACEMENT) に関連付けられた構成値を config_value::WORKSPACE_EXTERNAL に変更するように通知します。操作が完了すると、オブジェクトはコミットされたままになります。

外部に割り当てられたワークスペースは、descriptor オブジェクトに提供され、そのオブジェクトを使用する計算関数が完了するまでの間、他の用途で使用してはなりません (特に USM 割り当ての場合、oneMKL 内部のワークスペース関連の依存関係は無視される可能性があります)。

注

コミットされていないオブジェクトから照会することもできますが、パラメーター config_param::WORKSPACE_ESTIMATE_BYTES に関連付けられた構成値は、照会を実行するメンバー関数が呼び出された時点の呼び出し元オブジェクトの構成を考慮します。値を照会した後に呼び出し元オブジェクトの設定を変更すると、取得されたワークスペースのバイトサイズの推測値が無効になる可能性があります。

部分的なサポート#

外部に割り当てられたワークスペースは、GPU デバイスでのみサポートされます。上記で説明したワークスペースのバイトサイズの見積もり (つまり、config_param::WORKSPACE_ESTIMATE_BYTES に関連付けられた構成値) は、呼び出し元のオブジェクトが後で GPU デバイスを対象とするキューにコミットされることを暗黙的に想定しています (すでに CPU デバイスにコミットされている場合でも)。

テンプレート・パラメーター#

どちらのメンバー関数テンプレートも、タイプ・テンプレート・パラメーター data_type によってパラメーター化されます。oneMKL で data_type に対して使用できる唯一の特殊化は real_scalar_t、つまり単精度 (倍精度) 記述子の float (double) です。

入力パラメーター#

set_workspace メンバー関数テンプレートの入力パラメーター#

名前

サポートされるタイプ

説明

workspace
i. sycl::buffer<data_type, 1>
ii. data_type*

(i) sycl::buffer または (ii) デバイスがアクセス可能な USM 割り当ての形式でユーザーが割り当てたワークスペース。

例外#

set_workspace メンバー関数は、以下をスローします

  • 指定されたワークスペースがサブバッファーである sycl::buffer オブジェクトの場合、oneapi::mkl::invalid_argument 例外が発生します;

  • 呼び出し元のオブジェクトがコミットされていない場合は std::runtime_error が発生します;

    • ワークスペースは、必要なサイズよりも小さい sycl::buffer オブジェクトとして提供されます;

    • 引数として nullptr が使用されていますが、呼び出し元オブジェクトの必要なワークスペースのサイズは 0 以外です;

    • ワークスペースは、デバイスからアクセスできない USM 割り当てとして提供されます;

    • 呼び出し元のオブジェクトがワークスペース設定操作を実行中にエラーが発生しました。

注

USM 割り当てが提供されている場合、提供されるワークスペースのサイズは oneMKL によって検証されません (十分に大きいと想定されます)。