starpu-max/doc/doxygen/chapters/api/standard_memory_library.doxy

/*
 * This file is part of the StarPU Handbook.
 * Copyright (C) 2009--2011  Universit@'e de Bordeaux
 * Copyright (C) 2010, 2011, 2012, 2013  Centre National de la Recherche Scientifique
 * Copyright (C) 2011, 2012 Institut National de Recherche en Informatique et Automatique
 * See the file version.doxy for copying conditions.
 */

/*! \defgroup API_Standard_Memory_Library Standard Memory Library

\def starpu_data_malloc_pinned_if_possible
\ingroup API_Standard_Memory_Library
\deprecated
Equivalent to starpu_malloc(). This macro is provided to avoid breaking old codes.

\def starpu_data_free_pinned_if_possible
\ingroup API_Standard_Memory_Library
\deprecated
Equivalent to starpu_free(). This macro is provided to avoid breaking old codes.

\def STARPU_MALLOC_PINNED
\ingroup API_Standard_Memory_Library
Value passed to the function starpu_malloc_flags() to indicate the memory allocation should be pinned.

\def STARPU_MALLOC_COUNT
\ingroup API_Standard_Memory_Library
Value passed to the function starpu_malloc_flags() to indicate
the memory allocation should be in the limit defined by the
environment variables \ref STARPU_LIMIT_CUDA_devid_MEM,
\ref STARPU_LIMIT_CUDA_MEM, \ref STARPU_LIMIT_OPENCL_devid_MEM,
\ref STARPU_LIMIT_OPENCL_MEM and \ref STARPU_LIMIT_CPU_MEM (see
Section \ref HowToLimitMemoryPerNode).
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.

\def STARPU_MALLOC_NORECLAIM
\ingroup API_Standard_Memory_Library
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.

\fn int starpu_malloc_flags(void **A, size_t dim, int flags)
\ingroup API_Standard_Memory_Library
Performs a memory allocation based on the constraints defined
by the given flag.

\fn void starpu_malloc_set_align(size_t align)
\ingroup API_Standard_Memory_Library
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.

\fn int starpu_malloc(void **A, size_t dim)
\ingroup API_Standard_Memory_Library
This function allocates data of the given size in main memory.
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.

\fn int starpu_free(void *A)
\ingroup API_Standard_Memory_Library
This function frees memory which has previously been allocated
with starpu_malloc().

\fn int starpu_free_flags(void *A, size_t dim, int flags)
\ingroup API_Standard_Memory_Library
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.

\fn ssize_t starpu_memory_get_total(unsigned node)
\ingroup API_Standard_Memory_Library
If a memory limit is defined on the given node (see Section \ref
HowToLimitMemoryPerNode), return the amount of total memory
on the node. Otherwise return -1.

\fn ssize_t starpu_memory_get_available(unsigned node)
\ingroup API_Standard_Memory_Library
If a memory limit is defined on the given node (see Section \ref
HowToLimitMemoryPerNode), return the amount of available memory
on the node. Otherwise return -1.

*/