Memory management
=================
Memory management is specially important for immutable data
structures. This is mainly due to:
#. In order to preserve the old value, new memory has to be allocated
to store the new data whenever a container is manipulated. Thus,
more allocations are performed *when changing* than with traditional
mutable data structures.
#. In order to support *structural sharing* transparently, some kind
of garbage collection mechanism is required. Passing immutable
data structures around is, internally, just passing references,
thus the system needs to figure out somehow when old values are not
referenced anymore and should be deallocated.
Thus, most containers in this library can be customized via policies_
in order to use different *allocation* and *garbage collection*
strategies.
.. doxygentypedef:: immer::default_memory_policy
.. doxygentypedef:: immer::default_heap_policy
.. doxygentypedef:: immer::default_refcount_policy
.. _policies: https://en.wikipedia.org/wiki/Policy-based_design
.. _memory policy:
Memory policy
-------------
.. doxygenstruct:: immer::memory_policy
:members:
:undoc-members:
.. _gc:
Example: tracing garbage collection
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
It is note worthy that all aspects of a
:cpp:class:`immer::memory_policy` are not completely orthogonal.
Let's say you want to use a `tracing garbage collector`_. Actually, we
already provide :cpp:class:`a heap <immer::gc_heap>` that interfaces
with the `Boehm's conservative garbage collector`_. Chunks of memory
allocated with this heap do not need to be deallocated, instead, after
a certain number of allocations, the heap itself will scan the stack
and all allocated memory to find references to other blocks of memory.
The memory that is not referenced anymore is automatically *freed*.
Thus, no reference counting mechanism is needed, and it makes no sense
to use this heap with anything else than the
:cpp:class:`immer::no_refcount_policy`. Also, a big object can be
separated in parts that contain pointers and parts that do not, which
make scanning references faster. So it makes most sense to use
``prefer_fewer_bigger_objects = false``.
.. note:: There are few considerations to note when using
:cpp:class:`gc_heap` with containers. Please make sure to
read :cpp:class:`its documentation section <immer::gc_heap>`
before using it.
.. literalinclude:: ../example/vector/gc.cpp
:language: c++
:start-after: example/start
:end-before: example/end
.. _boehm's conservative garbage collector: https://github.com/ivmai/bdwgc
.. _tracing garbage collector: https://en.wikipedia.org/wiki/Tracing_garbage_collection
Heaps
-----
A **heap policy** is a `metafunction class`_ that given the sizes of
the objects that we want to allocate, it *returns* a heap that can
allocate objects of those sizes.
.. _metafunction class: http://www.boost.org/doc/libs/1_62_0/libs/mpl/doc/refmanual/metafunction-class.html
A **heap** is a type with a methods ``void* allocate(std::size_t)``
and ``void deallocate(void*)`` that return and release raw memory.
For a canonical model of this concept check the
:cpp:class:`immer::cpp_heap`.
.. note:: Currently, *heaps* can only have **global state**. Having
internal state poses conceptual problems for immutable data
structures: should a `const` method of a container modify
its internal allocator state? Should every immutable
container object have its own internal state, or new objects
made from another one just keep a reference to the allocator
of the parent?
On the other hand, having some **scoped state** does make
sense for some use-cases of immutable data structures. For
example, we might want to support variations of `region
based allocation`_. This interface might evolve to evolve
to support some kind of non-global state to accommodate
these use cases.
.. _region based allocation: https://en.wikipedia.org/wiki/Region-based_memory_management
.. admonition:: Why not use the standard allocator interface?
The standard allocator API was not designed to support different
allocation strategies, but to abstract over the underlying memory
model instead. In C++11 the situation improves, but the new API is
*stateful*, posing various challenges as described in the previous
note. So far it was easier to provide our own allocation
interface. In the future, we will provide adaptors so
standard-compatible allocators can also be used with ``immer``.
Heap policies
~~~~~~~~~~~~~
.. doxygenstruct:: immer::heap_policy
:members:
:undoc-members:
.. doxygenstruct:: immer::free_list_heap_policy
Standard heap
~~~~~~~~~~~~~
.. doxygenstruct:: immer::cpp_heap
:members:
Malloc heap
~~~~~~~~~~~
.. doxygenstruct:: immer::malloc_heap
:members:
Garbage collected heap
~~~~~~~~~~~~~~~~~~~~~~
.. doxygenclass:: immer::gc_heap
Heap adaptors
~~~~~~~~~~~~~
Inspired by `Andrei Alexandrescu's talk on allocators <allocation
vexation>`_ and `Emery Berger's heap layers <heap layers>`_ we provide
allocator adaptors that can be combined using C++ mixins. These
enable building more complex allocator out of simpler strategies, or
provide application specific optimizations on top of general
allocators.
.. _allocation vexation: https://www.youtube.com/watch?v=LIb3L4vKZ7U
.. _heap layers: https://github.com/emeryberger/Heap-Layers
.. doxygenstruct:: immer::with_data
.. doxygenstruct:: immer::free_list_heap
.. doxygenstruct:: immer::thread_local_free_list_heap
.. doxygenstruct:: immer::unsafe_free_list_heap
.. doxygenstruct:: immer::identity_heap
.. doxygenstruct:: immer::debug_size_heap
.. doxygenstruct:: immer::split_heap
.. _rc:
Reference counting
------------------
`Reference counting`_ is the most commonly used garbage collection
strategy for C++. It can be implemented non-intrusively, in a way
orthogonal to the allocation strategy. It is deterministic, playing
well with RAII_.
A `memory policy`_ can provide a reference counting strategy that
containers can use to track their contents.
.. _reference counting: https://en.wikipedia.org/wiki/Reference_counting
.. _raii: https://en.wikipedia.org/wiki/Resource_acquisition_is_initialization
.. doxygenstruct:: immer::refcount_policy
.. doxygenstruct:: immer::unsafe_refcount_policy
.. doxygenstruct:: immer::no_refcount_policy
Transience
----------
In order to support `transients`, it is needed to provide a mechanism
to track the ownership of the data allocated inside the container.
This concept is encapsulated in *transience policies*.
Note that when :ref:`reference counting <rc>` is available, no such mechanism is
needed. However, when :ref:`tracing garbage collection<gc>` is used instead,
a special policy has to be provided. Otherwise, the transient API is
still available, but it will perform poorly, since it won't be able to
mutate any data in place.
.. doxygenstruct:: immer::no_transience_policy
.. doxygenstruct:: immer::gc_transience_policy
