Memory Management

All Thrust functionalities related to memory allocation and deallocation.

Groups

• Allocators
• Memory Resources

template <typename T> class thrust::device_reference;
/* device_ptr is a pointer-like object which points to an object that resides in memory associated with the device system. */template <typename T> class thrust::device_ptr;
template <typename T> void device_delete(thrust::device_ptr< T > ptr,   const size_t n = 1);
void device_free(thrust::device_ptr< void > ptr);
thrust::device_ptr< void > device_malloc(const std::size_t n);
template <typename T> device_ptr< T > device_new(device_ptr< void > p,   const size_t n = 1);
template <typename T> device_ptr< T > device_new(device_ptr< void > p,   const T & exemplar,   const size_t n = 1);
template <typename T> device_ptr< T > device_new(const size_t n = 1);
template <typename T,   typename CharT,   typename Traits> _CCCL_HOST std::basic_ostream< CharT, Traits > & operator<<(std::basic_ostream< CharT, Traits > & os,   device_ptr< T > const & dp);
/* Create a device_ptr from a raw pointer. */template <typename T> _CCCL_HOST_DEVICE device_ptr< T > device_pointer_cast(T * ptr);
/* Create a device_ptr from another device_ptr. */template <typename T> _CCCL_HOST_DEVICE device_ptr< T > device_pointer_cast(device_ptr< T > const & dptr);
template <typename T> _CCCL_HOST_DEVICE void swap(device_reference< T > & x,   device_reference< T > & y);
template <typename T,   typename charT,   typename traits> std::basic_ostream< charT, traits > & operator<<(std::basic_ostream< charT, traits > & os,   const device_reference< T > & y);
template <typename DerivedPolicy> _CCCL_HOST_DEVICE pointer< void, DerivedPolicy > malloc(const thrust::detail::execution_policy_base< DerivedPolicy > & system,   std::size_t n);
template <typename T,   typename DerivedPolicy> _CCCL_HOST_DEVICE pointer< T, DerivedPolicy > malloc(const thrust::detail::execution_policy_base< DerivedPolicy > & system,   std::size_t n);
template <typename T,   typename DerivedPolicy> _CCCL_HOST_DEVICE thrust::pair< thrust::pointer< T, DerivedPolicy >, typename thrust::pointer< T, DerivedPolicy >::difference_type > get_temporary_buffer(const thrust::detail::execution_policy_base< DerivedPolicy > & system,   typename thrust::pointer< T, DerivedPolicy >::difference_type n);
template <typename DerivedPolicy,   typename Pointer> _CCCL_HOST_DEVICE void free(const thrust::detail::execution_policy_base< DerivedPolicy > & system,   Pointer ptr);
template <typename DerivedPolicy,   typename Pointer> _CCCL_HOST_DEVICE void return_temporary_buffer(const thrust::detail::execution_policy_base< DerivedPolicy > & system,   Pointer p,   std::ptrdiff_t n);
template <typename Pointer> _CCCL_HOST_DEVICE thrust::detail::pointer_traits< Pointer >::raw_pointer raw_pointer_cast(Pointer ptr);
template <typename T> _CCCL_HOST_DEVICE detail::raw_reference< T >::type raw_reference_cast(T & ref);
template <typename T> _CCCL_HOST_DEVICE detail::raw_reference< const T >::type raw_reference_cast(const T & ref);

Member Classes

Class thrust::device_reference

Inherits From: thrust::reference< T, thrust::device_ptr< T >, thrust::device_reference< T > >

Class thrust::device_ptr

device_ptr is a pointer-like object which points to an object that resides in memory associated with the device system.

Inherits From: thrust::pointer< T, thrust::device_system_tag, thrust::device_reference< T >, thrust::device_ptr< T > >

Functions

Function device_delete

template <typename T> void device_delete(thrust::device_ptr< T > ptr,   const size_t n = 1); device_delete deletes a device_ptr allocated with device_new.

Function Parameters:

• ptr The device_ptr to delete, assumed to have been allocated with device_new.
• n The number of objects to destroy at ptr. Defaults to 1 similar to device_new.

See:

• device_ptr
• device_new

Function device_free

void device_free(thrust::device_ptr< void > ptr); device_free deallocates memory allocated by the function device_malloc.

The following code snippet demonstrates how to use device_free to deallocate memory allocated by device_malloc.

#include <thrust/device_malloc.h>
#include <thrust/device_free.h>
...
// allocate some integers with device_malloc
const int N = 100;
thrust::device_ptr<int> int_array = thrust::device_malloc<int>(N);

