インテル® DPCT 名前空間の利用ガイド

インテル® DPCT 名前空間は、入力ソースコードの移行を支援するヘルパー関数とマクロを提供しています。インテル® DPCT 名前空間のヘルパー関数は、ヘッダーファイルで実装されており、インテル® DPC++ 互換性ツールのインストール・パスの include フォルダー (include/dpct) にあります。これらのヘッダーファイルは、インテル® DPC++ 互換性ツールによって生成される新しい DPC++ コードで使用されることを目的としています。必要に応じて、これらのヘッダーファイルをコピーし、生成されたコードにインクルードできます。

次の 3 つの名前空間があります。

名前空間	説明
dpct::	この名前空間は、インテル® DPC++ 互換性ツールが生成するコードで使用されます。
dpct::detail::	この名前空間は内部実装であり、dpct::detail:: 名前空間内の API と実装は予告なしに変更される可能性があるため、SYCL* ソースで直接使用すべきではありません。
dpct::deprecated::	この名前空間は互換性の目的で導入された機能向けですが、すでに削除された、または将来の標準化で削除される非推奨の C++ 機能に依存しています。dpct::deprecated:: 名前空間の非推奨の機能は使用しないでください。

注

移行後は、インテル® DPCT 名前空間のヘルパー関数とマクロをベースにするのではなく、SYCL* および C++ 標準 API を使用して開発を継続することを推奨します。

以下のセクションでは、ヘルパー関数とマクロのさまざまなドメインについて詳しく説明します。

マクロ

次の表は、ヘルパー関数の動作を制御するために使用されるマクロを示します。

マクロ	説明
DPCT_USM_LEVEL_NONE	--usm-level=none オプションを指定すると、DPCT_USM_LEVEL_NONE は、インテル® DPCT 名前空間のヘルパー・ヘッダー・ファイルが移行コードにインクルードされる前に定義されます。デフォルトでは、このマクロは定義されません。DPCT_USM_LEVEL_NONE が定義されると、このマクロでガードされているヘルパー関数が有効になり、移行されたコードでは USM ベースのメモリー関数ではなく、バッファーベースのメモリー関数が使用されます。
DPCT_NAMED_LAMBDA	--sycl-named-lambda オプションを指定すると、DPCT_NAMED_LAMBDA は、インテル® DPCT 名前空間のヘルパー・ヘッダー・ファイルが移行コードにインクルードされる前に定義されます。デフォルトでは、このマクロは定義されません。DPCT_NAMED_LAMBDA が定義されると、このマクロでガードされているヘルパー関数が有効になり、移行されたコードで使用されます。
DPCT_COMPATIBILITY_TEMP	DPCT_COMPATIBILITY_TEMP は、ヘルパー・ヘッダー・ファイルで整数値として定義され、インテル® DPC++ 互換性ツールによって移行されたコードに追加されます。必要に応じて、生成されたコードでこのマクロを置き換えたり、DPCT_COMPATIBILITY_TEMP の値を変更できます。

注

これらのマクロは手動で定義しないでください。インテル® DPC++ 互換性ツールが、dpct コマンドラインで指定されたオプションに応じて自動的に定義します。

アトミックヘルパー関数

アトミックヘルパー関数は、atomic.hpp ヘッダーファイルにあります。アトミックヘルパー関数は、SYCL* の標準的なアトミック操作のラッパーです。

デバイスヘルパー関数

デバイスヘルパー関数は、device.hpp ヘッダーファイルにあります。

次のクラスが device.hpp ヘッダーファイルで定義されています。

クラス	説明
device_info	device_info は、SYCL* のデバイス情報記述子で列挙される情報を提示します。
device_ext	device_ext は、SYCL* デバイスクラス cl::sycl::device のサブクラスです。 device_ext は、デバイス情報を照会するためのインターフェイスとデバイスに関連付けられたデフォルトの SYCL* キューを SYCL* デバイス上に追加し、device_info クラスを初期化します。
dev_mgr	dev_mgr は、システム上で利用可能なすべての DPC++ 対応デバイス (CPU や GPU など) を管理するシングルトンです。dev_mgr は、SYCL* のデフォルトのデバイスセレクターの動作に従って、利用可能なデバイスの 1 つを現在のデバイスとして選択します。現在のデバイスは current_device() で表示し、select_device() で変更できます。

詳細は、device.hpp ファイルを参照してください。

以下の表は、デバイスヘルパー関数の一覧です。

関数	説明
get_current_device()	デバイス・マネージャーの現在のデバイスを返します。
get_default_queue()	デバイス・マネージャーの現在のデバイスに関連付けられているデフォルトのキューを返します。
get_device(unsigned int id)	device_ext オブジェクトの ID (整数値) を返します。
cpu_device	SYCL* CPU に関連付けられている device_ext オブジェクトを返します。
get_default_context()	デバイス・マネージャーの現在のデバイスに関連付けられているデフォルトのキューの SYCL* コンテキストを返します。

メモリーヘルパー関数

次の表に、SYCL* バッファーベースのメモリー・モデル・ヘルパー関数を示します。

