From 2f025ea5d2183ee91f81117330fe7bdcb4159a6e Mon Sep 17 00:00:00 2001 From: Richard Brooksby Date: Tue, 1 Mar 2016 13:36:30 +0000 Subject: [PATCH] Deprecating table roots. Copied from Perforce Change: 189483 ServerID: perforce.ravenbrook.com --- mps/code/mps.h | 7 -- mps/code/mpsi.c | 21 +--- mps/code/tagtest.c | 12 +-- mps/manual/source/topic/deprecated.rst | 124 ++++++++++++++++++++++-- mps/manual/source/topic/root.rst | 129 ++----------------------- 5 files changed, 135 insertions(+), 158 deletions(-) diff --git a/mps/code/mps.h b/mps/code/mps.h index a6495f0dd88..51275c711a7 100644 --- a/mps/code/mps.h +++ b/mps/code/mps.h @@ -675,13 +675,6 @@ extern mps_res_t mps_root_create(mps_root_t *, mps_arena_t, mps_rank_t, extern mps_res_t mps_root_create_table(mps_root_t *, mps_arena_t, mps_rank_t, mps_rm_t, mps_addr_t *, size_t); -extern mps_res_t mps_root_create_table_tagged(mps_root_t *, - mps_arena_t, - mps_rank_t, mps_rm_t, - mps_addr_t *, size_t, - mps_area_scan_t, - mps_word_t, - mps_word_t); extern mps_res_t mps_root_create_table_masked(mps_root_t *, mps_arena_t, mps_rank_t, mps_rm_t, mps_addr_t *, size_t, diff --git a/mps/code/mpsi.c b/mps/code/mpsi.c index cb3c7c894a5..a4778a051c3 100644 --- a/mps/code/mpsi.c +++ b/mps/code/mpsi.c @@ -1383,29 +1383,16 @@ mps_res_t mps_root_create_area_tagged(mps_root_t *mps_root_o, } -mps_res_t mps_root_create_table_tagged(mps_root_t *mps_root_o, - mps_arena_t arena, - mps_rank_t mps_rank, mps_rm_t mps_rm, - mps_addr_t *base, size_t size, - mps_area_scan_t scan_area, - mps_word_t mask, - mps_word_t pattern) -{ - return mps_root_create_area_tagged(mps_root_o, arena, mps_rank, mps_rm, - (void *)base, (void *)(base + size), - scan_area, mask, pattern); -} - - mps_res_t mps_root_create_table_masked(mps_root_t *mps_root_o, mps_arena_t arena, mps_rank_t mps_rank, mps_rm_t mps_rm, mps_addr_t *base, size_t size, mps_word_t mask) { - return mps_root_create_table_tagged(mps_root_o, arena, mps_rank, mps_rm, - base, size, mps_scan_area_tagged, - mask, 0); + return mps_root_create_area_tagged(mps_root_o, arena, mps_rank, mps_rm, + (void *)base, (void *)(base + size), + mps_scan_area_tagged, + mask, 0); } mps_res_t mps_root_create_fmt(mps_root_t *mps_root_o, mps_arena_t arena, diff --git a/mps/code/tagtest.c b/mps/code/tagtest.c index d1f96e00c18..8673390538c 100644 --- a/mps/code/tagtest.c +++ b/mps/code/tagtest.c @@ -169,17 +169,17 @@ static void test(int mode) /* fall through */ case MODE_CONS: /* Scan words tagged "cons" -- everything will live. */ - die(mps_root_create_table_tagged(&root, arena, mps_rank_ambig(), 0, - refs, OBJCOUNT, - mps_scan_area_tagged, TAG_MASK, tag_cons), + die(mps_root_create_area_tagged(&root, arena, mps_rank_ambig(), 0, + (void *)refs, (void *)&refs[OBJCOUNT], + mps_scan_area_tagged, TAG_MASK, tag_cons), "root"); expected = 0; break; case MODE_INVALID: /* Scan words tagged "invalid" -- everything will die. */ - die(mps_root_create_table_tagged(&root, arena, mps_rank_ambig(), 0, - refs, OBJCOUNT, - mps_scan_area_tagged, TAG_MASK, tag_invalid), + die(mps_root_create_area_tagged(&root, arena, mps_rank_ambig(), 0, + (void *)refs, (void *)&refs[OBJCOUNT], + mps_scan_area_tagged, TAG_MASK, tag_invalid), "root"); expected = OBJCOUNT; break; diff --git a/mps/manual/source/topic/deprecated.rst b/mps/manual/source/topic/deprecated.rst index 964fcc2c2d1..592c52ef1f0 100644 --- a/mps/manual/source/topic/deprecated.rst +++ b/mps/manual/source/topic/deprecated.rst @@ -163,24 +163,130 @@ Deprecated in version 1.115 containing references to memory managed by the MPS). The ``s`` argument is ignored. +.. c:function:: mps_res_t mps_root_create_table(mps_root_t *root_o, mps_arena_t arena, mps_rank_t rank, mps_rm_t rm, mps_addr_t *base, size_t count) + + .. deprecated:: + + This function is equivalent to:: + + mps_root_create_area(root_o, arena, rank, mode, + (void *)base, (void *)(base + count), + mps_scan_area, NULL, 0) + + Register a :term:`root` that consists of a vector of + :term:`references`. + + ``root_o`` points to a location that will hold the address of the + new root description. + + ``arena`` is the arena. + + ``rank`` is the :term:`rank` of references in the root. + + ``rm`` is the :term:`root mode`. + + ``base`` points to a vector of references. + + ``count`` is the number of references in the vector. + + Returns :c:macro:`MPS_RES_OK` if the root was registered + successfully, :c:macro:`MPS_RES_MEMORY` if the new root + description could not be allocated, or another :term:`result code` + if there was another error. + + The registered root description persists until it is destroyed by + calling :c:func:`mps_root_destroy`. + + .. _topic-root-type-pun: + + .. warning:: + + The ``base`` argument has type ``mps_addr_t *`` (a typedef for + ``void **``) but the table of references most likely has some + other pointer type, ``my_object *`` say. It is tempting to + write:: + + mps_root_create_table(..., (mps_addr_t *)my_table, ...) + + but this is :term:`type punning`, and its behaviour is not + defined in ANSI/ISO Standard C. (GCC and Clang have a warning + flag ``-Wstrict-aliasing`` which detects some errors of this + form.) + + To ensure well-defined behaviour, the pointer must be + converted via ``void *`` (or via :c:type:`mps_addr_t`, which + is a typedef for ``void *``), like this:: + + mps_addr_t base = my_table; + mps_root_create_table(..., base, ...) + +.. c:function:: mps_res_t mps_root_create_table_tagged(mps_root_t *root_o, mps_arena_t arena, mps_rank_t rank, mps_rm_t rm, mps_addr_t *base, size_t count, mps_area_scan_t scan_area, mps_word_t mask, mps_word_t pattern) + + .. deprecated:: + + This function is equivalent to:: + + mps_root_create_area_tagged(root_o, arena, rank, mode, + (void *)base, (void *)(base + size), + scan_area, mask, pattern) + + Register a :term:`root` that consists of a vector of :term:`tagged + references`. + + ``root_o`` points to a location that will hold the address of the + new root description. + + ``arena`` is the arena. + + ``rank`` is the :term:`rank` of references in the root. + + ``rm`` is the :term:`root mode`. + + ``base`` points to a vector of tagged references. + + ``count`` is the number of tagged references in the vector. + + ``scan_area`` is an tagged area scanning function that will be + used to scan the table, for example :c:func:`mps_scan_area_tagged` + or :c:func:`mps_scan_area_tagged_or_zero`. See + :ref:`topic-scanning-area`. + + ``mask`` is a :term:`bitmask` that is passed to ``scan_area`` to + be applied to the words in the vector to locate the :term:`tag`. + + ``pattern`` is passed to ``scan_area`` to determine whether to + consider a word as a reference. For example, + :c:func:`mps_scan_area_tagged` will not consider any word that is + unequal to this (after masking with ``mask``) to be a reference. + + Returns :c:macro:`MPS_RES_OK` if the root was registered + successfully, :c:macro:`MPS_RES_MEMORY` if the new root + description could not be allocated, or another :term:`result code` + if there was another error. + + The registered root description persists until it is destroyed by + calling :c:func:`mps_root_destroy`. + + .. warning:: + + See the warning for :c:func:`mps_root_create_table` above. .. c:function:: mps_res_t mps_root_create_table_masked(mps_root_t *root_o, mps_arena_t arena, mps_rank_t rank, mps_rm_t rm, mps_addr_t *base, size_t count, mps_word_t mask) .. deprecated:: - Use :c:func:`mps_root_create_table_masked` instead, passing + This function is equivalent to:: + + mps_root_create_area_tagged(root_o, arena, rank, rm, + (void *)base, (void *)(base + size), + mps_scan_area_tagged, + mask, 0) + + Use :c:func:`mps_root_create_area_masked` instead, passing zero for the ``pattern`` argument. Register a :term:`root` that consists of a vector of :term:`tagged references` whose pattern is zero. - - This function is equivalent to:: - - mps_root_create_table_tagged(root_o, arena, rank, rm, - base, size, - mps_scan_area_tagged, - mask, 0) - .. c:type:: mps_res_t (*mps_reg_scan_t)(mps_ss_t ss, mps_thr_t thr, void *p, size_t s) diff --git a/mps/manual/source/topic/root.rst b/mps/manual/source/topic/root.rst index 2b24823f051..8a8ee334a9a 100644 --- a/mps/manual/source/topic/root.rst +++ b/mps/manual/source/topic/root.rst @@ -83,7 +83,7 @@ Roots can be deregistered at any time by calling :c:func:`mps_root_destroy`. All roots registered in an :term:`arena` must be deregistered before the arena is destroyed. -There are five ways to register a root, depending on how you need to +There are four ways to register a root, depending on how you need to scan it for references: #. :c:func:`mps_root_create` if you need a custom root scanning @@ -97,9 +97,6 @@ scan it for references: #. :c:func:`mps_root_create_area` if the root consists of an area of memory; -#. :c:func:`mps_root_create_table` if the root consists of a table of - references; - #. :c:func:`mps_root_create_thread` if the root consists of the :term:`registers` and :term:`control stack` of a thread. See :ref:`topic-root-thread` below. @@ -256,7 +253,7 @@ allowing the MPS to detect whether they have changed. the :term:`root` after it is registered: that is, scanning the root will produce the same set of :term:`references` every time. Furthermore, for roots registered by - :c:func:`mps_root_create_fmt` and :c:func:`mps_root_create_table`, + :c:func:`mps_root_create_fmt` and :c:func:`mps_root_create_area`, the client program will not write to the root at all. .. c:macro:: MPS_RM_PROT @@ -590,7 +587,7 @@ Root interface ``count`` is the number of tagged references in the vector. ``scan_area`` is an tagged area scanning function that will be - used to scan the table, for example :c:func:`mps_scan_area_tagged` + used to scan the area, for example :c:func:`mps_scan_area_tagged` or :c:func:`mps_scan_area_tagged_or_zero`. See :ref:`topic-scanning-area`. @@ -610,106 +607,6 @@ Root interface The registered root description persists until it is destroyed by calling :c:func:`mps_root_destroy`. -.. c:function:: mps_res_t mps_root_create_table(mps_root_t *root_o, mps_arena_t arena, mps_rank_t rank, mps_rm_t rm, mps_addr_t *base, size_t count) - - Register a :term:`root` that consists of a vector of - :term:`references`. - - ``root_o`` points to a location that will hold the address of the - new root description. - - ``arena`` is the arena. - - ``rank`` is the :term:`rank` of references in the root. - - ``rm`` is the :term:`root mode`. - - ``base`` points to a vector of references. - - ``count`` is the number of references in the vector. - - This function is equivalent to:: - - mps_root_create_area(root_o, arena, rank, mode, - (void *)base, (void *)(base + count), - mps_scan_area, NULL, 0) - - Returns :c:macro:`MPS_RES_OK` if the root was registered - successfully, :c:macro:`MPS_RES_MEMORY` if the new root - description could not be allocated, or another :term:`result code` - if there was another error. - - The registered root description persists until it is destroyed by - calling :c:func:`mps_root_destroy`. - - .. _topic-root-type-pun: - - .. warning:: - - The ``base`` argument has type ``mps_addr_t *`` (a typedef for - ``void **``) but the table of references most likely has some - other pointer type, ``my_object *`` say. It is tempting to - write:: - - mps_root_create_table(..., (mps_addr_t *)my_table, ...) - - but this is :term:`type punning`, and its behaviour is not - defined in ANSI/ISO Standard C. (GCC and Clang have a warning - flag ``-Wstrict-aliasing`` which detects some errors of this - form.) - - To ensure well-defined behaviour, the pointer must be - converted via ``void *`` (or via :c:type:`mps_addr_t`, which - is a typedef for ``void *``), like this:: - - mps_addr_t base = my_table; - mps_root_create_table(..., base, ...) - -.. c:function:: mps_res_t mps_root_create_table_tagged(mps_root_t *root_o, mps_arena_t arena, mps_rank_t rank, mps_rm_t rm, mps_addr_t *base, size_t count, mps_area_scan_t scan_area, mps_word_t mask, mps_word_t pattern) - - Register a :term:`root` that consists of a vector of :term:`tagged - references`. - - ``root_o`` points to a location that will hold the address of the - new root description. - - ``arena`` is the arena. - - ``rank`` is the :term:`rank` of references in the root. - - ``rm`` is the :term:`root mode`. - - ``base`` points to a vector of tagged references. - - ``count`` is the number of tagged references in the vector. - - ``scan_area`` is an tagged area scanning function that will be - used to scan the table, for example :c:func:`mps_scan_area_tagged` - or :c:func:`mps_scan_area_tagged_or_zero`. See - :ref:`topic-scanning-area`. - - ``mask`` is a :term:`bitmask` that is passed to ``scan_area`` to - be applied to the words in the vector to locate the :term:`tag`. - - ``pattern`` is passed to ``scan_area`` to determine whether to - consider a word as a reference. For example, - :c:func:`mps_scan_area_tagged` will not consider any word that is - unequal to this (after masking with ``mask``) to be a reference. - - Returns :c:macro:`MPS_RES_OK` if the root was registered - successfully, :c:macro:`MPS_RES_MEMORY` if the new root - description could not be allocated, or another :term:`result code` - if there was another error. - - The registered root description persists until it is destroyed by - calling :c:func:`mps_root_destroy`. - - This function is equivalent to:: - - mps_root_create_area_tagged(root_o, arena, rank, mode, - (void *)base, (void *)(base + size), - scan_area, mask, pattern) - For example:: #define TAG_MASK 0x3 /* bottom two bits */ @@ -724,19 +621,13 @@ Root interface mps_res_t res; mps_root_t root; - mps_addr_t base = symtab; - res = mps_root_create_table_tagged(&root, arena, - mps_rank_exact(), - (mps_rm_t)0, - base, symtab_size * 2, - mps_scan_area_tagged, - (mps_word_t)TAG_MASK, - (mps_word_t)TAG_PATTERN); - if (res != MPS_RES_OK) errror("can't create symtab root"); - - .. warning:: - - See the warning for :c:func:`mps_root_create_table` above. + res = mps_root_create_area_tagged(&root, arena, + mps_rank_exact(), + 0, + (void *)symtab, (void *)&symtab[symtab_size], + mps_scan_area_tagged, + TAG_MASK, TAG_PATTERN); + if (res != MPS_RES_OK) error("can't create symtab root"); .. c:function:: void mps_root_destroy(mps_root_t root)