oneAPI 1.3 暫定仕様書 Rev. 1 の解説 (38)

その他
oneAPIドキュメント

この記事は、https://www.oneapi.io/spec/ で 2023年9月14日に公開された『oneAPI 1.3 Provisional Specification Rev. 1』 (HTML、PDF) をベースにしています。原文は2000 ページ近くあり、翻訳の時間とリソースも限られるため、全文翻訳ではなく、記事形式で区切った仕様とその解説を提供することにしました。

この回では、『oneAPI 1.3 Provisional Specification Rev. 1』の「oneDAL」の「Common Interface」の節を取り上げています。

共通インターフェイス

現在のバージョンの oneDAL 仕様

これは、oneAPI 仕様バージョン 1.0 の一部である oneDAL の仕様です。

ヘッダーファイル

oneDAL パブリック識別子は、次のヘッダーファイルに含まれます。

ヘッダーファイル

説明

oneapi/dal.hpp

oneDAL ライブラリーのメイン・ヘッダー・ファイル。

oneapi/dal/%FILE%.hpp

他の oneDAL レイヤーで使用される一般的なタイプ定義。例えば、data_type や range。

oneapi/dal/algo/%ALGO%.hpp

特定のアルゴリズムのヘッダーファイル。アルゴリズム自体のフォルダーは、oneapi/dal/algo/%ALGO%/ です。

文字列 %ALGO% は、アルゴリズムの名称に置き換える必要があります (例: kmeans または knn)。

oneapi/dal/algo/misc/%FUNC%.hpp

oneDAL アルゴリズムおよび分析パイプラインのアプリケーションで利用することを目的とした、さまざまなデータタイプと関数のヘッダーファイル。

文字列 %FUNC% は、機能名に置き換える必要があります (例: mt19937 または cross_enthropy_loss)。

oneapi/dal/table/%FILE%.hpp

テーブルの概念に関連するタイプのヘッダーファイル。

文字列 %FILE% は、機能名に置き換える必要があります。例えば、テーブルタイプ (例: table、table_metadata、data_layout クラス) に関連する重要な概念に共通です。名前に _table サフィックスが含まれるエンティティーでは、関連するヘッダーファイル名にこのサフィックスを含まれている必要があります (例: homogen_table クラスの homogen)。

oneapi/dal/io/%FILE%.hpp

入出力機能のタイプとエンティティーのヘッダーファイル。

文字列 %FILE% は、機能名に置き換える必要があります (例: csv ファイルの読み取りと書き込みには csv を使用します)。

