Github/emacs
2
0
Fork 1
mirror of git://git.sv.gnu.org/emacs.git synced 2026-02-24 13:57:36 +00:00
Code Issues Projects Releases Packages Wiki Activity

Update user guide to use the new keyword argument interface.

Browse source 
Copied from Perforce
 Change: 181727
 ServerID: perforce.ravenbrook.com
This commit is contained in:
Gareth Rees 2013-05-11 19:42:31 +01:00
parent acc7a67349
commit fe1d4b5638
2 changed files with 40 additions and 30 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

29
mps/manual/source/guide/advanced.rst
View file

@ -712,17 +712,21 @@ Finally, we can create the buckets pool and its allocation points::
/* Create an Automatic Weak Linked (AWL) pool to manage the hash table
buckets. */
res = mps_pool_create(&buckets_pool,
arena,
mps_class_awl(),
buckets_fmt,
buckets_find_dependent);
res = mps_pool_create_k(&buckets_pool, arena, mps_class_awl(),
(mps_arg_s[]){{MPS_KEY_FORMAT, .val.format = buckets_fmt},
{MPS_KEY_AWL_FIND_DEPENDENT,
.val.addr_method = buckets_find_dependent},
{MPS_KEY_ARGS_END}});
if (res != MPS_RES_OK) error("Couldn't create buckets pool");
/* Create allocation points for weak and strong buckets. */
res = mps_ap_create(&strong_buckets_ap, buckets_pool, mps_rank_exact());
res = mps_ap_create_k(&strong_buckets_ap, buckets_pool,
(mps_arg_s[]){{MPS_KEY_RANK, .val.rank = mps_rank_exact()},
{MPS_KEY_ARGS_END}});
if (res != MPS_RES_OK) error("Couldn't create strong buckets allocation point");
res = mps_ap_create(&weak_buckets_ap, buckets_pool, mps_rank_weak());
res = mps_ap_create_k(&weak_buckets_ap, buckets_pool,
(mps_arg_s[]){{MPS_KEY_RANK, .val.rank = mps_rank_weak()},
{MPS_KEY_ARGS_END}});
if (res != MPS_RES_OK) error("Couldn't create weak buckets allocation point");
By adding the line::
@ -888,15 +892,14 @@ Second, the leaf objects must be allocated on ``leaf_ap`` instead of
/* Create an Automatic Mostly-Copying Zero-rank (AMCZ) pool to
manage the leaf objects. */
res = mps_pool_create(&leaf_pool,
arena,
mps_class_amcz(),
obj_fmt,
obj_chain);
res = mps_pool_create_k(&leaf_pool, arena, mps_class_amcz(),
(mps_arg_s[]){{MPS_KEY_CHAIN, .val.chain = obj_chain},
{MPS_KEY_FORMAT, .val.format = obj_fmt},
{MPS_KEY_ARGS_END}});
if (res != MPS_RES_OK) error("Couldn't create leaf pool");
/* Create allocation point for leaf objects. */
res = mps_ap_create(&leaf_ap, leaf_pool);
res = mps_ap_create_k(&leaf_ap, leaf_pool, mps_args_none);
if (res != MPS_RES_OK) error("Couldn't create leaf objects allocation point");
Note that the new pool shared a :term:`generation chain` with the old

41
mps/manual/source/guide/lang.rst
View file

@ -155,24 +155,32 @@ rather than having to pass it around everywhere::
static mps_arena_t arena;
Create an arena by calling :c:func:`mps_arena_create`. This function
takes a third argument when creating a virtual memory arena: the size of
the amount of virtual virtual :term:`address space` (*not* :term:`RAM`),
in bytes, that the arena will reserve initially. The MPS will ask for
Create an arena by calling :c:func:`mps_arena_create_k`. This function
takes a :term:`keyword argument` when creating a virtual memory arena:
the size of virtual :term:`address space` (*not* :term:`RAM`), in
bytes, that the arena will reserve initially. The MPS will ask for
more address space if it runs out, but the more times it has to extend
its address space, the less efficient garbage collection will become.
The MPS works best if you reserve an address space that is several times
larger than your peak memory usage.
The MPS works best if you reserve an address space that is several
times larger than your peak memory usage.
.. note::
Functions in the MPS interface take :term:`keyword arguments` for
arguments that are optional, or are only required in some
circumstances. These argument are passed in the form of an array
of structures of type :c:type:`mps_arg_s`. See
:ref:`topic-keyword` for the full details.
Let's reserve 32 megabytes::
mps_res_t res;
res = mps_arena_create(&arena,
mps_arena_class_vm(),
(size_t)(32 * 1024 * 1024));
res = mps_arena_create_k(&arena, mps_arena_class_vm(),
(mps_arg_s[]){{MPS_KEY_ARENA_SIZE, .val.size = 32 * 1024 * 1024},
{MPS_KEY_ARGS_END}});
if (res != MPS_RES_OK) error("Couldn't create arena");
:c:func:`mps_arena_create` is typical of functions in the MPS
:c:func:`mps_arena_create_k` is typical of functions in the MPS
interface in that it stores its result in a location pointed to by an
:term:`out parameter` (here, ``&arena``) and returns a :term:`result
code`, which is :c:macro:`MPS_RES_OK` if the function succeeded, or
@ -762,11 +770,10 @@ Third, the :term:`generation chain`::
And finally the :term:`pool`::
mps_pool_t obj_pool;
res = mps_pool_create(&obj_pool,
arena,
mps_class_amc(),
obj_fmt,
obj_chain);
res = mps_pool_create_k(&obj_pool, arena, mps_class_amc(),
(mps_arg_s[]){{MPS_KEY_CHAIN, .val.chain = obj_chain},
{MPS_KEY_FORMAT, .val.format = obj_fmt},
{MPS_KEY_ARGS_END}});
if (res != MPS_RES_OK) error("Couldn't create obj pool");
@ -1080,13 +1087,13 @@ may abort.
The MPS solves this problem via the fast, nearly lock-free
:ref:`topic-allocation-point-protocol`. This needs an additional
structure, an :term:`allocation point`, to be attached to the pool by
calling :c:func:`mps_ap_create`::
calling :c:func:`mps_ap_create_k`::
static mps_ap_t obj_ap;
/* ... */
res = mps_ap_create(&obj_ap, obj_pool, mps_rank_exact());
res = mps_ap_create_k(&obj_ap, obj_pool, mps_args_none);
if (res != MPS_RES_OK) error("Couldn't create obj allocation point");
And then the constructor can be implemented like this::