From fe1d4b56383a85cd4deff3a2a5da8592a696607d Mon Sep 17 00:00:00 2001 From: Gareth Rees Date: Sat, 11 May 2013 19:42:31 +0100 Subject: [PATCH] Update user guide to use the new keyword argument interface. Copied from Perforce Change: 181727 ServerID: perforce.ravenbrook.com --- mps/manual/source/guide/advanced.rst | 29 +++++++++++--------- mps/manual/source/guide/lang.rst | 41 ++++++++++++++++------------ 2 files changed, 40 insertions(+), 30 deletions(-) diff --git a/mps/manual/source/guide/advanced.rst b/mps/manual/source/guide/advanced.rst index f65de503e9e..7ab02a3141d 100644 --- a/mps/manual/source/guide/advanced.rst +++ b/mps/manual/source/guide/advanced.rst @@ -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 diff --git a/mps/manual/source/guide/lang.rst b/mps/manual/source/guide/lang.rst index 3186774685f..edaee742830 100644 --- a/mps/manual/source/guide/lang.rst +++ b/mps/manual/source/guide/lang.rst @@ -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::