oneapi/dal/util/%UTIL%.hpp`

クラスの設計や各種メソッドの実装に使用するメモリー・アロケーターやタイプ特性など、補助機能向けのヘッダーファイル。

文字列 %UTIL% は、補助機能の名称に置き換える必要があります (例: usm_allocator や type_traits など)。

名前空間

oneDAL の機能は、以下で説明する C++ 名前空間で表されます。

名前空間

oneDAL の概念

oneapi::dal

外部から見えるデータタイプ、データ管理エンティティー、処理、および oneDAL の処理とサービス機能を含むライブラリーの名前空間。

oneapi::dal::%ALGORITHM%

アルゴリズムの名前空間。アルゴリズムに関連するすべてのクラスと構造は、名前空間で定義されます。

アルゴリズムの名前空間を定義するには、文字列 %ALGORITHM% をアルゴリズム名に置き換えます (例: oneapi::dal::kmeans や oneapi::dal::knn)。

oneapi::dal::%DATA_SOURCE%

データソースの名前空間。データソースに関連するすべてのクラスと構造は、名前空間で定義されます。

データソースを定義するには、文字列 %DATA_SOURCE% をデータソース名に置き換えます (例: oneapi::dal::csv)。

oneapi::dal::misc

解析パイプラインの各種ステージでアルゴリズムをカスタマイズおよび最適化するため、oneDAL アルゴリズムとアプリケーションで使用する各種データタイプと機能が含まれる名前空間。

%PARENT%::detail

親の名前空間データタイプと機能実装の詳細を含む名前空間。名前空間は、名前空間の階層の任意のレベルであることができます。

特定の名前空間を定義するには、文字列 %PARENT% を詳細が提供される名前空間に置き換えます (例: oneapi::dal::detail や oneapi::dal::kmeans::detail)。

アプリケーションは、detail 名前空間にあるデータタイプを使用したり、機能を呼び出してはなりません。

エラー処理

oneDAL のエラー処理は、C++ の例外メカニズムに関連しています。エラーが発生すると、標準の C++ エラー処理メカニズムを使用してキャッチされた関数呼び出しに伝搬されます。

例外の分類

oneDAL の例外分類は、C++ 標準ライブラリーの分類と一致しています。oneDAL は例外クラスの階層に基本クラスを定義する抽象化クラスを導入する必要があります。非抽象化クラスは、それぞれの C+C 標準ライブラリー例外クラスから派生します。oneDAL は、非抽象化クラスで表現される例外をスローします。

oneDAL 例外階層では、oneapi::dal::exception はすべての例外クラスの派生元である基本抽象化クラスです。

class oneapi::dal::exception;

例外

説明

概要

oneapi::dal::exception

oneDAL 例外階層の基本クラス。

はい

すべての oneDAL 例外は 3 つのグループに分けられます。

  • 論理エラー

  • ランタイムエラー

  • アプリケーションのエラー

class oneapi::dal::logic_error : public oneapi::dal::exception;
class oneapi::dal::runtime_error : public oneapi::dal::exception;
class oneapi::dal::bad_alloc :  public oneapi::dal::exception, public std::bad_alloc;

例外

説明

概要

oneapi::dal::logic_error

前提条件と不変条件違反をレポートします。

はい

oneapi::dal::runtime_error

oneDAL 機能の実行中に発生した事後条件違反やその他のエラーをレポートします。

はい

oneapi::dal::bad_alloc

ストレージ割り当ての失敗をレポートします。

はい

oneapi::dal::logic_error で表現されるすべての前提条件と不変エラーは、次のグループに分類されます。

  • 無効な引数エラー
  • ドメインエラー
  • 範囲外エラー
  • 実装されていないメソッドやアルゴリズムのエラー
  • サポートされないデバイス
class oneapi::dal::invalid_argument :  public oneapi::dal::logic_error, public std::invalid_argument;
class oneapi::dal::domain_error :  public oneapi::dal::logic_error, public std::domain_error;
class oneapi::dal::out_of_range :  public oneapi::dal::logic_error, public std::out_of_range;
class oneapi::dal::unimplemented :  public oneapi::dal::logic_error, public std::logic_error;
class oneapi::dal::unsupported_device :  public oneapi::dal::logic_error, public std::logic_error;

例外

説明

概要

oneapi::dal::invalid_argument

引数が受け入れられなかった状況をレポートします。

いいえ

oneapi::dal::domain_error

操作で定義されている引数がドメイン外にある場合の状況をレポートします。oneapi::dal::invalid_argument よりも優先順位が高いです。

いいえ

oneapi::dal::out_of_range

インデックスが範囲外にある状況をレポートします。oneapi::dal::invalid_argument よりも優先順位が高いです。

いいえ

oneapi::dal::unimplemented

アルゴリズムまたはメソッドが実装されていないため発生したエラーをレポートします。

いいえ

oneapi::dal::unsupported_device

デバイスがサポートされていない状況をレポートします。

いいえ

oneDAL 機能の実行中に発生するエラーは、oneapi::dal::runtime_error に示されます。2 つのエラーグループを区別する必要があります。

  • デスティネーション・タイプの範囲エラー
  • OS 機能との相互作用エラー

他のすべてのエラーは、oneapi::dal::internal_error でレポートされます。

class oneapi::dal::range_error :  public oneapi::dal::runtime_error, public std::range_error;
class oneapi::dal::system_error :  public oneapi::dal::runtime_error, public std::system_error;
class oneapi::dal::internal_error :  public oneapi::dal::runtime_error, public std::runtime_error;

例外

説明

概要

oneapi::dal::range_error

計算結果をデスティネーションのタイプで表現できない状況をレポートします。

いいえ

oneapi::dal::system_error

OS 機能を使用中に発生したエラーをレポートします。

いいえ

oneapi::dal::internal_error

継承できなかったすべてのランタイムエラーをレポートします。

いいえ

すべてのメモリーの割り当てエラーは oneapi::dal::bad_alloc で報告されます。メモリーエラーは発生した場所により 2 つのグループに分けられます。

  • ホストメモリー割り当てエラー
  • デバイスメモリー割り当てエラー
class oneapi::dal::host_bad_alloc :  public oneapi::dal::bad_alloc;
class oneapi::dal::device_bad_alloc :  public oneapi::dal::bad_alloc;

例外

説明

概要

oneapi::dal::host_bad_alloc

ホストでストレージが割り当てられなかったことをレポートします。

いいえ

oneapi::dal::device_bad_alloc

デバイスでストレージが割り当てられなかったことをレポートします。

いいえ

共通タイプ定義

ここでは、oneDAL で使用される一般的なタイプについて説明します。

プログラミング・インターフェイス

この節のすべてのタイプと関数は、oneapi::dal 名前空間で宣言され、oneapi/dal/common.hpp ヘッダーファイルをインクルードして使用できます。

スカラータイプ

oneDAL は <cstdint> で定義される整数タイプを使用します。このファイルは oneapi/dal/ common.hpp でインクルードされ、すべての oneDAL タイプはこれらのデータタイプを使用します。

ライブラリーのインターフェイスは、std::int64_t タイプを使用して、次元 (例えば、テーブルの行と列) を表現します。

アプリケーションでも標準の C++ データタイプを使用することを推奨します。

enum クラス

oneDAL の概念を表す enum や enum クラス を定義する際に使用する基本タイプは、仕様で定義される特定の基本タイプを除いて実装依存です。

データタイプ

データタイプの概念の基本。計算を実行するため、oneDAL でサポートされるすべてのデータタイプを列挙する必要があります。data_type クラスには、すべての基本スカラータイプが含まれ、それらを拡張することもできます。基本スカラータイプには、名前のパターンが std::int_XX_t または std::uint_XX_t である必要があります。ここで、XX は 8、16、32 または 64 です。

データタイプの詳細はこちら (英語) を参照してください。

範囲

配列または値のインデックスをサポートするコンテナの範囲 [start_index, end_index)。

範囲の詳細はこちら (英語) を参照してください。

法務上の注意書き

The content of this oneAPI Specification is licensed under the Creative Commons Attribution 4.0 International License (英語). Unless stated otherwise, the sample code examples in this document are released to you under the MIT license (英語).

This specification is a continuation of Intel’s decades-long history of working with standards groups and industry/academia initiatives such as The Khronos Group*, to create and define specifications in an open and fair process to achieve interoperability and interchangeability. oneAPI is intended to be an open specification and we encourage you to help us make it better. Your feedback is optional, but to enable Intel to incorporate any feedback you may provide to this specification, and to further upstream your feedback to other standards bodies, including The Khronos Group SYCL* specification, please submit your feedback under the terms and conditions below. Any contribution of your feedback to the oneAPI Specification does not prohibit you from also contributing your feedback directly to other standard bodies, including The Khronos Group under their respective submission policies.

By opening an issue, providing feedback, or otherwise contributing to the specification, you agree that Intel will be free to use, disclose, reproduce, modify, license, or otherwise distribute your feedback at its sole discretion without any obligations or restrictions of any kind, including without limitation, intellectual property rights or licensing obligations.

This document contains information on products, services and/or processes in development. All information provided here is subject to change without notice.

© Intel Corporation. Intel、インテル、Intel ロゴ、その他のインテルの名称やロゴは、Intel Corporation またはその子会社の商標です。

* その他の社名、製品名などは、一般に各社の表示、商標または登録商標です。

« パート 37        目次        パート 39 »
タイトルとURLをコピーしました