関数	説明
デバイス・メモリー・マネージャー (mem_mgr )	デバイス・メモリー・マネージャーは、SYCL* バッファーベースのメモリーモデルが使用されている場合に、メモリー API 呼び出しの移行を支援するシングルトンです。cl::sycl::buffer にバインドされたホスト仮想アドレス空間の割り当てと解放、およびホスト仮想アドレスと cl::sycl::buffer 間の変換を行う API を提供します。デフォルトでは、mem_mgr は 128GB の仮想メモリー空間を保持します。必要に応じて、memory.hpp ファイルの mapped_region_size の値を変更して、仮想メモリー空間のサイズを変更できます。

次の表に、ホスト仮想アドレスから SYCL* バッファーを取得するヘルパー関数を示します。

関数	説明
get_buffer_and_offset(const void *ptr)	ptr はホスト仮想アドレスです。この関数は、ホスト仮想アドレスにバインドされている cl::sycl::buffer と cl::sycl::buffer のホスト仮想アドレスのオフセットを返します。
get_buffer(const void *ptr)	ptr はホスト仮想アドレスです。ホスト仮想アドレスにバインドされている sycl::buffer を返します。

一般的なヘルパー関数

一般的なメモリーヘルパー関数は、USM とバッファーベースのメモリーモデルの両方で、メモリーの割り当て、メモリーコピー、メモリーセットなどのメモリー API 呼び出しの移行を支援するために使用されます。次のヘルパー関数が利用できます。

• dpct_malloc()

• dpct_free()

• dpct_memcpy()

• async_dpct_memcpy()

• dpct_memset()

• async_dpct_memset()

詳細は、memory.hpp ファイルを参照してください。

デバイスメモリー変数の移行を支援するヘルパー関数

グローバルおよび定数デバイスメモリー属性で宣言された変数の移行を支援するため、ヘルパー関数は以下のテンプレートクラスを提供します。

関数	説明
global_memory	SYCL* グローバルメモリー変数を表します。
constant_memory	SYCL* 定数メモリー変数を表します。
shared_memory	SYCL* USM 共有メモリーと同様に、ホストとデバイスからアクセス可能なメモリーを表します。

次の表に、メモリークラスの主なメンバー関数を示します。

関数	説明
get_prt()	メモリー・オブジェクトのメモリーポインターを返します。バッファーベースのメモリーモデルを使用している場合は仮想ポインター、USM メモリーモデルを使用している場合はデバイスポインターとなります。
get_size()	メモリー・オブジェクトのサイズを返します。
get_access()	メモリー・オブジェクトのアクセサーを返します。USM メモリーモデルが使用されている場合、この関数はデバイス・メモリー・オブジェクトの dpct_accessor_t オブジェクトを返します。dpct_accessor_t は、データポインターやデータの次元情報を含むヘルパー型で、メモリーにアクセスする方法を提供します。バッファーベースのメモリーモデルが使用されている場合、この関数はデバイス・メモリー・オブジェクトの cl::sycl::accessor を返します。
init()	SYCL* デバイスが選択された後にメモリーを割り当て、デバイスメモリーが初期値であれば初期化します。この API は、SYCL* デバイスを選択した後に呼び出す必要があります。

カーネル ヘルパー関数

カーネルヘルパー関数は、DPC++ のカーネル情報を保持する構造体 kernel_function_info とカーネル情報を取得するユーティリティー関数 get_kernel_function_info() を提供します。

イメージヘルパー関数

イメージヘルパー関数は、テクスチャー API の移行を支援するクラスラッパーを提供します。イメージヘルパー関数の詳細は、image.hpp ファイルを参照してください。

ラッパー	説明
テンプレートクラス image_wrapper	cl::sycl::image のラッパー。cl::sycl::image との間で 1D/2D/3D データをアタッチ/デタッチするメソッドと、SYCL* イメージアクセサーを返す get_access() メソッドを提供します。
クラス image_accessor_ext	SYCL* サンプラーと SYCL* イメージアクセサーをラップします。アクセサーからデータを読み取る read() メソッドを提供します。
クラス image_data	cl::sycl::image オブジェクトの作成に使用されるデータを表します。以下のデータ型をサポートしています。 2D または 3D 行列データ用の行列 (image_matrix クラス) 1D 線形配列用の線形 ピッチ指定 2D または 3D メモリーデータ用のピッチ (pitched_data クラス)
クラス image_matrix	イメージの 2D/3D 行列データを表します。イメージのチャネル情報、次元、各次元のサイズ、生データポインターが含まれています。
クラス pitched_data	イメージの 2D/3D ピッチ指定データを表します。
構造体 image_channel	順番、データ幅、タイプ情報などのイメージチャネル情報を保持します。
クラス image_info	アドレス指定モード、フィルターモード、正規化モードを含む、画像のサンプリング情報。
image_wrapper 操作 API: create_image_wrapper()	指定されたパラメータに応じて、ヘルパー・イメージ・クラスのオブジェクトを作成します。

インテル® oneAPI DPC++ ライブラリー固有ユーティリティー・ヘルパー関数

