24. Deprecated interfaces

This chapter documents the public symbols in the MPS interface that are now deprecated. These symbols may be removed in any future release (see Support policy for details). If you are using one of these symbols, then you should update your code to use the supported interface.

Note

If you are relying on a deprecated interface, and there is no supported alternative, please contact us. It makes a difference if we know that someone is using a feature.

24.1. Deprecated in version 1.115

typedef mps_pool_class_t mps_class_t

Deprecated

The former name for mps_pool_class_t, chosen when pools were the only objects in the MPS that belonged to classes.

size_t mps_mv_free_size(mps_pool_t pool)

Deprecated

Use the generic function mps_pool_free_size() instead.

Return the total amount of free space in an MV pool.

pool is the MV pool.

Returns the total free space in the pool, in bytes (1).

size_t mps_mv_size(mps_pool_t pool)

Deprecated

Use the generic function mps_pool_total_size() instead.

Return the total size of an MV pool.

pool is the MV pool.

Returns the total size of the pool, in bytes (1). This is the sum of allocated space and free space.

size_t mps_mvff_free_size(mps_pool_t pool)

Deprecated

Use the generic function mps_pool_free_size() instead.

Return the total amount of free space in an MVFF pool.

pool is the MVFF pool.

Returns the total free space in the pool, in bytes (1).

size_t mps_mvff_size(mps_pool_t pool)

Deprecated

Use the generic function mps_pool_total_size() instead.

Return the total size of an MVFF pool.

pool is the MVFF pool.

Returns the total size of the pool, in bytes (1). This is the sum of allocated space and free space.

size_t mps_mvt_free_size(mps_pool_t pool)

Deprecated

Use the generic function mps_pool_free_size() instead.

Return the total amount of free space in an MVT pool.

pool is the MVT pool.

Returns the total free space in the pool, in bytes (1).

size_t mps_mvt_size(mps_pool_t pool)

Deprecated

Use the generic function mps_pool_total_size() instead.

Return the total size of an MVT pool.

pool is the MVT pool.

Returns the total size of the pool, in bytes (1). This is the sum of allocated space and free space.

mps_res_t mps_root_create_reg(mps_root_t *root_o, mps_arena_t arena, mps_rank_t rank, mps_rm_t rm, mps_thr_t thr, mps_reg_scan_t reg_scan, void *p, size_t s)

Deprecated

Use mps_root_create_thread() instead.

Register a root that consists of the references fixed in a thread’s registers and stack by a scanning function.

root_o points to a location that will hold the address of the new root description.

arena is the arena.

rank is the rank of references in the root.

rm is the root mode.

thr is the thread.

reg_scan is a scanning function. See mps_reg_scan_t.

p and s are arguments that will be passed to reg_scan each time it is called. This is intended to make it easy to pass, for example, an array and its size as parameters.

Returns MPS_RES_OK if the root was registered successfully, MPS_RES_MEMORY if the new root description could not be allocated, or another result code if there was another error.

The registered root description persists until it is destroyed by calling mps_root_destroy().

Note

It is not supported for client programs to pass their own scanning functions to this function. The built-in MPS function mps_stack_scan_ambig() must be used. In this case the p argument must be a pointer to the cold end of the thread’s stack (or the part of the stack containing references to memory managed by the MPS). The s argument is ignored.

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,
                     base, base + count,
                     mps_scan_area, NULL, 0)

Register a root that consists of a vector of references.

root_o points to a location that will hold the address of the new root description.

arena is the arena.

rank is the rank of references in the root.

rm is the root mode.

base points to a vector of references.

count is the number of references in the vector.

Returns MPS_RES_OK if the root was registered successfully, MPS_RES_MEMORY if the new root description could not be allocated, or another result code if there was another error.

The registered root description persists until it is destroyed by calling mps_root_destroy().

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 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 mps_addr_t, which is a typedef for void*), like this:

mps_addr_t base = my_table;
mps_root_create_table(..., base, ...)

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,
                            base, base + size,
                            scan_area, mask, pattern)

Register a root that consists of a vector of 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 rank of references in the root.

