User-Allocated Workspaces¶
During the FFT execution, the descriptor object may require additional memory to store intermediate results or pre-computed data. By default, the descriptor allocates this workspace internally. oneMKL DFT provides a combination of existing and new APIs to enable the user to manage this workspace.
Note
User-allocated workspaces are currently supported only for GPU devices.
User’s intention regarding workspace¶
The descriptor allocates any required workspace internally during the commit
by default. The following needs to be set before commit
to let oneMKL DFT know that the workspace will be provided by the user.
descriptor.set_value(oneapi::mkl::dft::config_param::WORKSPACE, oneapi::mkl::dft::config_value::WORKSPACE_EXTERNAL);
The above call will notify the descriptor to not allocate any internal workspace during the commit
.
Note
If the user did not notify the descriptor before commit
that an external workspace will be provided, they can directly call
set_workspace
, which will override the internal allocations and utilize the user-workspace.
Get workspace estimate¶
The below optional call to get_value
before the commit
provides a conservative estimate of the workspace size that may be required.
size_t workspaceEstimate = 0;
descriptor.get_value(oneapi::mkl::dft::config_param::WORKSPACE_ESTIMATE, &workspaceEstimate);
The estimate in bytes will be stored in the workspaceEstimate variable.
Note
The workspace estimate values pertain to GPU devices only.
Get the exact workspace size¶
The below call to get_value
returns the exact amount of workspace size that will be required by the descriptor for computing the FFT.
This needs to be called after the commit
.
size_t workspaceSize = 0;
descriptor.get_value(oneapi::mkl::dft::config_param::WORKSPACE_BYTES, &workspaceSize);
The workspace size in bytes will be stored in the workspaceSize variable.
Note
Trying to get the exact workspace size before commit
will throw a std::runtime_exception()
.
Provide the workspace to the descriptor¶
The below descriptor class member functions will enable the user to set/replace the workspace either in the form of SYCL buffer or device-accessible USM.
If the workspace was internally allocated (config_param::WORKSPACE
was not set to config_value::WORKSPACE_EXTERNAL
before commit), setting the workspace will deallocate any internal workspace and user-provided workspace will be used.
Syntax¶
namespace oneapi::mkl::dft{
void descriptor<prec, dom>::set_workspace<data_type>(sycl::buffer<data_type, 1> &workspaceBuf);
void descriptor<prec, dom>::set_workspace<data_type>(data_type *workspaceUsm);
}
Note
The descriptor assumes that the workspace will be solely used for FFT, so the user must be careful not to use the same workspace area for other purposes in parallel or before finishing
compute_forward
/compute_backward
(especially for USM as explicit synchronization is required).In case of USM, it is assumed that the workspace is large enough. In case of Buffer,
std::runtime_exception()
will be thrown if the workspace size is smaller than required.If the user calls
compute_forward
orcompute_backward
before setting the workspace astd::runtime_exception()
will be thrown.Currently, the workspace type (Buffer or USM) must be the same as the container type(Buffer or USM) used during the compute stage. Otherwise,
std::runtime_exception()
will be thrown.
Include Files¶
oneapi/mkl/dfti.hpp