// manipulate integers
...

// deallocate with device_free
thrust::device_free(int_array);

Function Parameters: ptr: A device_ptr pointing to memory to be deallocated.

See:

• device_ptr
• device_malloc

Function device_malloc

thrust::device_ptr< void > device_malloc(const std::size_t n); This version of device_malloc allocates sequential device storage for bytes.

The following code snippet demonstrates how to use device_malloc to allocate a range of device memory.

#include <thrust/device_malloc.h>
#include <thrust/device_free.h>
...
// allocate some memory with device_malloc
const int N = 100;
thrust::device_ptr<void> void_ptr = thrust::device_malloc(N);

// manipulate memory
...

// deallocate with device_free
thrust::device_free(void_ptr);

This version of device_malloc allocates sequential device storage for new objects of the given type.

The following code snippet demonstrates how to use device_malloc to allocate a range of device memory.

#include <thrust/device_malloc.h>
#include <thrust/device_free.h>
...
// allocate some integers with device_malloc
const int N = 100;
thrust::device_ptr<int> int_array = thrust::device_malloc<int>(N);

// manipulate integers
...

// deallocate with device_free
thrust::device_free(int_array);

Function Parameters:

• n The number of bytes to allocate sequentially in device memory.
• n The number of objects of type T to allocate sequentially in device memory.

Returns:

• A device_ptr to the newly allocated memory.
• A device_ptr to the newly allocated memory.

See:

• device_ptr
• device_free
• device_ptr
• device_free

Function device_new

template <typename T> device_ptr< T > device_new(device_ptr< void > p,   const size_t n = 1); device_new implements the placement new operator for types resident in device memory. device_new calls T’s null constructor on a array of objects in device memory. No memory is allocated by this function.

Function Parameters:

• p A device_ptr to a region of device memory into which to construct one or many Ts.
• n The number of objects to construct at p.

Returns: p, casted to T’s type.

See: device_ptr

Function device_new

template <typename T> device_ptr< T > device_new(device_ptr< void > p,   const T & exemplar,   const size_t n = 1); device_new implements the placement new operator for types resident in device memory. device_new calls T’s copy constructor on a array of objects in device memory. No memory is allocated by this function.

Function Parameters:

• p A device_ptr to a region of device memory into which to construct one or many Ts.
• exemplar The value from which to copy.
• n The number of objects to construct at p.

Returns: p, casted to T’s type.

See:

• device_ptr
• fill

Function device_new

template <typename T> device_ptr< T > device_new(const size_t n = 1); device_new implements the new operator for types resident in device memory. It allocates device memory large enough to hold n new objects of type T.

Function Parameters: n: The number of objects to allocate. Defaults to 1.

Returns: A device_ptr to the newly allocated region of device memory.

Function operator<<

template <typename T,   typename CharT,   typename Traits> _CCCL_HOST std::basic_ostream< CharT, Traits > & operator<<(std::basic_ostream< CharT, Traits > & os,   device_ptr< T > const & dp); Write the address that a device_ptr points to to an output stream.

Function Parameters:

• os The output stream.
• dp The device_ptr to output.

Returns: os.

Function device_pointer_cast

template <typename T> _CCCL_HOST_DEVICE device_ptr< T > device_pointer_cast(T * ptr); Create a device_ptr from a raw pointer.

Template Parameters: T: Any type.

Function Parameters: ptr: A raw pointer to a T in device memory.

Preconditions: ptr points to a location in device memory.

Returns: A device_ptr<T> pointing to ptr.

Function device_pointer_cast

template <typename T> _CCCL_HOST_DEVICE device_ptr< T > device_pointer_cast(device_ptr< T > const & dptr); Create a device_ptr from another device_ptr.

Template Parameters: T: Any type.

Function Parameters: dptr: A device_ptr to a T.

Function swap

template <typename T> _CCCL_HOST_DEVICE void swap(device_reference< T > & x,   device_reference< T > & y); swaps the value of one device_reference with another. x The first device_reference of interest. y The second device_reference of interest.

Function operator<<

template <typename T,   typename charT,   typename traits> std::basic_ostream< charT, traits > & operator<<(std::basic_ostream< charT, traits > & os,   const device_reference< T > & y); Writes to an output stream the value of a device_reference.

Function Parameters:

• os The output stream.
• y The device_reference to output.

Returns: os.

Function malloc