rm is the 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 mps_scan_area_tagged() or mps_scan_area_tagged_or_zero(). See Area scanners.

mask is a bitmask that is passed to scan_area to be applied to the words in the vector to locate the tag.

pattern is passed to scan_area to determine whether to consider a word as a reference. For example, mps_scan_area_tagged() will not consider any word that is unequal to this (after masking with mask) to be a reference.

Returns MPS_RES_OK if the root was registered successfully, MPS_RES_MEMORY if the new root description could not be allocated, or another result code if there was another error.

The registered root description persists until it is destroyed by calling mps_root_destroy().

Warning

See the warning for mps_root_create_table() above.

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

This function is equivalent to:

mps_root_create_area_tagged(root_o, arena, rank, rm,
                            base, base + size,
                            mps_scan_area_tagged,
                            mask, 0)

Use mps_root_create_area_masked() instead, passing zero for the pattern argument.

Register a root that consists of a vector of tagged references whose pattern is zero.

mps_res_t (*mps_reg_scan_t)(mps_ss_t ss, mps_thr_t thr, void *p, size_t s)

Deprecated

Use mps_root_create_thread() instead.

The type of a root scanning function for roots created with mps_root_create_reg().

ss is the scan state. It must be passed to MPS_SCAN_BEGIN() and MPS_SCAN_END() to delimit a sequence of fix operations, and to the functions MPS_FIX1() and MPS_FIX2() when fixing a reference.

thr is the thread.

p and s are the corresponding values that were passed to mps_root_create_reg().

Returns a result code. If a fix function returns a value other than MPS_RES_OK, the scan method must return that value, and may return without fixing any further references. Generally, it is better if it returns as soon as possible. If the scanning is completed successfully, the function should return MPS_RES_OK.

A root scan method is called whenever the MPS needs to scan the root. It must then indicate references within the root by calling MPS_FIX1() and MPS_FIX2().

See also

Scanning.

Note

Client programs are not expected to write scanning functions of this type. The built-in MPS function mps_stack_scan_ambig() must be used.

mps_reg_scan_t mps_stack_scan_ambig()

Deprecated

Use mps_root_create_thread() instead, passing sizeof(mps_word_t) - 1 for the mask argument, and 0 for the pattern argument.

A root scanning function for ambiguous scanning of threads, suitable for passing to mps_root_create_reg().

It scans all integer registers and everything on the stack of the thread given, and can therefore only be used with ambiguous roots. It scans locations that are more recently added to the stack than the location that was passed in the p argument to mps_root_create_reg().

References are assumed to be represented as machine words, and are required to be word-aligned; unaligned values are ignored.

24.2. Deprecated in version 1.113

MPS_ARGS_DONE(args)

Deprecated

Formerly this was used to finalize a list of keyword arguments before passing it to a function. It is no longer needed.

24.3. Deprecated in version 1.112

mps_res_t mps_arena_create(mps_arena_t *arena_o, mps_arena_class_t arena_class, ...)

Deprecated

Use mps_arena_create_k() instead.

An alternative to mps_arena_create_k() that takes its extra arguments using the standard C variable argument list mechanism.

When creating an arena of class mps_arena_class_cl(), pass the values for the keyword arguments MPS_KEY_ARENA_SIZE and MPS_KEY_ARENA_CL_BASE like this:

mps_res_t mps_arena_create(mps_arena_t *arena_o,
                           mps_arena_class_t mps_arena_class_cl(),
                           size_t arena_size,
                           mps_addr_t cl_base)

When creating an arena of class mps_arena_class_vm(), pass the value for the keyword argument MPS_KEY_ARENA_SIZE like this:

mps_res_t mps_arena_create(mps_arena_t *arena_o,
                           mps_arena_class_t mps_arena_class_vm(),
                           size_t arena_size)

mps_res_t mps_arena_create_v(mps_arena_t *arena_o, mps_arena_class_t arena_class, va_list args)

Deprecated

Use mps_arena_create_k() instead.

An alternative to mps_arena_create_k() that takes its extra arguments using the standard C va_list mechanism. See mps_arena_create() for details of which arguments to pass for the different arena classes.

mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena, mps_pool_class_t pool_class, ...)

Deprecated

Use mps_pool_create_k() instead.

An alternative to mps_pool_create_k() that takes its extra arguments using the standard C variable argument list mechanism.

When creating a pool of class mps_class_amc() or mps_class_amcz(), pass the values for the keyword arguments MPS_KEY_FORMAT and MPS_KEY_CHAIN like this:

mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena,
                          mps_pool_class_t mps_class_amc(),
                          mps_fmt_t format,
                          mps_chain_t chain)

When creating a pool of class mps_class_ams(), pass the values for the keyword arguments MPS_KEY_FORMAT, MPS_KEY_CHAIN and ambiguous flag MPS_KEY_AMS_SUPPORT_AMBIGUOUS like this:

mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena,
                          mps_pool_class_t mps_class_ams(),
                          mps_fmt_t format,
                          mps_chain_t chain,
                          mps_bool_t ams_support_ambiguous)

When creating a pool of class mps_class_ams_debug(), pass the values for the keyword arguments MPS_KEY_POOL_DEBUG_OPTIONS, MPS_KEY_FORMAT, MPS_KEY_CHAIN and MPS_KEY_AMS_SUPPORT_AMBIGUOUS like this:

mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena,
                          mps_pool_class_t mps_class_ams_debug(),
                          mps_pool_debug_option_s *pool_debug_options,
                          mps_fmt_t format,
                          mps_chain_t chain,
                          mps_bool_t ams_support_ambiguous)

When creating a pool of class mps_class_awl(), pass the values for the keyword arguments MPS_KEY_FORMAT and MPS_KEY_AWL_FIND_DEPENDENT like this:

mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena,
                          mps_pool_class_t mps_class_awl(),
                          mps_fmt_t format,
                          mps_awl_find_dependent_t awl_find_dependent)

When creating a pool of class mps_class_lo(), pass the value for the keyword argument MPS_KEY_FORMAT like this:

mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena,
                          mps_pool_class_t mps_class_lo(),
                          mps_fmt_t format)

When creating a pool of class mps_class_mfs(), pass the values for the keyword arguments MPS_KEY_EXTEND_BY and MPS_KEY_MFS_UNIT_SIZE like this:

mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena,
                          mps_pool_class_t mps_class_mfs(),
                          size_t extend_by,
                          size_t unit_size)

When creating a pool of class mps_class_mv(), pass the values for the keyword arguments MPS_KEY_EXTEND_BY, MPS_KEY_MEAN_SIZE, and MPS_KEY_MAX_SIZE like this:

mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena,
                          mps_pool_class_t mps_class_mv(),
                          size_t extend_by,
                          size_t mean_size,
                          size_t max_size)

When creating a pool of class mps_class_mv_debug(), pass the values for the keyword arguments MPS_KEY_POOL_DEBUG_OPTIONS, MPS_KEY_EXTEND_BY, MPS_KEY_MEAN_SIZE and MPS_KEY_MAX_SIZE like this:

mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena,
                          mps_pool_class_t mps_class_mv_debug(),
                          mps_pool_debug_option_s *pool_debug_options,
                          size_t extend_by,
                          size_t mean_size,
                          size_t max_size)

When creating a pool of class mps_class_mvff(), pass the values for the keyword arguments MPS_KEY_EXTEND_BY, MPS_KEY_MEAN_SIZE, MPS_KEY_ALIGN, MPS_KEY_MVFF_SLOT_HIGH, MPS_KEY_MVFF_ARENA_HIGH and MPS_KEY_MVFF_FIRST_FIT like this:

mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena,
                          mps_pool_class_t mps_class_mvff(),
                          size_t extend_by,
                          size_t mean_size,
                          mps_align_t align,
                          mps_bool_t mvff_slot_high,
                          mps_bool_t mvff_arena_high,
                          mps_bool_t mvff_first_fit)

When creating a pool of class mps_class_mvff_debug(), pass the values for the keyword arguments MPS_KEY_POOL_DEBUG_OPTIONS, MPS_KEY_EXTEND_BY, MPS_KEY_MEAN_SIZE, MPS_KEY_ALIGN, MPS_KEY_MVFF_SLOT_HIGH, MPS_KEY_MVFF_ARENA_HIGH, and MPS_KEY_MVFF_FIRST_FIT like this:

mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena,
                          mps_pool_class_t mps_class_mvff_debug(),
                          mps_pool_debug_option_s *pool_debug_options,
                          size_t extend_by,
                          size_t mean_size,
                          mps_align_t align,
                          mps_bool_t mvff_slot_high,
                          mps_bool_t mvff_arena_high,
                          mps_bool_t mvff_first_fit)

When creating a pool of class mps_class_mvt(), pass the values for the keyword arguments MPS_KEY_MIN_SIZE, MPS_KEY_MEAN_SIZE, MPS_KEY_MAX_SIZE, MPS_KEY_MVT_RESERVE_DEPTH and MPS_KEY_MVT_FRAG_LIMIT like this:

mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena,
                          mps_pool_class_t mps_class_mvt(),
                          size_t min_size,
                          size_t mean_size,
                          size_t max_size,
                          mps_word_t mvt_reserve_depth,
                          mps_word_t mvt_frag_limit)

Note

The mvt_frag_limit is a percentage from 0 to 100 inclusive when passed to mps_pool_create(), not a double from 0.0 to 1.0 as in mps_pool_create_k().

When creating a pool of class mps_class_snc(), pass the value for the keyword argument MPS_KEY_FORMAT like this:

mps_res_t mps_pool_create(mps_pool_t *pool_o, mps_arena_t arena,
                          mps_pool_class_t mps_class_snc(),
                          mps_fmt_t format)

mps_res_t mps_pool_create_v(mps_pool_t *pool_o, mps_arena_t arena, mps_pool_class_t pool_class, va_list args)

Deprecated

Use mps_pool_create_k() instead.

An alternative to mps_pool_create_k() that takes its extra arguments using the standard C va_list mechanism. See mps_pool_create() for details of which arguments to pass for the different pool classes.

mps_res_t mps_ap_create(mps_ap_t *ap_o, mps_pool_t pool, ...)

Deprecated

Use mps_ap_create_k() instead.

An alternative to mps_ap_create_k() that takes its extra arguments using the standard C variable argument list mechanism.

When creating an allocation point on a pool of class mps_class_ams(), mps_class_ams_debug(), mps_class_awl() or mps_class_snc(), pass the keyword argument MPS_KEY_RANK like this:

mps_res_t mps_ap_create(mps_ap_t *ap_o, mps_pool_t pool,
                        mps_rank_t rank)

mps_res_t mps_ap_create_v(mps_ap_t *ap_o, mps_pool_t pool, va_list args)

Deprecated

Use mps_ap_create_k() instead.

An alternative to mps_ap_create_k() that takes its extra arguments using the standard C va_list mechanism. See mps_ap_create() for details of which arguments to pass for the different pool classes.

mps_fmt_A_s

Deprecated

Use mps_fmt_create_k() instead.

The type of the structure used to create an object format of variant A.

typedef struct mps_fmt_A_s {
    mps_align_t     align;
    mps_fmt_scan_t  scan;
    mps_fmt_skip_t  skip;
    mps_fmt_copy_t  copy;
    mps_fmt_fwd_t   fwd;
    mps_fmt_isfwd_t isfwd;
    mps_fmt_pad_t   pad;
} mps_fmt_A_s;

The fields of this structure correspond to the keyword arguments to mps_fmt_create_k(), except for copy, which is not used. In older versions of the MPS this was a copy method that copied objects belonging to this format.

mps_res_t mps_fmt_create_A(mps_fmt_t *fmt_o, mps_arena_t arena, mps_fmt_A_s *fmt_A)

Deprecated

Use mps_fmt_create_k() instead.

Create an object format based on a description of an object format of variant A.

mps_fmt_B_s

Deprecated

Use mps_fmt_create_k() instead.

The type of the structure used to create an object format of variant B.

