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
.. Sources:

    `<https://info.ravenbrook.com/project/mps/master/manual/wiki/pool_classes.html>`_

.. index::
   single: AMCZ
   single: pool class; AMCZ

.. _pool-amcz:

AMCZ (Automatic Mostly-Copying Zero-rank)
=========================================

**AMCZ** is a general-purpose :term:`automatically managed <automatic
memory management>` :term:`pool class` for :term:`leaf objects`
("zero-rank" objects that contain no references).

It is otherwise identical to :ref:`pool-amc`.

AMCZ is intended for "simple" objects like numbers, characters, and
strings. Segregating these objects into one or more AMCZ pools avoids
the cost of scanning them that would be incurred if they were
interleaved in a pool with objects containing references. It may also
simplify the scanning of the objects that are left behind.

See :ref:`guide-advanced-segregation` for an example.


.. index::
   single: AMCZ; properties

AMCZ properties
---------------

AMCZ is identical to :ref:`pool-amc`, except that:

* Blocks may not contain :term:`references` to blocks in automatically
  managed pools.

* Blocks are not :term:`scanned <scan>`. A consequence of this is that
  the pool's :term:`object format` need not provide a :term:`scan
  method`.

* Blocks are not protected by :term:`barriers (1)`.


.. index::
   single: AMCZ; interface

AMCZ interface
--------------

::

   #include "mpscamc.h"

.. c:function:: mps_class_t mps_class_amcz(void)

    Return the :term:`pool class` for an AMCZ (Automatic
    Mostly-Copying Zero-rank) :term:`pool`.

    When creating an AMCZ pool, :c:func:`mps_pool_create_k` requires
    two :term:`keyword arguments`:

    * :c:macro:`MPS_KEY_FORMAT` (type :c:type:`mps_fmt_t`) specifies
      the :term:`object format` for the objects allocated in the pool.
      The format must provide a :term:`skip method`, a :term:`forward
      method`, an :term:`is-forwarded method` and a :term:`padding
      method`.

    * :c:macro:`MPS_KEY_CHAIN` (type :c:type:`mps_chain_t`) specifies
      the :term:`generation chain` for the pool.

    For example::

        MPS_ARGS_BEGIN(args) {
            MPS_ARGS_ADD(args, MPS_KEY_CHAIN, chain);
            MPS_ARGS_ADD(args, MPS_KEY_FORMAT, fmt);
            MPS_ARGS_DONE(args);
            res = mps_pool_create_k(&pool, arena, mps_class_amcz(), args);
        } MPS_ARGS_END(args);

    .. deprecated:: starting with version 1.112.

        When using :c:func:`mps_pool_create`, pass the format and
        chain like this::

          mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena, 
                                    mps_class_t mps_class_amcz(),
                                    mps_fmt_t fmt,
                                    mps_chain_t chain)