Providing an externally-allocated workspace

oneMKL - Data Parallel C++ Developer Reference

Download PDF

ID 772045

Date 6/24/2024

Version

Public

A newer version of this document is available. Customers should click here to go to the newest version.

Visible to Intel only — GUID: GUID-B2C2DC34-66E4-4706-9021-8DF3C485E84B

View Details

Providing an externally-allocated workspace

This page describes the member function templates set_workspace 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:
    template<typename data_type>
    void set_workspace(sycl::buffer<data_type, 1> &workspace);
    template<typename data_type>
    void set_workspace(data_type* workspace);
  }
}

The usage of prepended namespace specifiers oneapi::mkl::dft is omitted below for conciseness.

Definitions and description

During the computation of the DFT that it defines, any descriptor object may require additional memory, e.g., to store intermediate results or pre-computed data: that required additional memory is referred to as the object’s “workspace”.

Internally-allocated workspaces

A descriptor object uses an internally-allocated workspace if config_value::WORKSPACE_AUTOMATIC (or its equivalent config_value::WORKSPACE_INTERNAL) is the configuration value associated with its configuration parameter config_param::WORKSPACE_PLACEMENT (or its aliasconfig_param::WORKSPACE). Such an object allocates and owns its workspace. The workspace is allocated (and initialized, if relevant) when the object is committed. This is the default behavior in oneMKL.

Externally-allocated workspaces

A descriptor objects uses an externally-allocated workspace if config_value::WORKSPACE_EXTERNAL is the configuration value associated with its configuration parameter config_param::WORKSPACE_PLACEMENT (or its aliasconfig_param::WORKSPACE). Such an object does not allocate nor own its workspace and oneMKL users must provide it with a device-accessible memory allocation (not managed by oneMKL) after the object was committed.

The above set_workspace member functions enable users to provide the committed calling object with an externally-allocated workspace, either in the form of a SYCL buffer or a device-accessible USM allocation (either function template’s only argument). The form of the workspace being provided (SYCL buffer or USM allocation) must be identical to the form of input and output data containers used afterwards, in compute functions.

The minimal size (in bytes) of the allocation to be provided as a workspace is the configuration value associated with the committed object’s configuration parameter config_param::WORKSPACE_BYTES (or its alias config_param::WORKSPACE_EXTERNAL_BYTES). That minimal size is unknown unless the object is committed, but a conservative estimate may be obtained from uncomitted objects by querying their configuration value associated with config_param::WORKSPACE_ESTIMATE_BYTES. In either case, the object’s member function for querying integer-valued parameters must be used to obtain that (read-only) configuration value.

If the calling object’s configuration was set to use an internally-allocated workspace when committed, a subsequent call to any set_workspace member function overrides that pre-existing status: it signals the object to free its own internally-allocated workspace, use the user-provided one instead, and change its configuration value associated with config_param::WORKSPACE (or its equivalent config_param::WORKSPACE_PLACEMENT) to config_value::WORKSPACE_EXTERNAL. The object remains committed upon completion of that operation.

An externally-allocated workspace must not be used for any other purposes between the time it is provided to a descriptor object and the time any compute function using that object completes (especially in case of USM allocations since workspace-related dependencies internal to oneMKL may be ignored otherwise).

NOTE:

Although it may be queried from uncommitted objects, the configuration value associated with parameter config_param::WORKSPACE_ESTIMATE_BYTES does take into account the calling object’s configuration at the time its querying member function is called. Modifying the calling object’s configuration after querying that value may invalidate the obtained workspace byte size estimate.

Partial support

Externally-allocated workspaces are supported on GPU devices only. As a consequence, the conservative estimate of the workspace byte size documented above (i.e., the configuration value associated with config_param::WORKSPACE_ESTIMATE_BYTES) implicitly assumes that the calling object is meant to be committed to a queue targeting a GPU device later on (even if it is already committed to a CPU device).

Template parameter

Either member function template is parameterized by a type template parameter data_type. The only specializations availaible in oneMKL for data_type are real_scalar_t, i.e., float (resp. double) for single-precision (resp. double-precision) descriptors.

Input parameter

Input parameter for the `set_workspace` member function templates.
Name	Supported types	Description
`workspace`	i. `sycl::buffer<data_type, 1>` ii. `data_type*`	User-allocated workspace in the form of a (i) `sycl::buffer` or (ii) device-accessible USM allocation.

Exceptions

The set_workspace member functions may throw

a oneapi::mkl::invalid_argument exception if the provided workspace is a sycl::buffer object that is a sub-buffer;
an std::runtime_error if
- the calling object is not committed;
- the workspace is provided as a sycl::buffer object that is smaller than required;
- a nullptr is used as argument yet the calling object’s required workspace size is nonzero;
- the workspace is provided as a USM allocation that is not accessible by the device;
- an error occurred while the calling object operated its workspace-setting operations.

NOTE:

In case of a USM allocation being provided, the size of the provided workspace is not verified by oneMKL (assumed large enough).

Select Your Language

Using Intel.com Search

Quick Links

Recent Searches

Advanced Search

Only search in

oneMKL - Data Parallel C++ Developer Reference

Providing an externally-allocated workspace

Definitions and description

Partial support

Template parameter

Input parameter

Exceptions