typedef struct mps_fmt_B_s {
    mps_align_t     align;
    mps_fmt_scan_t  scan;
    mps_fmt_skip_t  skip;
    mps_fmt_copy_t  copy;
    mps_fmt_fwd_t   fwd;
    mps_fmt_isfwd_t isfwd;
    mps_fmt_pad_t   pad;
    mps_fmt_class_t mps_class;
} mps_fmt_B_s;

Variant B is the same as variant A except for the addition of the mps_class method. See mps_fmt_A_s.

mps_res_t mps_fmt_create_B(mps_fmt_t *fmt_o, mps_arena_t arena, mps_fmt_B_s *fmt_B)

Deprecated

Use mps_fmt_create_k() instead.

Create an object format based on a description of an object format of variant B.

mps_fmt_auto_header_s

Deprecated

Use mps_fmt_create_k() instead.

The type of the structure used to create an object format of variant auto-header.

typedef struct mps_fmt_auto_header_s {
    mps_align_t     align;
    mps_fmt_scan_t  scan;
    mps_fmt_skip_t  skip;
    mps_fmt_fwd_t   fwd;
    mps_fmt_isfwd_t isfwd;
    mps_fmt_pad_t   pad;
    size_t          mps_headerSize;
} mps_fmt_auto_header_s;

Variant auto-header is the same as variant A except for the removal of the unused copy method, and the addition of the mps_headerSize field. See mps_fmt_A_s.

mps_res_t mps_fmt_create_auto_header(mps_fmt_t *fmt_o, mps_arena_t arena, mps_fmt_auto_header_s *fmt_ah)

Deprecated

Use mps_fmt_create_k() instead.

Create an object format based on a description of an object format of variant auto-header.

mps_fmt_fixed_s

Deprecated

Use mps_fmt_create_k() instead.

The type of the structure used to create an object format of variant fixed.

typedef struct mps_fmt_fixed_s {
    mps_align_t     align;
    mps_fmt_scan_t  scan;
    mps_fmt_fwd_t   fwd;
    mps_fmt_isfwd_t isfwd;
    mps_fmt_pad_t   pad;
} mps_fmt_fixed_s;

Variant fixed is the same as variant A except for the removal of the unused copy method, and the lack of a skip method (this is not needed because the objects are fixed in size). See mps_fmt_A_s.

mps_res_t mps_fmt_create_fixed(mps_fmt_t *fmt_o, mps_arena_t arena, mps_fmt_fixed_s *fmt_fixed)

Deprecated

Use mps_fmt_create_k() instead.

Create an object format based on a description of an object format of variant fixed.

24.4. Deprecated in version 1.111

mps_res_t mps_fix(mps_ss_t ss, mps_addr_t *ref_io)

Deprecated

Use MPS_FIX1() and MPS_FIX2() instead.

Fix a reference.

This is a function equivalent to:

MPS_SCAN_BEGIN(ss);
res = MPS_FIX12(ss, ref_io);
MPS_SCAN_END(ss);
return res;

Because scanning is an operation on the critical path, we recommend that you use MPS_FIX12() (or MPS_FIX1() and MPS_FIX2()) to ensure that the “stage 1 fix” is inlined.

Note

If you call this between MPS_SCAN_BEGIN() and MPS_SCAN_END(), you must use MPS_FIX_CALL() to ensure that the scan state is passed correctly.

mps_word_t mps_telemetry_control(mps_word_t reset_mask, mps_word_t flip_mask)

Deprecated

Use mps_telemetry_get(), mps_telemetry_reset(), and mps_telemetry_set() instead.

Update and return the telemetry filter.

reset_mask is a bitmask indicating the bits in the telemetry filter that should be reset.

flip_mask is a bitmask indicating the bits in the telemetry filter whose value should be flipped after the resetting.

Returns the previous value of the telemetry filter, prior to the reset and the flip.

The parameters reset_mask and flip_mask allow the specification of any binary operation on the filter control. For typical operations, the parameters should be set as follows:

Operation	reset_mask	flip_mask
set(M)	M	M
reset(M)	M	0
flip(M)	0	M
read()	0	0

void mps_tramp(void **r_o, mps_tramp_t f, void *p, size_t s)

Deprecated

The MPS trampoline is no longer required on any operating system supported by the MPS.

