StarPU Handbook
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Standard Memory Library

Macros

#define starpu_data_malloc_pinned_if_possible
#define starpu_data_free_pinned_if_possible
#define STARPU_MALLOC_PINNED
#define STARPU_MALLOC_COUNT
#define STARPU_MALLOC_NORECLAIM
#define STARPU_MALLOC_SIMULATION_FOLDED
#define STARPU_MEMORY_WAIT
#define STARPU_MEMORY_OVERFLOW

Functions

int starpu_malloc_flags (void **A, size_t dim, int flags) STARPU_ATTRIBUTE_ALLOC_SIZE(2)
void starpu_malloc_set_align (size_t align)
int starpu_malloc (void **A, size_t dim) STARPU_ATTRIBUTE_ALLOC_SIZE(2)
int starpu_free (void *A)
int starpu_free_flags (void *A, size_t dim, int flags)
int starpu_memory_pin (void *addr, size_t size)
int starpu_memory_unpin (void *addr, size_t size)
starpu_ssize_t starpu_memory_get_total (unsigned node)
starpu_ssize_t starpu_memory_get_available (unsigned node)
int starpu_memory_allocate (unsigned node, size_t size, int flags)
void starpu_memory_deallocate (unsigned node, size_t size)
void starpu_memory_wait_available (unsigned node, size_t size)

Detailed Description

Macro Definition Documentation

#define starpu_data_malloc_pinned_if_possible
Deprecated:
Equivalent to starpu_malloc(). This macro is provided to avoid breaking old codes.
#define starpu_data_free_pinned_if_possible
Deprecated:
Equivalent to starpu_free(). This macro is provided to avoid breaking old codes.
#define STARPU_MALLOC_PINNED

Value passed to the function starpu_malloc_flags() to indicate the memory allocation should be pinned.

#define STARPU_MALLOC_COUNT

Value passed to the function starpu_malloc_flags() to indicate the memory allocation should be in the limit defined by the environment variables STARPU_LIMIT_CUDA_devid_MEM, STARPU_LIMIT_CUDA_MEM, STARPU_LIMIT_OPENCL_devid_MEM, STARPU_LIMIT_OPENCL_MEM and STARPU_LIMIT_CPU_MEM (see Section How to Limit Memory Used By StarPU And Cache Buffer Allocations). If no memory is available, it tries to reclaim memory from StarPU. Memory allocated this way needs to be freed by calling the function starpu_free_flags() with the same flag.

#define STARPU_MALLOC_NORECLAIM

Value passed to the function starpu_malloc_flags() along STARPU_MALLOC_COUNT to indicate that while the memory allocation should be kept in the limits defined for STARPU_MALLOC_COUNT, no reclaiming should be performed by starpu_malloc_flags itself, thus potentially overflowing the memory node a bit. StarPU will reclaim memory after next task termination, according to the STARPU_MINIMUM_AVAILABLE_MEM and STARPU_TARGET_AVAILABLE_MEM environment variables. If STARPU_MEMORY_WAIT is set, no overflowing will happen, starpu_malloc_flags() will wait for other eviction mechanisms to release enough memory.

#define STARPU_MALLOC_SIMULATION_FOLDED

Value passed to the function starpu_malloc_flags() to indicate that when StarPU is using simgrid, the allocation can be "folded", i.e. a memory area is allocated, but its content is actually a replicate of the same memory area, to avoid having to actually allocate that much memory . This thus allows to have a memory area that does not actually consumes memory, to which one can read from and write to normally, but get bogus values.

#define STARPU_MEMORY_WAIT

Value passed to starpu_memory_allocate() to specify that the function should wait for the requested amount of memory to become available, and atomically allocate it.

#define STARPU_MEMORY_OVERFLOW

Value passed to starpu_memory_allocate() to specify that the function should allocate the amount of memory, even if that means overflowing the total size of the memory node.

Function Documentation

int starpu_malloc_flags ( void **  A,
size_t  dim,
int  flags 
)

Performs a memory allocation based on the constraints defined by the given flag.

void starpu_malloc_set_align ( size_t  align)

This function sets an alignment constraints for starpu_malloc() allocations. align must be a power of two. This is for instance called automatically by the OpenCL driver to specify its own alignment constraints.

int starpu_malloc ( void **  A,
size_t  dim 
)

This function allocates data of the given size dim in main memory, and returns the pointer to the allocated data through A. It will also try to pin it in CUDA or OpenCL, so that data transfers from this buffer can be asynchronous, and thus permit data transfer and computation overlapping. The allocated buffer must be freed thanks to the starpu_free() function.

int starpu_free ( void *  A)

This function frees memory which has previously been allocated with starpu_malloc().

int starpu_free_flags ( void *  A,
size_t  dim,
int  flags 
)

This function frees memory by specifying its size. The given flags should be consistent with the ones given to starpu_malloc_flags() when allocating the memory.

int starpu_memory_pin ( void *  addr,
size_t  size 
)

This function pins the given memory area, so that CPU-GPU transfers can be done asynchronously with DMAs. The memory must be unpinned with starpu_memory_unpin() before being freed. Returns 0 on success, -1 on error.

int starpu_memory_unpin ( void *  addr,
size_t  size 
)

This function unpins the given memory area previously pinned with starpu_memory_pin(). Returns 0 on success, -1 on error.

ssize_t starpu_memory_get_total ( unsigned  node)

If a memory limit is defined on the given node (see Section How to Limit Memory Used By StarPU And Cache Buffer Allocations), return the amount of total memory on the node. Otherwise return -1.

ssize_t starpu_memory_get_available ( unsigned  node)

If a memory limit is defined on the given node (see Section How to Limit Memory Used By StarPU And Cache Buffer Allocations), return the amount of available memory on the node. Otherwise return -1.

int starpu_memory_allocate ( unsigned  node,
size_t  size,
int  flags 
)

Try to allocate memory on the given node

Parameters
sizeamount of memory to allocate
nodenode where the memory is to be allocated
Returns
1 if the given amount of memory was allocated on the given node

If a memory limit is defined on the given node (see Section How to Limit Memory Used By StarPU And Cache Buffer Allocations), try to allocate some of it. This does not actually allocate memory, but only accounts for it. This can be useful when the application allocates data another way, but want StarPU to be aware of the allocation size e.g. for memory reclaiming. By default, the function returns -ENOMEM if there is not enough room on the given node. flags can be either STARPU_MEMORY_WAIT or STARPU_MEMORY_OVERFLOW to change this.

void starpu_memory_deallocate ( unsigned  node,
size_t  size 
)

Indicates the given amount of memory is going to be deallocated from the given node

Parameters
sizeamount of memory to be deallocated
nodenode where the memory is going to be deallocated

If a memory limit is defined on the given node (see Section How to Limit Memory Used By StarPU And Cache Buffer Allocations), free some of it. This does not actually free memory, but only accounts for it, like starpu_memory_allocate(). The amount does not have to be exactly the same as what was passed to starpu_memory_allocate(), only the eventual amount needs to be the same, i.e. one call to starpu_memory_allocate() can be followed by several calls to starpu_memory_deallocate() to declare the deallocation piece by piece.

void starpu_memory_wait_available ( unsigned  node,
size_t  size 
)

If a memory limit is defined on the given node (see Section How to Limit Memory Used By StarPU And Cache Buffer Allocations), this will wait for size bytes to become available on node. Of course, since another thread may be allocating memory concurrently, this does not necessarily mean that this amount will be actually available, just that it was reached. To atomically wait for some amount of memory and reserve it, starpu_memory_allocate() should be used with the STARPU_MEMORY_WAIT flag.