README++

README.org

@@ -132,25 +132,37 @@ USAGE:
     fusta [OPTIONS] <FASTA> --mountpoint <mountpoint>
 
 OPTIONS:
+        --cache <cache>              Use either mmap, fseek(2) or just memory-backed cache to extract sequencse from
+                                     FASTA files [default: mmap]  [possible values: file, mmap,
+                                     memory]
+        --cache-all                  Cache all the sequences in RAM for faster access. WARNING as much RAM as the size
+                                     of the FASTA file should be available. Recommended when needing fast access above
+                                     all.
     -D, --daemon                     Launch in the background; will automatically quit when unmounted
     -h, --help                       Prints help information
     -C, --max-cache <max-cache>      Set the maximum amount of memory to use to cache writes (MB) [default: 500]
     -o, --mountpoint <mountpoint>    Specifies the directory to use as mountpoint; it will be created if it does not
                                      exist [default: fusta]
-    -M, --nommap                     Don't use mmap, but rather fseek(2) to extract sequences. Slower, but more memory-
-                                     efficient.
     -E, --non-empty                  Perform the mount even if the destination folder is not empty
     -v                               Sets the level of verbosity
     -V, --version                    Prints version information
 
 ARGS:
     <FASTA>    A (multi)FASTA file containing the sequences to mount
 #+end_src
+
+*** =--cache=
+The cache option is key in adapting FUSTA to your use, and for files of non-trivial size, a correct choice is the difference between a memory overflow and a smooth run:
+- =file= :: in this mode, FUSTA store all the fragments as offsets in their file, and access them through =fseek= accesses. The performances will probably be the worse, but memory consumption will be kept to the minimal.
+- =mmap= :: this mode is extremely similar to the previous one, safe that access will proceed through [[https://en.wikipedia.org/wiki/Mmap][mmmap(2)]] reads, leveraging the caching facilities of the OS -- this is the default mode.
+- =memory= :: in this mode, all fragments will directly be copied to memory. Performances will be at their best, but enough memory should be available to store the entirety of the processed files.
 * Contact
 If you have any question or if you encounter a problem, do not hesitate to [[https://github.com/delehef/fusta/issues][open an issue]].
 * Acknowledgments
 FUSTA is standing on the shoulders of, among others, [[https://github.com/cberner/fuser][fuser]], [[https://github.com/clap-rs/clap][clap]], [[https://github.com/danburkert/memmap-rs][memmap]] and [[https://github.com/knsd/daemonize][daemonize]].
 * Changelog
+** v1.3
+- Can now cache all fragments in memory: increased RAM consumption, but starkly reduced random access time
 ** v1.2.1
 - Bugfixes
 ** v1.2

src/fs.rs

@@ -132,10 +132,10 @@ impl VirtualFile for FragmentFile {
 
 #[derive(Debug)]
 enum Backing {
-    File(SString, usize, usize),   // A start, end pair in a file
-    Buffer(Vec<u8>),               // A chunk of memory
-    PureBuffer(Vec<u8>),           // The same, but guaranteed pure (i.e. no newlines) - can be accessed directly
-    MMap(memmap::Mmap),            // A memmapped chunk of memory
+    File(SString, usize, usize), // A start, end pair in a file
+    Buffer(Vec<u8>),             // A chunk of memory
+    PureBuffer(Vec<u8>), // The same, but guaranteed pure (i.e. no newlines) - can be accessed directly
+    MMap(memmap::Mmap),  // A memmapped chunk of memory
 }
 impl Backing {
     fn len(&self) -> usize {