Celeritas 0.7-develop+fa62b79
Loading...
Searching...
No Matches
Public Member Functions | List of all members
celeritas::AsyncCompactedCopy< T > Class Template Reference

Compact valid device items and copy them to the host without waiting. More...

#include <AsyncCompactedCopy.hh>

Public Types

Type aliases
using SpanConstT = Span< T const >
 
using VecT = std::vector< T, PinnedAllocator< T > >
 

Public Member Functions

 AsyncCompactedCopy ()=default
 Construct without storage.
 
 AsyncCompactedCopy (size_type capacity, StreamId stream)
 Allocate device scratch and pinned host storage for a stream.
 
 ~AsyncCompactedCopy ()
 Wait for any pending compaction or copy before releasing buffers.
 
AsyncCompactedCopy & operator= (AsyncCompactedCopy &&other) noexcept(ndebug)
 Replace the storage, leaving the old storage to be released by the other.
 
size_type capacity () const
 Maximum number of items.
 
 operator bool () const
 Whether storage is allocated.
 
bool has_compacted () const
 Whether compacted items are waiting to be copied.
 
bool has_copied () const
 Whether copied items are waiting to be taken.
 
void compact_async (ObserverPtr< T const, MemSpace::device > items, size_type count)
 Enqueue compaction of the valid items on the stream.
 
void copy_async ()
 Enqueue the copy of the compacted items on the memcpy stream.
 
SpanConstT take_copied ()
 Wait for the copied items and release them to the caller.
 
 AsyncCompactedCopy (AsyncCompactedCopy const &)=delete
 
 AsyncCompactedCopy (AsyncCompactedCopy &&)=delete
 
AsyncCompactedCopy & operator= (AsyncCompactedCopy const &)=delete
 

Detailed Description

template<class T>
class celeritas::AsyncCompactedCopy< T >

Compact valid device items and copy them to the host without waiting.

This transfers the items that evaluate to true (e.g., detector hits with a valid detector ID) from a per-track-slot device array to pinned host memory in three phases, so that the transfer overlaps with later kernels and the host only reads the number of items once it is available:

  1. Compacted: compact_async enqueues on the given stream the stable selection of the valid items into a device scratch buffer, followed by an asynchronous copy of their number to pinned host memory. The compaction waits on the device for any previous copy out of the scratch buffer.
  2. Copied: once the compaction is complete (for example because the host waited on a later event on the same stream), copy_async reads the number of items and enqueues the copy of exactly that many items to the pinned host output on the device's memcpy_stream .
  3. Processed: take_copied waits for the copy and returns the items, which remain valid until the next call to copy_async .

The scratch buffer and host output form a two-stage pipeline: the items of step n+1 can be compacted while the items of step n are being copied or processed. A single host output therefore suffices if the host waits for each step to complete before starting the next one. Those phases describe one set of items: each buffer has its own state, with the scratch free or compacted and the output empty or copied , and any combination of the two can occur.

// At the end of step n
if (copier.has_compacted())
{
process(copier.take_copied()); // step n-2
copier.copy_async(); // step n-1
}
copier.compact_async(device_items.data(), device_items.size()); // step n

The device operations are defined in AsyncCompactedCopy.device.t.hh : one device source file must include it and explicitly instantiate this class for each item type.

Constructor & Destructor Documentation

◆ ~AsyncCompactedCopy()

Wait for any pending compaction or copy before releasing buffers.

The number of compacted items and the copied items are written asynchronously into pinned memory owned by this class, so pending copies must complete before that memory is freed (e.g., when an exception unwinds the transport loop mid-step).

◆ AsyncCompactedCopy() [1/2]

template<class T >
celeritas::AsyncCompactedCopy< T >::AsyncCompactedCopy ( AsyncCompactedCopy< T > const &  )
delete

Prevent copying and move construction

◆ AsyncCompactedCopy() [2/2]

template<class T >
celeritas::AsyncCompactedCopy< T >::AsyncCompactedCopy ( AsyncCompactedCopy< T > &&  )
delete

Prevent copying and move construction

Member Function Documentation

◆ compact_async()

template<class T >
void celeritas::AsyncCompactedCopy< T >::compact_async ( ObserverPtr< T const, MemSpace::device >  items,
size_type  count 
)

Enqueue compaction of the valid items on the stream.

The device items must remain unchanged until the compaction completes, which is guaranteed if they are only modified by later work on the same stream. The previously compacted items must have been copied.

◆ copy_async()

template<class T >
void celeritas::AsyncCompactedCopy< T >::copy_async ( )

Enqueue the copy of the compacted items on the memcpy stream.

This reads the number of compacted items on the host, waiting for the compaction if it is not yet complete. The previously copied items must have been taken.

◆ operator=() [1/2]

template<class T >
auto celeritas::AsyncCompactedCopy< T >::operator= ( AsyncCompactedCopy< T > &&  other)
inlinenoexcept

Replace the storage, leaving the old storage to be released by the other.

All items must have been taken, since any others would never reach the caller. If they haven't, in a release build the items are dropped, but the old storage is still safe from pending work: it is swapped into other , whose destructor waits for any compaction or copy before releasing it. Any span previously returned by take_copied is invalidated.

◆ operator=() [2/2]

Prevent copying and move construction

◆ take_copied()

template<class T >
auto celeritas::AsyncCompactedCopy< T >::take_copied ( )
inline

Wait for the copied items and release them to the caller.

The returned items are valid until the next call to copy_async . If no items are being copied, an empty span is returned.


The documentation for this class was generated from the following files: