/*
 * This file is part of the StarPU Handbook.
 * Copyright (C) 2013 Corentin Salingue
 * See the file version.doxy for copying conditions.
 */


/*! \defgroup API_Out_Of_Core Out Of Core

\struct starpu_disk_ops
\ingroup API_Out_Of_Core
This is a set of functions to manipulate datas on disk.

\var void* (*starpu_disk_ops::alloc)(void *base, size_t size)
Create a new location for datas of size \p size. This returns an opaque object pointer.

\var void (*starpu_disk_ops::free)(void *base, void *obj, size_t size)
Free a data \p obj previously allocated with \c alloc.

\var void* (*starpu_disk_ops::open)(void *base, void *pos, size_t size)
Open an existing location of datas, at a specific position \p pos dependent on the backend.

\var void (*starpu_disk_ops::close)(void *base, void *obj, size_t size)
Close, without deleting it, a location of datas \p obj.

\var int (*starpu_disk_ops::read)(void *base, void *obj, void *buf, off_t offset, size_t size)
Read \p size bytes of data from \p obj in \p base, at offset \p offset, and put
into \p buf. Returns the actual number of read bytes.

\var int (*starpu_disk_ops::write)(void *base, void *obj, const void *buf, off_t offset, size_t size)
Write \p size bytes of data to \p obj in \p base, at offset \p offset, from \p buf. Returns 0 on success.

\var int (*starpu_disk_ops::full_read)(void * base, void * obj, void ** ptr, size_t * size)
Read all data from \p obj of \p base, from offset 0. Returns it in an allocated buffer \p ptr, of size \p size

\var int (*starpu_disk_ops::full_write)(void * base, void * obj, void * ptr, size_t size)
Write data in \p ptr to \p obj of \p base, from offset 0, and truncate \p obj to
\p size, so that a \c full_read will get it.

\var void* (*starpu_disk_ops::plug) (void *parameters, size_t size)
Connect a disk memory at location \p parameter with size \p size, and return a
base as void*, which will be passed by StarPU to all other methods.

\var void (*starpu_disk_ops::unplug) (void* base)
Disconnect a disk memory \p base.

\var void* (*starpu_disk_ops::async_read)(void *base, void *obj, void *buf, off_t offset, size_t size)
Asynchronously read \p size bytes of data from \p obj in \p base, at offset \p
offset, and put into \p buf. Returns a void* pointer that StarPU will pass to \c
*_request methods for testing for the completion.

\var void* (*starpu_disk_ops::async_write)(void *base, void *obj, const void *buf, off_t offset, size_t size)
Asynchronously write \p size bytes of data to \p obj in \p base, at offset \p
offset, from \p buf. Returns a void* pointer that StarPU will pass to \c
*_request methods for testing for the completion.

\var void * (*starpu_disk_ops::async_full_read)(void * base, void * obj, void ** ptr, size_t * size)
Read all data from \p obj of \p base, from offset 0. Returns it in an allocated buffer \p ptr, of size \p size

\var void * (*starpu_disk_ops::async_full_write)(void * base, void * obj, void * ptr, size_t size)
Write data in \p ptr to \p obj of \p base, from offset 0, and truncate \p obj to
\p size, so that a \c full_read will get it.

\var void* (*starpu_disk_ops::copy)(void *base_src, void* obj_src, off_t offset_src,  void *base_dst, void* obj_dst, off_t offset_dst, size_t size)
Copy from offset \p offset_src of disk object \p obj_src in \p base_src to
offset \p offset_dst of disk object \p obj_dst in \p base_dst. Returns a void*
pointer that StarPU will pass to \c *_request methods for testing for the
completion.

\var int (*starpu_disk_ops::bandwidth) (unsigned node)
Measure the bandwidth and the latency for the disk \p node and save it. Returns
1 if it could measure it.

\var void (*starpu_disk_ops::wait_request)(void *async_channel)
Wait for completion of request \p async_channel returned by a previous
asynchronous read, write or copy.

\var void (*starpu_disk_ops::test_request)(void *async_channel)
Test for completion of request \p async_channel returned by a previous
asynchronous read, write or copy. Returns 1 on completion, 0 otherwise.

\var void (*starpu_disk_ops::free_request)(void *async_channel)
Free the request allocated by a previous asynchronous read, write or copy.

\fn int starpu_disk_register(struct starpu_disk_ops *func, void *parameter, starpu_ssize_t size)
\ingroup API_Out_Of_Core
Register a disk memory node with a set of functions to manipulate datas. The \c
plug member of \p func will be passed \p parameter, and return a \c base which will be passed to all \p func methods. <br />
SUCCESS: return the disk node. <br />
FAIL: return an error code. <br />
The \p size must be at least 1 MB !
\p size being negative means infinite size.

\fn void *starpu_disk_open(unsigned node, void *pos, size_t size)
\ingroup API_Out_Of_Core
Open an existing file memory in a disk node. \p size: this is a size of your
file. \p pos is specific position dependent on the backend, given to the \c open
method of the disk operations. This returns an opaque object pointer.

\fn void starpu_disk_close(unsigned node, void *obj, size_t size)
\ingroup API_Out_Of_Core
Close an existing data opened with starpu_disk_open.


\var starpu_disk_stdio_ops
\ingroup API_Out_Of_Core
This set uses the stdio library (fwrite, fread...) to read/write on disk. <br />
<strong>Warning: It creates one file per allocation !</strong>  <br />
It doesn't support asynchronous transfers.

\var starpu_disk_unistd_ops
\ingroup API_Out_Of_Core
This set uses the unistd library (write, read...) to read/write on disk. <br />
<strong>Warning: It creates one file per allocation !</strong>  <br />

\var starpu_disk_unistd_o_direct_ops
\ingroup API_Out_Of_Core
This set uses the unistd library (write, read...) to read/write on disk with the O_DIRECT flag. <br />
<strong>Warning: It creates one file per allocation !</strong>  <br />
Only available on Linux systems.

\var starpu_disk_leveldb_ops
\ingroup API_Out_Of_Core
This set uses the leveldb created by Google <br />
Show here: https://code.google.com/p/leveldb/ <br />
It doesn't support asynchronous transfers.

*/
