corecel/data/AsyncResultRef.hh

0001 //------------------------------- -*- C++ -*- -------------------------------//
0002 // Copyright Celeritas contributors: see top-level COPYRIGHT file for details
0003 // SPDX-License-Identifier: (Apache-2.0 OR MIT)
0004 //---------------------------------------------------------------------------//
0005 //! \file corecel/data/AsyncResultRef.hh
0006 //---------------------------------------------------------------------------//
0007 #pragma once
0008
0009 #include <vector>
0010
0011 #include "corecel/Assert.hh"
0012 #include "corecel/Types.hh"
0013
0014 #include "ObserverPtr.hh"
0015 #include "PinnedAllocator.hh"
0016
0017 namespace celeritas
0018 {
0019 //---------------------------------------------------------------------------//
0020 /*!
0021  * Reference to pinned host memory written asynchronously by a stream.
0022  *
0023  * This marks a host destination for an asynchronous device-to-host copy. The
0024  * referenced value \b must be in pinned host memory, which must remain valid
0025  * until the stream has completed the write. The value must not be read until
0026  * the stream is synchronized (directly or through an event recorded after the
0027  * enqueued write).
0028  *
0029  * \code
0030     std::vector<size_type, PinnedAllocator<size_type>> count(1);
0031     enqueue_count(state, AsyncResultRef{count});
0032     stream.sync();
0033     use(count.front());
0034    \endcode
0035  */
0036 template<class T>
0037 struct AsyncResultRef
0038 {
0039     //! Host destination of the asynchronous write
0040     ObserverPtr<T, MemSpace::host> ptr;
0041
0042     //! Construct with a null reference
0043     AsyncResultRef() = default;
0044
0045     // Construct from the first element of a pinned host vector
0046     inline explicit AsyncResultRef(std::vector<T, PinnedAllocator<T>>& vec);
0047
0048     //! Whether the reference is assigned
0049     explicit operator bool() const { return static_cast<bool>(ptr); }
0050 };
0051
0052 //---------------------------------------------------------------------------//
0053 // INLINE DEFINITIONS
0054 //---------------------------------------------------------------------------//
0055 /*!
0056  * Construct from the first element of a pinned host vector.
0057  *
0058  * The vector must not be resized while the asynchronous write is pending.
0059  */
0060 template<class T>
0061 AsyncResultRef<T>::AsyncResultRef(std::vector<T, PinnedAllocator<T>>& vec)
0062     : ptr{vec.data()}
0063 {
0064     CELER_EXPECT(!vec.empty());
0065 }
0066
0067 //---------------------------------------------------------------------------//
0068 }  // namespace celeritas