1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
.. index::
   pair: reservoir; design

.. _design-reservoir:


The low-memory reservoir
========================

.. mps:prefix:: design.mps.reservoir


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

:mps:tag:`intro` The low-memory reservoir provides client support for
implementing handlers for low-memory situations which allocate. The
reservoir is implemented inside the arena as a pool of unallocatable
segments.


Architecture
------------

.. c:type:: struct ReservoirStruct *Reservoir

:mps:tag:`adt` The reservoir interface looks (almost) like an abstract data
type of type :c:type:`Reservoir`. It's not quite abstract because the arena
embeds the structure of the reservoir (of type :c:type:`ReservoirStruct`)
into its own structure, for simplicity of initialization.

:mps:tag:`align` The reservoir is implemented as a pool of available tracts,
along with a size and limit which must always be aligned to the arena
alignment. The size corresponds to the amount of memory currently
maintained in the reservoir. The limit is the maximum amount that it
is desired to maintain.

:mps:tag:`wastage` When the reservoir limit is set by the client, the actual
limit should be increased by one arena grain for every active mutator
buffer.

:mps:tag:`really-empty` When the reservoir limit is set to 0, assume that
the client really doesn't have a need for a reservoir at all. In this
case, the client won't even want an allowance to be made for wastage
in active buffers.


Implementation
--------------

:mps:tag:`interface` The following functions comprise the interface to the
reservoir module:

.. c:function:: Bool ReservoirCheck(Reservoir reservoir)

:mps:tag:`interface.check` :c:func:`ReservoirCheck()` checks the reservoir for
consistency.

.. c:function:: Res ReservoirInit(Reservoir reservoir, Arena arena)

:mps:tag:`interface.init` :c:func:`ReservoirInit()` initializes the reservoir and
its associated pool, setting the size and limit to 0.

.. c:function:: void ReservoirFinish (Reservoir reservoir)

:mps:tag:`interface.finish` :c:func:`ReservoirFinish()` de-initializes the reservoir
and its associated pool:

.. c:function:: Size ReservoirLimit(Reservoir reservoir)

:mps:tag:`interface.limit` :c:func:`ReservoirLimit()` returns the limit of the
reservoir:

.. c:function:: void ReservoirSetLimit(Reservoir reservoir, Size size)

:mps:tag:`interface.set-limit` :c:func:`ReservoirSetLimit()` sets the limit of the
reservoir, making an allowance for wastage in mutator buffers:

.. c:function:: Size ReservoirAvailable(Reservoir reservoir)

:mps:tag:`interface.available` :c:func:`ReservoirAvailable()` returns the available
size of the reservoir:

.. c:function:: Res ReservoirEnsureFull(Reservoir reservoir)

:mps:tag:`interface.ensure-full` :c:func:`ReservoirEnsureFull()` attempts to fill
the reservoir with memory from the arena, until it is full:

.. c:function:: void ReservoirDeposit(Reservoir reservoir, Addr base, Size size)

:mps:tag:`interface.deposit` :c:func:`ReservoirDeposit()` attempts to fill the
reservoir with memory in the supplied range, until it is full. This is
called by the arena from :c:func:`ArenaFree()` if the reservoir is not known
to be full. Any memory which is not added to the reservoir (because
the reservoir is full) is freed via the arena class's free method.

.. c:function:: Res ReservoirWithdraw(Addr *baseReturn, Tract *baseTractReturn, Reservoir reservoir, Size size, Pool pool)

:mps:tag:`interface.withdraw` :c:func:`ReservoirWithdraw()` attempts to allocate
memory of the specified size to the specified pool to the reservoir.
If no suitable memory can be found it returns ``ResMEMORY``.

:mps:tag:`interface.withdraw.align` Currently, :c:func:`ReservoirWithdraw()` can
only withdraw a single arena grain at a time. This is because the
reservoir doesn't attempt to coalesce adjacent memory blocks. This
deficiency should be fixed in the future.

:mps:tag:`pool` The memory managed by the reservoir is owned by the
reservoir pool. This memory is never sub-allocated. Each tract
belonging to the pool is linked onto a list. The head of the list is
in the :c:type:`Reservoir` object. Links are stored in the ``TractP`` fields
of each tract object.