mmap_allocator - A STL allocator that mmaps files
-------------------------------------------------

Introduction
------------

When reading large files (>100MB) into memory, read() calls are usually 
not very space and time efficient, since the whole data is copiied at
least once. Furthermore, when using STL containers (like a vector for
example), data is copiied another time unless you specify the location
of the vector content as parameter to read(). 

It would be nice to tell the vector a filename and have the vector mmap
the file directly. This not only avoids the read() copiing (and the
STL vector copiing) but also allows different processes that read the
same file to see the same physical memory. Fortunately STL foresees
an interface to do exactly this.

Put short, if you need to handle big files that contain unstructured data 
(like doubles or even text files), mmap_allocator is worth a try. It was
written as part of a consulting project I did for a large Austrian bank.

License
-------

This code is (c) Johannes Thoma 2012 and is LGPL. Please write me an email to 
johannes.thoma@gmx.at if you find this useful, or if you find bugs or want 
to extend the library.

How it works
------------

Many STL container classes accept allocators as part of their instantiation
and construction. The default allocator simply does a malloc on allocate and
a free on deallocate. By subclassing the default allocator and replacing the
allocate and deallocate methods with code that memory maps a file and return
a pointer to the mmaped area, we can create STL containers that use memory
mapped regions directly.

Usage
-----

To build this, do a 

        make

followed by a 

        make install

When compiling, include the mmappable_vector.h file and link with 
the -lmmap_allocator library.

Example
-------

Suppose you have a file with 1024 ints. Then:

	mmappable_vector<int> my_vector;

declares a vector that uses mmap_allocator to mmap the file. By calling:

	my_vector.mmap_file("testfile", READ_ONLY, 0, 1024);

the mmappable_vector class will call allocate of the mmap_allocator
class, which in turn will mmap the file and set the content of the 
vector to the mmapped area. The file's content can then be accessed 
the usual way (my_vector[i]). 

Use 

	my_vector.munmap_file();

to drop the mapping (it may remain in an internal cache, however). After
this call all accesses of mmappable_vector elements are invalid, same
goes for the iterators.

Do not forget to:

	using namespace mmap_allocator_namespace;

and include:

	#include "mmappable_vector.h"

but you probably know that yourself ;)

Please see the test_allocator.cpp file for more examples 
(I used Testdriven development for this project and can highly recommend
this development model).

Mode
----

As part of the construction of the mmap_allocator object a mode field can be 
specified. It does the following:

* DEFAULT_STL_ALLOCATOR: Default STL allocator (malloc based). Reason 
	is to have containers that do both and are compatible
* READ_ONLY: Readonly modus. Segfaults when vector content is written to.
* READ_WRITE_PRIVATE: Read/write access, writes are not propagated to disk.
* READ_WRITE_SHARED: Read/write access, writes are propagated to disk 
	(file is modified)

The offset parameter must be page aligned (PAGE_SIZE, usually 4K or 8K), 
else mmap will return an error.

Mmap file pool
--------------

Beginning with 0.3, mmap allocator uses a pool of mmaped files. If you
map the same file with the same access mode again it gets the same
(virtual and physical) memory assigned as it was mapped previously.
We needed this because our program (that uses mmap_allocator) mmaps
a file in many small chunks (10K junks) which eventually lead to a
Out of filedescriptors error (when mapping a 100Meg file in 10K junks).

Following flags can be passed (by |'ing them together) to the mmap_file
method:

* MAP_WHOLE_FILE: Set this flag when you know that you need
the whole (or most parts of the) file later and only want to 
request a part of it now.

* ALLOW_REMAP: Set this flag if you are allocating a vector
from a mmapped file and you know that you do not need previous
mappings any more. Normally this is used when the file size 
changes (in particular when it grows). Be aware, however that
this could invalidate all allocations for that file that have
been made before.

* BYPASS_FILE_POOL: Set this flag if you want a per-vector
private mapping. This is useful in conjunction with READ_WRITE_PRIVATE
mappings.

Mmappable vector class
----------------------

Beginning with version 0.4, there is a special std::vector subclass 
for use with mmapped vectors. This was necessary because there is
no standard way to set the size of an STL vector without initializing
the content (which is not wanted since the content is coming from the
mmapped file). From now on, please use the mmapped_vector class for
using mmap_allocator.

The old method by using the mmap_allocators constructor to set the
parameters for file mapping is still supported, however deprecated.

READ_WRITE caveats
------------------

Unlike reading from a file, a mmappable_vector that is mapped via
the mmap file pool contains all changes already made to the content
before. Suppose if you have:

    mmappable_vector<int> p;
    if (method == MMAP) {
	p.mmap_file("testfile", READ_WRITE_PRIVATE, 0, filesize("testfile")); 
    } else {
        readFromFileIntoVector(p, "testfile", READ_WRITE_PRIVATE, 0, filesize("testfile")
    }

and then do something like:

    for (it = p.begin();it != p.end();it++) {
       *it += 1;
    }

This will do not what you would expect at first glance when being called
twice. When the vector maps the file for the second time, it will map it
from the file pool and hence already have the values increased by one.

To avoid this, use the bypass_file_pool flag which will cause the file 
being mmapped another time with different virtual memory mappings.

Exceptions
----------

There is a custom exception class mmap_allocator_exception which is
used at various places, for example when the file to be mapped is 
not found. Use the e.message() method to find out what happened.

Conversion function templates
-----------------------------

To convert between a STL vector and a mmappable vector, use the
to_std_vector(mappable_vector) and to_mmappable_vector(std_vector)
function templates. However, try to avoid this because this will
copy the whole vector contents.

Verbosity
---------

To debug the allocator, there are two ways: 

* call set_verbosity() with a positive value at runtime.
* define MMAP_ALLOCATOR_DEBUG as a positive value at compile time.

The latter is done by make test.

Version history
---------------

* 0.1.0, first release.
* 0.2.0, some interface changes.
* 0.3.0, mmaped file pool.
* 0.3.1, do not remap files when area fits in already mapped file.
* 0.3.2, never use MAP_FIXED.
* 0.3.3, bugfix in computing pointers.
* 0.4.0, mmapped_vector class.
* 0.5.0, cleaner interface, illegal offset bugfix.
* 0.5.1, bypass_file_pool flag.
* 0.5.2, changed bool parameters to flags argument.
* 0.5.3, set_verbosity() to toggle debug output.
* 0.6.0, to_stl_vector function template.
* 0.6.1, flags bugfix.
* 0.7.0, moved mmappable_vector to separate header.
* 0.8.0, to_mmappable_vector conversion function.
* 0.8.1, exception now knows what() method.
* 0.9.0, more standard conformant exception handling.
* 0.9.1, fixed a permission bug in MMAP_READWRITE_PRIVATE.
* 0.10.0, KEEP_FOREVER flag: never close any file.
* 0.10.1, fixed bug with allocating/deallocating 0 bytes.

Author
------

This was written by Johannes Thoma <johannes.thoma@gmx.at>
Thanks to Piotr Nycz from stackoverflow for contributing 
the constructor function template in mmappable_vector.h