corecel/data/Ref.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/Ref.hh
0006 //! \brief Helper functions for memspace-specific references
0007 //---------------------------------------------------------------------------//
0008 #pragma once
0009
0010 #include "corecel/Types.hh"
0011
0012 #include "detail/RefImpl.hh"
0013
0014 namespace celeritas
0015 {
0016 //---------------------------------------------------------------------------//
0017 /*!
0018  * Construct a reference object pointing to state data.
0019  *
0020  * Since the "reference" type is a value whose scope must extend beyond all
0021  * references to it, it's often necessary to create a "reference" instance from
0022  * a "value" instance. Collection groups don't define templated copy
0023  * constructors, so this function (and the others like it) provide a
0024  * workaround.
0025  *
0026  * \code
0027    auto my_states = make_ref(my_state_values);
0028  * \endcode
0029  */
0030 template<template<Ownership, MemSpace> class S, MemSpace M>
0031 inline S<Ownership::reference, M> make_ref(S<Ownership::value, M>& states)
0032 {
0033     S<Ownership::reference, M> result;
0034     result = states;
0035     return result;
0036 }
0037
0038 //---------------------------------------------------------------------------//
0039 /*!
0040  * Construct a reference object pointing to params data.
0041  */
0042 template<template<Ownership, MemSpace> class P, MemSpace M>
0043 inline P<Ownership::const_reference, M>
0044 make_ref(P<Ownership::value, M> const& params)
0045 {
0046     P<Ownership::const_reference, M> result;
0047     result = params;
0048     return result;
0049 }
0050
0051 //---------------------------------------------------------------------------//
0052 /*!
0053  * Construct a const reference object pointing to params data.
0054  */
0055 template<template<Ownership, MemSpace> class P, MemSpace M>
0056 inline decltype(auto) make_const_ref(P<Ownership::value, M> const& params)
0057 {
0058     return make_ref(params);
0059 }
0060
0061 //---------------------------------------------------------------------------//
0062 /*!
0063  * Get a reference to memory-spaced data owned by a params/state object.
0064  *
0065  * The object must have \c host_ref and \c device_ref accessors depending on
0066  * the value of \c M.
0067  */
0068 template<MemSpace M, class T>
0069 decltype(auto) get_ref(T&& obj)
0070 {
0071     return detail::RefGetter<T, M>{std::forward<T>(obj)}();
0072 }
0073
0074 //---------------------------------------------------------------------------//
0075 /*!
0076  * Copy an entire collection group to the host.
0077  *
0078  * This is mostly useful for debugging and testing. It is \em not performant
0079  * and should not be used as part of the stepping loop, since it is likely to
0080  * perform many allocations.
0081  *
0082  * \code
0083    auto my_states = make_host_val(states.device_ref());
0084  * \endcode
0085  */
0086 template<template<Ownership, MemSpace> class CG, Ownership W, MemSpace M>
0087 inline auto make_host_val(CG<W, M> const& source)
0088 {
0089     CG<Ownership::value, MemSpace::host> result;
0090     // Assign from mutable value since the "state" collections require it
0091     result = const_cast<CG<W, M>&>(source);
0092     return result;
0093 }
0094
0095 //---------------------------------------------------------------------------//
0096 }  // namespace celeritas