AlpakaInterface/interface/CopyToHost.h

0001 #ifndef HeterogeneousCore_AlpakaInterface_interface_CopyToHost_h
0002 #define HeterogeneousCore_AlpakaInterface_interface_CopyToHost_h
0003
0004 // TODO: this utility class is specific to CMSSW, but needs to be in a
0005 // package that is suitable as DataFormat dependence
0006
0007 namespace cms::alpakatools {
0008   /**
0009    * This class template needs to be specialized for each device-side
0010    * Event data product so that the framework can implicitly copy the
0011    * device-side data product to the host memory. The specialization
0012    * is expected to define static copyAsync() function as in the
0013    * following example
0014    *
0015    * \code
0016    * template <>
0017    * struct CopyToHost<ExampleDeviceProduct> {
0018    *   template <typename TQueue>
0019    *   static ExampleHostProduct copyAsync(TQueue& queue, ExampleDeviceProduct const& deviceData) {
0020    *     // construct ExampleHostProduct
0021    *     // asynchronous copy deviceData to the ExampleHostProduct object
0022    *     // return ExampleHostProduct object by value
0023    *   }
0024    * };
0025    * \endcode
0026    *
0027    * The copyAsync() function should not explicitly synchronize the
0028    * queue. The ExampleDeviceProduct and ExampleHostProduct can be the
0029    * same type, if they internally are able to handle the memory
0030    * allocation difference between host and device.
0031    *
0032    * Data products that contain pointers to memory elsewhere in the
0033    * data product need those pointers to be updated after the copy
0034    * from device-to-host completes. While such data structures are
0035    * generally discouraged, such an update of the data product can be
0036    * implemented (without any additional synchronization) with an
0037    * optional postCopy() static member function in the CopyToHost
0038    * specialization. The postCopy() is called for the host-side data
0039    * product after the copy operations enqueued in the copyAsync()
0040    * have finished. Following the example above, the expected
0041    * signature is
0042    * \code
0043    * template <>
0044    * struct CopyToHost<ExampleDeviceProduct> {
0045    *   // copyAsync() definition from above
0046    *
0047    *   static void postCopy(ExampleHostProduct& obj) {
0048    *     // modify obj
0049    *     // any modifications must be such that the postCopy() can be
0050    *     // skipped when the obj originates from the host (i.e. on CPU backends)
0051    *   }
0052    * };
0053    * \endcode
0054    */
0055   template <typename TDeviceData>
0056   struct CopyToHost;
0057 }  // namespace cms::alpakatools
0058
0059 #endif