/*!
\if sion_internal
\page internal_docs Internal Documentation

BeeGFS
======

Cache domains
-------------

Cache domains in BeeGFS are independent file systems like the global
file system. From SIONlib's point of view they are especially
interesting when used on fast local storage (e.g. burst buffers). In
general these cache domains may span multiple local storage targets.

BeeGFS offers an API which allows the usage of paths in the global
file system which are then transparently mapped to the according path
in the cache mount point. The advantage of this feature is the
automatic handling of the mapping but the disadvantage for SIONlib is
the need for a special open call `deeper_cache_open` which would have
to be added to the current ANSI-C and POSIX open calls.


Flushing byte ranges of cache domains
-------------------------------------

When used on a BeeGFS, SIONlib is able to exploit optimization by
using byte ranges for flushing the cache layer.

The logic would be

- Every SIONlib task uses its local storage to write its data.

- When closing the file each task performs a flush to the byte ranges
  in the file it wrote. Since SIONlib ensures those parts to be
  disjoint this flush operation can be performed concurrently for the
  same file without potential race conditions for writing to the same
  location or even the same file system block.

When the asynchronous flush is available in BeeGFS this would allow
SIONlib for a high performance I/O to local storage and then
non-blocking flush to the global file system.


Internal management of block and fp location
--------------------------------------------

- sion_filedesc structure: (sion_filedesc.h)
  \verbatim
  /* file pointer and temporary data */
   _sion_fileptr *fileptr;         /*!< Pointer to the current sion file */
  /* current position in file */
  sion_int32 rank;                 /*!< Rank of the task writing the file (global rank) */
  sion_int64 currentpos;           /*!< only used if opened  for one rank, reading */
  sion_int32 currentblocknr;       /*!< only used if opened  for one rank, reading */

  /* data for one task  */
  sion_int64 *blocksizes;          /*!< Array of the blocksizes in all chunks of the current task */
  sion_int32 lastchunknr;          /*!< number of last chunk used on this task (0..n) */
  sion_int64 startpos;             /*!< Start position for the current task, start of first chunk (fix for task) */
  \endverbatim

- Handling in API Routines: (old, before continous write)
  sion_fwrite()
  --> sion_ensure_free_space()
      --> _sion_flush_block()
          --> _sion_update_fileposition()
              * adjust currentpos to position of filepointer
              * adjust entry in sion_filedesc->blocksizes
      --> _sion_create_new_block()
          sets currentpos to position of byte 0 of new block
  --> _sion_file_write()
  --> advance currentpos by bytes_written

  * sion_ensure_free_space ensure that there is enough space in current or in the next block, so that
    currentpos stays in the current block

  sion_fread()
  --> _sion_update_fileposition()
      * adjust currentpos to postion of filepointer
      * adjust entry in sion_filedesc->blocksizes
  --> sion_feof()
      --> _sion_update_fileposition()
      --> _sion_file_purge()
      --> _sion_file_set_position()
      * advances to next block if behind last byte of current block
  --> _sion_file_read()
  --> advance currentpos by bytes_read

  * sion_fread return with error if more bytes than available in block are requested

- Handling in API Routines: (new, with continous write)
  sion_fwrite()
  --> sion_write_multi_chunk()
      Loop:
        --> _sion_flush_block()
            --> _sion_update_fileposition()
                * adjust currentpos to postion of filepointer
                * adjust entry in sion_filedesc->blocksizes
        --> _sion_file_write()
        --> advance currentpos by bytes_written
        if new block needed:
        --> _sion_flush_block(sion_filedesc);
        --> _sion_create_new_block(sion_filedesc);

  * buffering mode is currently not adjusted to continous write

  sion_fread()
  --> _sion_update_fileposition()
      * adjust currentpos to postion of filepointer
      * adjust entry in sion_filedesc->blocksizes
  --> sion_feof()
      --> _sion_update_fileposition()
      --> _sion_file_purge()
      --> _sion_file_set_position()
      * advances to next block if behind last byte of current block
  --> _sion_read_multi_chunk()

  --> advance currentpos by bytes_read
      Loop:
        --> _sion_flush_block()
        --> _sion_file_read()
	--> advance currentpos by bytes_read
	if data from next block needed:
        --> _sion_move_to_next_chunk()
	    advances currentblocknr and sets currentpos
	    --> _sion_file_purge()
            --> _sion_file_set_position()
\endif
*/
