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 alias config_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 alias config_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#
Name |
Supported types |
Description |
---|---|---|
|
i.
sycl::buffer<data_type, 1> ii.
data_type* |
User-allocated workspace in the form of a (i) |
Exceptions#
The set_workspace
member functions may throw
a
oneapi::mkl::invalid_argument
exception if the provided workspace is asycl::buffer
object that is a sub-buffer;an
std::runtime_error
ifthe 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).