add docstring

Author: AlexanderSinn

Src/Base/AMReX_GpuDevice.H

@@ -268,6 +268,15 @@ streamSynchronizeAll () noexcept
     Device::streamSynchronizeAll();
 }
 
+/** Deallocate memory belonging to an arena asynchronously.
+ * Memory deallocated in this way is held in a pool and will not be reused until
+ * the next amrex::Gpu::streamSynchronize(). GPU kernels that were already launched on the
+ * currently active stream can still continue to use the memory after this function is called.
+ * There is no need to use this function for CPU-only memory or with The_Async_Arena.
+ *
+ * \param[in] arena the arena the memory belongs to
+ * \param[in] mem pointer to the memory to be freed
+ */
 inline void
 streamFree (Arena* arena, void* mem) noexcept
 {

Src/Base/AMReX_PODVector.H

@@ -834,6 +834,11 @@ namespace amrex
             std::swap(static_cast<Allocator&>(a_vector), static_cast<Allocator&>(*this));
         }
 
+        /** Deallocate the memory of the PODVector using amrex::Gpu::streamFree.
+         * Memory deallocated in this way is held in a pool and will not be reused until the next
+         * amrex::Gpu::streamSynchronize(). GPU kernels that were already launched on the currently
+         * active stream can still continue to use the memory after this function is called.
+         */
         void stream_free () noexcept
         {
             if (m_data != nullptr) {
@@ -843,6 +848,8 @@ namespace amrex
                     deallocate(m_data, capacity());
                 }
                 m_data = nullptr;
+                m_size = 0;
+                m_capacity = 0;
             }
         }
 

Src/Particle/AMReX_ParticleUtil.H

@@ -632,7 +632,8 @@ partitionParticles (PTile& ptile, int num_left, ParFunc const& is_left)
             }
         });
 
-    Gpu::streamSynchronize(); // for index_left and index_right deallocation
+    index_left.stream_free();
+    index_right.stream_free();
 }
 
 template <typename PTile>