アルゴリズム関数、メモリー関数、イテレーター、デバイス上のデータを管理するコンテナーなど、dpl_utils.hpp にインクルードされたヘッダーファイルが提供するヘルパー関数です。

アルゴリズム・ヘルパー関数

アルゴリズム・ヘルパー関数は、dpl_extras/algorithm.h ヘッダーファイルにあります。アルゴリズム・ヘルパー関数は、インテル® oneAPI DPC++ ライブラリー (インテル® oneDPL) (英語) アルゴリズム関数のラッパーです。

マスクプレディケート・アルゴリズム関数

マスクプレディケート・アルゴリズム関数には、C++ 標準ライブラリーにある同名のアルゴリズムと同様に、パラメーター・リストがあります。これらの関数は、関数のほかの入力の対応する要素をアルゴリズムで処理すべきかどうかを示す値のセットを指す、追加のイテレーターを受け取ります。これらの関数に提供されるプレディケートは、入力データの要素ではなく、マスクの値に適用され、プレディケートが true を返した場合、入力データの対応する要素がアルゴリズムによって操作されます。

以下のマスクプレディケート・アルゴリズム関数が dpl_extras/algorithm.h ヘッダーファイルにあります。

• copy_if

• partition

• partition_copy

• remove_if

• remove_copy_if

• replace_if

• replace_copy_if

• stable_partition_copy

• stable_partition

• transform_if

キー値ペア・アルゴリズム関数

キー値ペア・アルゴリズム関数には、C++ 標準ライブラリーにある同名のアルゴリズムと同様に、パラメーター・リストがあります。この関数は、1 つの入力データではなく、2 つの入力データを受け取ります。1 つ目はキーのセット、2 つ目は各キーに関連する値のセットです。これらのアルゴリズム関数は、zip_iterators を作成し、インテル® oneDPL で提供されている標準的なアルゴリズムを呼び出すことで、キー値ペアを単一のデータ要素として処理します。

以下のキー値ペア・アルゴリズム関数が dpl_extras/algorithm.h ヘッダーファイルにあります。

• unique

• unique_copy

• merge

• sort

• stable_sort

• set_difference

• set_intersection

• set_symmetric_difference

• set_union

追加のアルゴリズム関数

関数	説明
partition_point	実行ポリシーを受け取り、並列実行を可能にする C++ 標準ライブラリーのアルゴリズムの実装。
transform_if	提供されたプレディケートが true を返す入力のすべての要素に単項演算を適用します。この関数のマスクプレディケート・バージョンも用意されています。
iota	入力イテレーターと初期値に加えてステップを受け取るように、C++ 標準ライブラリーのアルゴリズムを拡張します。ステップは、生成されるシーケンスの次の値を計算するために使用されます。
inner_product	実行ポリシーを受け取り、並列実行を可能にする C++ 標準ライブラリーのアルゴリズムの実装。リダクションを行う二項演算は、結合的かつ可換でなければなりません。
for_each_index	入力レンジの各要素に、その要素のインデックスを指定して呼び出した単項演算の結果を割り当てます。

メモリーヘルパー関数

dpl_extras/memory.h ヘッダーファイルは、デバイスメモリーを操作するためのクラスと関数を提供します。

以下の表は、メモリーヘルパー関数の一覧です。

クラス	説明
device_pointer	デバイス上のメモリーへのポインター型。
device_iterator	device_vector の begin と end メソッドによって返されるイテレーター型。
device_reference	device_vector 要素アクセス演算子が返す参照型。

device_iterator クラスと device_reference クラスを使用する device_vector 実装は、dpl_extras/vector.h で定義されています。

以下の表は、メモリーヘルパー関数の一覧です。

関数	説明
malloc_device	デバイスで使用するメモリーを割り当てます。
free_device	malloc_device で割り当てられたメモリーを解放します。
device_new	指定された型の要素を要求された数だけ保持するのに十分な大きさの、デバイスで使用するメモリーを割り当てます。
device_delete	device_new で割り当てられたメモリーを解放します。
get_device_pointer	生ポインターから device_pointer を構築します。
get_raw_pointer	device_pointer インスタンスから生ポインターを返します。

インテル® oneAPI DPC++ ライブラリー固有ユーティリティー・ヘルパー・ファイル

次の表は、インテル® oneAPI DPC++ ライブラリーに固有のユーティリティー・ヘッダー・ファイルを示します。

ヘッダーファイル	説明
functional.h	上記のアルゴリズム関数の定義に使用される関数オブジェクトの実装が含まれています。
iterator.h	ある値で構築され、逆参照時にその値を返す constant_iterator イテレーターの実装を提供します。
vector.h	デバイスメモリーに格納されたデータ要素を管理するコンテナである device_vector の実装を提供します。

ユーティリティー・ヘルパー関数

次の表に、ユーティリティー関数を定義するヘッダーファイルを示します。

ヘッダーファイル	説明
util.hpp	一般ユーティリティー・ヘルパー関数。
blas_utils.hpp	BLAS 固有のユーティリティー・ヘルパー関数。