/* StarPU --- Runtime system for heterogeneous multicore architectures.
 *
 * Copyright (C) 2013-2014,2016-2017                      CNRS
 * Copyright (C) 2013                                     Inria
 * Copyright (C) 2013-2014,2017                           Université de Bordeaux
 * Copyright (C) 2013                                     Corentin Salingue
 *
 * StarPU is free software; you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation; either version 2.1 of the License, or (at
 * your option) any later version.
 *
 * StarPU is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 *
 * See the GNU Lesser General Public License in COPYING.LGPL for more details.
 */

/*! \page OutOfCore Out Of Core

\section Introduction Introduction

When using StarPU, one may need to store more data than what the main memory
(RAM) can store. This part describes the method to add a new memory node on a
disk and to use it.

The principle is that one first registers a disk location, seen by StarPU as
a <c>void*</c>, which can be for instance a Unix path for the stdio, unistd or unistd_o_direct case,
or a database file path for a leveldb case, etc. The disk backend opens this
place with the plug method.

If the disk backend provides an alloc method, StarPU can then start using it
to allocate room and store data there with the write method, without user
intervention.

The user can also use starpu_disk_open() to explicitly open an object within the
disk, e.g. a file name in the stdio or unistd cases, or a database key in the
leveldb case, and then use <c>starpu_*_register</c> functions to turn it into a StarPU
data handle. StarPU will then automatically read and write data as appropriate.

\section UseANewDiskMemory Use a new disk memory

To use a disk memory node, you have to register it with this function:

\code{.c}
	int new_dd = starpu_disk_register(&starpu_disk_unistd_ops, (void *) "/tmp/", 1024*1024*200);
\endcode

Here, we use the unistd library to realize the read/write operations, i.e.
fread/fwrite. This structure must have a path where to store files, as well as
the maximum size the software can afford storing on the disk.

Don't forget to check if the result is correct!

This can also be achieved by just setting environment variables:

\verbatim
export STARPU_DISK_SWAP=/tmp
export STARPU_DISK_SWAP_BACKEND=unistd
export STARPU_DISK_SWAP_SIZE=200
\endverbatim

The backend can be set to stdio, unistd, unistd_o_direct, or leveldb.

When the register function is called, StarPU will benchmark the disk. This can
take some time.

<strong>Warning: the size thus has to be at least \ref STARPU_DISK_SIZE_MIN bytes ! </strong> 

StarPU will automatically try to evict unused data to this new disk. One can
also use the standard StarPU memory node API, see the \ref API_Standard_Memory_Library
and the \ref API_Data_Interfaces .

The disk is unregistered during the starpu_shutdown().

\section DiskFunctions Disk functions

There are various ways to operate a disk memory node, described by the structure
starpu_disk_ops. For instance, the variable #starpu_disk_unistd_ops
uses read/write functions.

All structures are in \ref API_Out_Of_Core.

\section ExampleDiskCopy Examples: disk_copy

\snippet disk_copy.c To be included. You should update doxygen if you see this text.

\section ExampleDiskCompute Examples: disk_compute

\snippet disk_compute.c To be included. You should update doxygen if you see this text.

*/