template <typename DerivedPolicy> _CCCL_HOST_DEVICE pointer< void, DerivedPolicy > malloc(const thrust::detail::execution_policy_base< DerivedPolicy > & system,   std::size_t n); This version of malloc allocates untyped uninitialized storage associated with a given system.

The following code snippet demonstrates how to use malloc to allocate a range of memory associated with Thrust’s device system.

#include <thrust/memory.h>
...
// allocate some memory with thrust::malloc
const int N = 100;
thrust::device_system_tag device_sys;
thrust::pointer<void,thrust::device_space_tag> void_ptr = thrust::malloc(device_sys, N);

// manipulate memory
...

// deallocate void_ptr with thrust::free
thrust::free(device_sys, void_ptr);

Template Parameters: DerivedPolicy: The name of the derived execution policy.

Function Parameters:

• system The Thrust system with which to associate the storage.
• n The number of bytes of storage to allocate.

Preconditions: DerivedPolicy must be publically derived from thrust::execution_policy<DerivedPolicy>.

Returns: If allocation succeeds, a pointer to the allocated storage; a null pointer otherwise. The pointer must be deallocated with thrust::free.

See:

• free
• device_malloc

Function malloc

template <typename T,   typename DerivedPolicy> _CCCL_HOST_DEVICE pointer< T, DerivedPolicy > malloc(const thrust::detail::execution_policy_base< DerivedPolicy > & system,   std::size_t n); This version of malloc allocates typed uninitialized storage associated with a given system.

The following code snippet demonstrates how to use malloc to allocate a range of memory to accomodate integers associated with Thrust’s device system.

#include <thrust/memory.h>
...
// allocate storage for 100 ints with thrust::malloc
const int N = 100;
thrust::device_system_tag device_sys;
thrust::pointer<int,thrust::device_system_tag> ptr = thrust::malloc<int>(device_sys, N);

// manipulate memory
...

// deallocate ptr with thrust::free
thrust::free(device_sys, ptr);

Template Parameters: DerivedPolicy: The name of the derived execution policy.

Function Parameters:

• system The Thrust system with which to associate the storage.
• n The number of elements of type T which the storage should accomodate.

Preconditions: DerivedPolicy must be publically derived from thrust::execution_policy<DerivedPolicy>.

Returns: If allocation succeeds, a pointer to an allocation large enough to accomodate n elements of type T; a null pointer otherwise. The pointer must be deallocated with thrust::free.

See:

• free
• device_malloc

Function get_temporary_buffer

template <typename T,   typename DerivedPolicy> _CCCL_HOST_DEVICE thrust::pair< thrust::pointer< T, DerivedPolicy >, typename thrust::pointer< T, DerivedPolicy >::difference_type > get_temporary_buffer(const thrust::detail::execution_policy_base< DerivedPolicy > & system,   typename thrust::pointer< T, DerivedPolicy >::difference_type n); get_temporary_buffer returns a pointer to storage associated with a given Thrust system sufficient to store up to n objects of type T. If not enough storage is available to accomodate n objects, an implementation may return a smaller buffer. The number of objects the returned buffer can accomodate is also returned.

Thrust uses get_temporary_buffer internally when allocating temporary storage required by algorithm implementations.

The storage allocated with get_temporary_buffer must be returned to the system with return_temporary_buffer.

The following code snippet demonstrates how to use get_temporary_buffer to allocate a range of memory to accomodate integers associated with Thrust’s device system.

#include <thrust/memory.h>
...
// allocate storage for 100 ints with thrust::get_temporary_buffer
const int N = 100;

typedef thrust::pair<
  thrust::pointer<int,thrust::device_system_tag>,
  std::ptrdiff_t
> ptr_and_size_t;

thrust::device_system_tag device_sys;
ptr_and_size_t ptr_and_size = thrust::get_temporary_buffer<int>(device_sys, N);

// manipulate up to 100 ints
for(int i = 0; i < ptr_and_size.second; ++i)
{
  *ptr_and_size.first = i;
}

// deallocate storage with thrust::return_temporary_buffer
thrust::return_temporary_buffer(device_sys, ptr_and_size.first);

Template Parameters: DerivedPolicy: The name of the derived execution policy.

Function Parameters:

• system The Thrust system with which to associate the storage.
• n The requested number of objects of type T the storage should accomodate.

Preconditions: DerivedPolicy must be publically derived from thrust::execution_policy<DerivedPolicy>.