Call a function via the MPS trampoline.

r_o points to a location that will store the result of calling f.

f is the function to call.

p and s are arguments that will be passed to f each time it is called. This is intended to make it easy to pass, for example, an array and its size as parameters.

The MPS relies on barriers (1) to protect memory that is in an inconsistent state. On some operating systems, barrier hits generate exceptions that have to be caught by a handler that is on the stack. On these operating systems, any code that uses memory managed by the MPS must be called from inside such an exception handler, that is, inside a call to mps_tramp().

If you have multiple threads that run code that uses memory managed by the MPS, each thread must execute such code inside a call to mps_tramp().

void *(*mps_tramp_t)(void *p, size_t s)

Deprecated

The MPS trampoline is no longer required on any operating system supported by the MPS.

The type of a function called by mps_tramp().

p and s are the corresponding arguments that were passed to mps_tramp().

void mps_arena_expose(mps_arena_t arena)

Deprecated

If you need access to protected memory for debugging, contact us.

Ensure that the MPS is not protecting any page in the arena with a read barrier or write barrier.

arena is the arena to expose.

This is expected to only be useful for debugging. The arena is left in the clamped state.

Since barriers are used during a collection, calling this function has the same effect as calling mps_arena_park(): all collections are run to completion, and the arena is clamped so that no new collections begin. The MPS also uses barriers to maintain remembered sets, so calling this function will effectively destroy the remembered sets and any optimization gains from them.

Calling this function is time-consuming: any active collections will be run to completion; and the next collection will have to recompute all the remembered sets by scanning the entire arena.

The recomputation of the remembered sets can be avoided by calling mps_arena_unsafe_expose_remember_protection() instead of mps_arena_expose(), and by calling mps_arena_unsafe_restore_protection() before calling mps_arena_release(). Those functions have unsafe aspects and place restrictions on what the client program can do (basically no exposed data can be changed).

void mps_arena_unsafe_expose_remember_protection(mps_arena_t arena)

Deprecated

If you need access to protected memory for debugging, contact us.

Ensure that the MPS is not protecting any page in the arena with a read barrier or write barrier. In addition, request the MPS to remember some parts of its internal state so that they can be restored later.

arena is the arena to expose.

This function is the same as mps_arena_expose(), but additionally causes the MPS to remember its protection state. The remembered protection state can optionally be restored later by calling the mps_arena_unsafe_restore_protection() function. This is an optimization that avoids the MPS having to recompute all the remembered sets by scanning the entire arena.

However, restoring the remembered protections is only safe if the contents of the exposed pages have not been changed; therefore this function should only be used if you do not intend to change the pages, and the remembered protection must only be restored if the pages have not been changed.

The MPS will only remember the protection state if resources (memory) are available. If memory is low then only some or possibly none of the protection state will be remembered, with a corresponding necessity to recompute it later. The MPS provides no mechanism for the client program to determine whether the MPS has in fact remembered the protection state.

The remembered protection state, if any, is discarded after calling mps_arena_unsafe_restore_protection(), or as soon as the arena leaves the clamped state by calling mps_arena_release().

void mps_arena_unsafe_restore_protection(mps_arena_t arena)

Deprecated

If you need access to protected memory for debugging, contact us.

Restore the remembered protection state for an arena.

arena is the arena to restore the protection state for.

This function restores the protection state that the MPS has remembered when the client program called mps_arena_unsafe_expose_remember_protection(). The purpose of remembering and restoring the protection state is to avoid the need for the MPS to recompute all the remembered sets by scanning the entire arena, that occurs when mps_arena_expose() is used, and which causes the next garbage collection to be slow.

The client program must not change the exposed data between the call to mps_arena_unsafe_expose_remember_protection() and mps_arena_unsafe_restore_protection(). If the client program has changed the exposed data then mps_arena_unsafe_restore_protection() must not be called: in this case simply call mps_arena_release().

Calling this function does not release the arena from the clamped state: mps_arena_release() must be called to continue normal collections.

Calling this function causes the MPS to forget the remembered protection state; as a consequence the same remembered state cannot be restored more than once.