From 11a42bf1865e062896e15b453e907cab90685b30 Mon Sep 17 00:00:00 2001 From: Matti Kortelainen Date: Fri, 9 Feb 2024 08:18:03 -0600 Subject: [PATCH] Document CopyToDeviceCache and MoveToDeviceCache in README --- HeterogeneousCore/AlpakaCore/README.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/HeterogeneousCore/AlpakaCore/README.md b/HeterogeneousCore/AlpakaCore/README.md index a658e1e578f57..93d49b7e9e887 100644 --- a/HeterogeneousCore/AlpakaCore/README.md +++ b/HeterogeneousCore/AlpakaCore/README.md @@ -164,6 +164,26 @@ In the [`fillDescriptions()`](https://twiki.cern.ch/twiki/bin/view/CMSPublic/SWG Also note that the `fillDescription()` function must have the same content for all backends, i.e. any backend-specific behavior with e.g. `#ifdef` or `if constexpr` are forbidden. +### Copy e.g. configuration data to all devices in EDProducer + +While the EventSetup can be used to handle copying data to all devices +of an Alpaka backend, for data used only by one EDProducer a simpler +way would be to use one of +* `cms::alpakatools::MoveToDeviceCache` (recommended) + * `#include "HeterogeneousCore/AlpakaCore/interface/MoveToDeviceCache.h"` + * Moves the `THostObject` to all devices using `cms::alpakatools::CopyToDevice` synchronously. On host backends the argument `THostObject` is moved around, but not copied. + * The `THostObject` must not be copyable + * This is to avoid easy mistakes with objects that follow copy semantics of `std::shared_ptr` (that includes Alpaka buffers), that would allow the source memory buffer to be used via another copy during the asynchronous data copy to the device. + * The constructor argument `THostObject` object may not be used, unless it is initialized again e.g. by assigning another `THostObject` into it. + * The corresponding device-side object can be obtained with `get()` member function using either alpaka Device or Queue object. It can be used immediately after the constructor returns. +* `cms::alpakatools::CopyToDeviceCache` (use only if **must** use copyable `THostObject`) + * `#include "HeterogeneousCore/AlpakaCore/interface/CopyToDeviceCache.h"` + * Copies the `THostObject` to all devices using `cms::alpakatools::CopyToDevice` synchronously. Also host backends do a copy. + * The constructor argument `THostObject` object can be used for other purposes immediately after the constructor returns + * The corresponding device-side object can be obtained with `get()` member function using either alpaka Device or Queue object. It can be used immediately after the constructor returns. + +For examples see [`HeterogeneousCore/AlpakaTest/plugins/alpaka/TestAlpakaGlobalProducerCopyToDeviceCache.cc`](../../HeterogeneousCore/AlpakaTest/plugins/alpaka/TestAlpakaGlobalProducerCopyToDeviceCache.cc) and [`HeterogeneousCore/AlpakaTest/plugins/alpaka/TestAlpakaGlobalProducerMoveToDeviceCache.cc`](../../HeterogeneousCore/AlpakaTest/plugins/alpaka/TestAlpakaGlobalProducerMoveToDeviceCache.cc). + ## Guarantees * All Event data products in the device memory space are guaranteed to be accessible only for operations enqueued in the `Queue` given by `device::Event::queue()` when accessed through the `device::Event`.