Returns: A pair p such that p.first is a pointer to the allocated storage and p.second is the number of contiguous objects of type T that the storage can accomodate. If no storage can be allocated, p.first if no storage can be obtained. The storage must be returned to the system using return_temporary_buffer.

See:

• malloc
• return_temporary_buffer

Function free

template <typename DerivedPolicy,   typename Pointer> _CCCL_HOST_DEVICE void free(const thrust::detail::execution_policy_base< DerivedPolicy > & system,   Pointer ptr); free deallocates the storage previously allocated by thrust::malloc.

The following code snippet demonstrates how to use free to deallocate a range of memory previously allocated with thrust::malloc.

#include <thrust/memory.h>
...
// allocate storage for 100 ints with thrust::malloc
const int N = 100;
thrust::device_system_tag device_sys;
thrust::pointer<int,thrust::device_system_tag> ptr = thrust::malloc<int>(device_sys, N);

// mainpulate memory
...

// deallocate ptr with thrust::free
thrust::free(device_sys, ptr);

Template Parameters: DerivedPolicy: The name of the derived execution policy.

Function Parameters:

• system The Thrust system with which the storage is associated.
• ptr A pointer previously returned by thrust::malloc. If ptr is null, free does nothing.

Preconditions: ptr shall have been returned by a previous call to thrust::malloc(system, n) or thrust::malloc<T>(system, n) for some type T.

Function return_temporary_buffer

template <typename DerivedPolicy,   typename Pointer> _CCCL_HOST_DEVICE void return_temporary_buffer(const thrust::detail::execution_policy_base< DerivedPolicy > & system,   Pointer p,   std::ptrdiff_t n); return_temporary_buffer deallocates storage associated with a given Thrust system previously allocated by get_temporary_buffer.

Thrust uses return_temporary_buffer internally when deallocating temporary storage required by algorithm implementations.

The following code snippet demonstrates how to use return_temporary_buffer to deallocate a range of memory previously allocated by get_temporary_buffer.

#include <thrust/memory.h>
...
// allocate storage for 100 ints with thrust::get_temporary_buffer
const int N = 100;

typedef thrust::pair<
  thrust::pointer<int,thrust::device_system_tag>,
  std::ptrdiff_t
> ptr_and_size_t;

thrust::device_system_tag device_sys;
ptr_and_size_t ptr_and_size = thrust::get_temporary_buffer<int>(device_sys, N);

// manipulate up to 100 ints
for(int i = 0; i < ptr_and_size.second; ++i)
{
  *ptr_and_size.first = i;
}

// deallocate storage with thrust::return_temporary_buffer
thrust::return_temporary_buffer(device_sys, ptr_and_size.first);

Template Parameters: DerivedPolicy: The name of the derived execution policy.

Function Parameters:

• system The Thrust system with which the storage is associated.
• p A pointer previously returned by thrust::get_temporary_buffer. If ptr is null, return_temporary_buffer does nothing.

Preconditions: p shall have been previously allocated by thrust::get_temporary_buffer.

See:

• free
• get_temporary_buffer

Function raw_pointer_cast

template <typename Pointer> _CCCL_HOST_DEVICE thrust::detail::pointer_traits< Pointer >::raw_pointer raw_pointer_cast(Pointer ptr); raw_pointer_cast creates a “raw” pointer from a pointer-like type, simply returning the wrapped pointer, should it exist.

Function Parameters: ptr: The pointer of interest.

Returns: ptr.get(), if the expression is well formed; ptr, otherwise.

See: raw_reference_cast

Function raw_reference_cast

template <typename T> _CCCL_HOST_DEVICE detail::raw_reference< T >::type raw_reference_cast(T & ref); raw_reference_cast creates a “raw” reference from a wrapped reference type, simply returning the underlying reference, should it exist.

If the argument is not a reference wrapper, the result is a reference to the argument.

Note: There are two versions of raw_reference_cast. One for const references, and one for non-const.

Function Parameters: ref: The reference of interest.

Returns: *thrust::raw_pointer_cast(&ref).

See: raw_pointer_cast

Function raw_reference_cast

template <typename T> _CCCL_HOST_DEVICE detail::raw_reference< const T >::type raw_reference_cast(const T & ref); raw_reference_cast creates a “raw” reference from a wrapped reference type, simply returning the underlying reference, should it exist.

If the argument is not a reference wrapper, the result is a reference to the argument.

Note: There are two versions of raw_reference_cast. One for const references, and one for non-const.

Function Parameters: ref: The reference of interest.

Returns: *thrust::raw_pointer_cast(&ref).

See: raw_pointer_cast