doc: update doc explaining how to limit amount of memory on devices

ChangeLog

@@ -94,6 +94,11 @@ New features:
     STARPU_LIMIT_OPENCL_devid_MEM to limit memory per specific device
   * Introduce new variable STARPU_LIMIT_CPU_MEM to limit memory for
     the CPU devices
+  * Define new functions starpu_malloc_count and starpu_free_count to
+    be used for allocating memory up to the limits defined by the
+    environment variables STARPU_LIMIT_xxx (see above). When no memory
+    is left, starpu_malloc_count tries to reclaim memory from StarPU
+    and returns -ENOMEM on failure.
 
 Small features:
   * Add starpu_worker_get_by_type and starpu_worker_get_by_devid

doc/chapters/basic-api.texi

@@ -9,6 +9,7 @@
 @menu
 * Versioning::
 * Initialization and Termination::
+* Standard memory library::
 * Workers' Properties::
 * Data Management::
 * Data Interfaces::
@@ -235,6 +236,43 @@ Return 1 if asynchronous data transfers between CPU and OpenCL accelerators
 are disabled.
 @end deftypefun
 
+@node Standard memory library
+@section Standard memory library
+
+@deftypefun int starpu_malloc (void **@var{A}, size_t @var{dim})
+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 @code{starpu_free} function.
+@end deftypefun
+
+@deftypefun void starpu_malloc_set_align (size_t @var{align})
+This functions sets an alignment constraints for @code{starpu_malloc}
+allocations. @var{align} must be a power of two. This is for instance called
+automatically by the OpenCL driver to specify its own alignment constraints.
+@end deftypefun
+
+@deftypefun int starpu_free (void *@var{A})
+This function frees memory which has previously allocated with
+@code{starpu_malloc}.
+@end deftypefun
+
+@deftypefun int starpu_malloc_count (void **@var{A}, size_t @var{dim})
+This function is similar to @code{starpu_malloc}. It only allocates
+memory up to the limit defined by the environment variables
+@code{STARPU_LIMIT_CUDA_devid_MEM}, @code{STARPU_LIMIT_CUDA_MEM},
+@code{STARPU_LIMIT_OPENCL_devid_MEM}, @code{STARPU_LIMIT_OPENCL_MEM}
+and @code{STARPU_LIMIT_CPU_MEM} (@pxref{Limit memory}). If no memory
+is available, it tries to reclaim memory from StarPU.
+Memory allocated through this function needs to be freed thanks to the
+@code{starpu_free_count} function.
+@end deftypefun
+
+@deftypefun int starpu_free_count (void *@var{A}, size_t @var{dim})
+This function frees memory which has previously allocated with
+@code{starpu_malloc_count}.
+@end deftypefun
+
 @node Workers' Properties
 @section Workers' Properties
 
@@ -400,24 +438,6 @@ data).
 @node Basic Data Management API
 @subsection Basic Data Management API
 
-@deftypefun int starpu_malloc (void **@var{A}, size_t @var{dim})
-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 @code{starpu_free} function.
-@end deftypefun
-
-@deftypefun void starpu_malloc_set_align (size_t @var{align})
-This functions sets an alignment constraints for @code{starpu_malloc}
-allocations. @var{align} must be a power of two. This is for instance called
-automatically by the OpenCL driver to specify its own alignment constraints.
-@end deftypefun
-
-@deftypefun int starpu_free (void *@var{A})
-This function frees memory which has previously allocated with
-@code{starpu_malloc}.
-@end deftypefun
-
 @deftp {Data Type} {enum starpu_access_mode}
 This datatype describes a data access mode. The different available modes are:
 @table @asis

doc/chapters/configuration.texi

@@ -627,6 +627,13 @@ intended to be used for experimental purposes as it emulates devices
 that have a limited amount of memory.
 @end defvr
 
+@defvr {Environment variable} STARPU_LIMIT_CPU_MEM
+This variable specifies the maximum number of megabytes that should be
+available to the application on each CPU device. This variable is
+intended to be used for experimental purposes as it emulates devices
+that have a limited amount of memory.
+@end defvr
+
 @defvr {Environment variable} STARPU_GENERATE_TRACE
 When set to @code{1}, this variable indicates that StarPU should automatically
 generate a Paje trace when @code{starpu_shutdown()} is called.

doc/chapters/tips-tricks.texi

@@ -2,12 +2,13 @@
 
 @c This file is part of the StarPU Handbook.
 @c Copyright (C) 2009--2011  Universit@'e de Bordeaux 1
-@c Copyright (C) 2010, 2011, 2012  Centre National de la Recherche Scientifique
+@c Copyright (C) 2010, 2011, 2012, 2013  Centre National de la Recherche Scientifique
 @c Copyright (C) 2011 Institut National de Recherche en Informatique et Automatique
 @c See the file starpu.texi for copying conditions.
 
 @menu
 * Per-worker library initialization::  How to initialize a computation library once for each worker?
+* Limit memory::
 @end menu
 
 @node Per-worker library initialization
@@ -77,3 +78,14 @@ void starpu_cublas_init(void)
 @}
 @end smallexample
 @end cartouche
+
+@node Limit memory
+@section How to limit memory per node
+
+TODO
+
+Talk about
+@code{STARPU_LIMIT_CUDA_devid_MEM}, @code{STARPU_LIMIT_CUDA_MEM},
+@code{STARPU_LIMIT_OPENCL_devid_MEM}, @code{STARPU_LIMIT_OPENCL_MEM}
+and @code{STARPU_LIMIT_CPU_MEM}
+