Back to home page

EIC code displayed by LXR

 
 

    


File indexing completed on 2026-11-17 10:08:35

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/sys/Stream.hh
0006 //---------------------------------------------------------------------------//
0007 #pragma once
0008 
0009 #include <cstddef>
0010 #include <memory>
0011 
0012 #include "corecel/Assert.hh"  // IWYU pragma: keep
0013 #include "corecel/Macros.hh"  // IWYU pragma: keep
0014 
0015 #if CELER_DEVICE_SOURCE
0016 #    include "corecel/DeviceRuntimeApi.hh"
0017 #endif
0018 
0019 #if CELERITAS_USE_CUDA
0020 #    define CELER_STREAM_SUPPORTS_ASYNC 1
0021 #elif CELERITAS_USE_HIP \
0022     && (HIP_VERSION_MAJOR > 5 \
0023         || (HIP_VERSION_MAJOR == 5 && HIP_VERSION_MINOR >= 2))
0024 #    define CELER_STREAM_SUPPORTS_ASYNC 1
0025 #else
0026 //! Whether CUDA/HIP is enabled and new enough to support async operations
0027 #    define CELER_STREAM_SUPPORTS_ASYNC 0
0028 #endif
0029 
0030 namespace celeritas
0031 {
0032 //---------------------------------------------------------------------------//
0033 class Device;
0034 class DeviceEvent;
0035 
0036 //---------------------------------------------------------------------------//
0037 namespace detail
0038 {
0039 class AsyncMemoryResource;
0040 }
0041 
0042 //---------------------------------------------------------------------------//
0043 /*!
0044  * PIMPL class for CUDA or HIP stream.
0045  *
0046  * This creates/destroys a stream on construction/destruction and provides
0047  * accessors to low-level stream-related functionality. This class will
0048  * typically be accessed only by low-level device implementations or advanced
0049  * kernels that need to interact with the device stream.
0050  *
0051  * \par States
0052  * - \b Constructed: A valid stream created with an active device. The stream
0053  *   can be used for device operations.
0054  * - \b Null: Explicitly constructed with \c nullptr. No stream is created,
0055  *   but the object is in a valid null state. Operations are no-ops.
0056  *
0057  * \internal
0058  * \warning This class interface changes based on available headers.
0059  * Because the CUDA/HIP stream type are only defined when those paths are
0060  * included and available (which isn't true for all Celeritas code) we hide the
0061  * stream unless DeviceRuntimeApi has been included or the file is being
0062  * compiled by a CUDA/HIP compiler. Worse, our stream class has to manage a
0063  * Thrust memory resource, and in newer versions of rocthrust, its headers
0064  * cannot be included at all by a non-HIP compiler. Because this class forward
0065  * declares the memory resource, downstream uses must include \c
0066  * corecel/sys/detail/AsyncMemoryResource.device.hh .
0067  */
0068 class Stream
0069 {
0070   public:
0071     //!@{
0072     //! \name Type aliases
0073 #if !CELER_USE_DEVICE
0074     //! Stream implementation is unavailable
0075     using StreamT = std::nullptr_t;
0076     using ResourceT = std::nullptr_t;
0077 #elif !defined(CELER_DEVICE_RUNTIME_INCLUDED)
0078     //! Sentinel type to indicate compilation error
0079     using MissingDeviceRuntime = void;
0080     using ResourceT = detail::AsyncMemoryResource;
0081 #else
0082     //! Actual CUDA/HIP stream opaque pointer
0083     using StreamT = CELER_DEVICE_API_SYMBOL(Stream_t);
0084     using ResourceT = detail::AsyncMemoryResource;
0085 #endif
0086     using HostKernel = void (*)(void*);
0087     //!@}
0088 
0089   public:
0090     // Construct by creating a stream
0091     Stream();
0092     // Construct a null stream
0093     Stream(std::nullptr_t);
0094     // Construct a stream for the given device
0095     explicit Stream(Device const& device);
0096     CELER_DEFAULT_MOVE_DELETE_COPY(Stream);
0097     ~Stream() = default;
0098 
0099     // Whether the stream is valid (not null or moved-from)
0100     inline explicit operator bool() const;
0101 
0102 #if defined(CELER_DEVICE_RUNTIME_INCLUDED) || !CELER_USE_DEVICE
0103     // Access the stream
0104     StreamT get() const;
0105 #else
0106     // Since CUDA/HIP declarations are unavailable, this function cannot be
0107     // used. Include "corecel/DeviceRuntimeApi.hh" to fix.
0108     MissingDeviceRuntime get() const {}
0109 #endif
0110 
0111     // Access the thrust resource allocator associated with the stream
0112     ResourceT& memory_resource();
0113 
0114     // Allocate memory asynchronously on this stream if possible
0115     void* malloc_async(std::size_t bytes);
0116 
0117     // Free memory asynchronously on this stream if possible
0118     void free_async(void* ptr);
0119 
0120     // Block host execution until stream operations are all done
0121     void sync() const;
0122 
0123     // Block stream execution until the event completes
0124     void wait(DeviceEvent const& d);
0125 
0126     // Delayed execution of a host function
0127     void launch_host_func(HostKernel func, void* data);
0128 
0129   private:
0130     struct Impl;
0131     struct ImplDeleter
0132     {
0133         void operator()(Impl*) noexcept;
0134     };
0135     std::unique_ptr<Impl, ImplDeleter> impl_;
0136 };
0137 
0138 //---------------------------------------------------------------------------//
0139 /*!
0140  * Whether the stream is valid (not null or moved-from).
0141  */
0142 Stream::operator bool() const
0143 {
0144     return static_cast<bool>(impl_);
0145 }
0146 
0147 //---------------------------------------------------------------------------//
0148 }  // namespace celeritas