From 9e046c1dc3ca86145ccd8b05bede8de5fc0f8cd9 Mon Sep 17 00:00:00 2001 From: David Jones Date: Wed, 9 Jul 2003 12:46:15 +0100 Subject: [PATCH] Mps ref man minor updates. mps_arena_formatted_objects_walk et al Copied from Perforce Change: 50079 ServerID: perforce.ravenbrook.com --- mps/manual/reference/index.html | 152 +++++++++++++++++++++++++++++--- 1 file changed, 141 insertions(+), 11 deletions(-) diff --git a/mps/manual/reference/index.html b/mps/manual/reference/index.html index 0fcd66c112e..86fdd4058fd 100644 --- a/mps/manual/reference/index.html +++ b/mps/manual/reference/index.html @@ -2520,7 +2520,8 @@ href="#mps_ap_alloc_pattern_begin">mps_ap_alloc_pattern_begin

Summary

-

mps_amc_apply is used to inspect objects in an AMC pool. You may only call it when thearena is parked (for example, after mps_arena_collect).

+

mps_amc_apply is used to inspect objects in an AMC pool. You may only call it when the +arena is parked (for example, after mps_arena_collect).

Associated Protocols

@@ -3889,7 +3890,21 @@ extern void mps_arena_formatted_objects_walk(mps_arena_t,

mps_arena in an MPS arena object.

-

stepper is a client-supplied function (pointer) of the right type (see mps_formatted_objects_stepper_t). This function is applied to every object in allformatted pools. This function should take the argument list (mps_addr_t object, mps_fmt_t format,mps_pool_t pool, void *p, size_t s). object is the object to which the function is being applied. format is the format (an MPS format object) of the object, pool is the pool in which the object resides, p and s are copies of the corresponding values that the client passed into mps_arena_formatted_objects_walk originally.

+

stepper is a client-supplied function (pointer) of +the right type (see mps_formatted_objects_stepper_t). +This function is applied to every object in all formatted pools. +This function should take the argument list (mps_addr_t object, +mps_fmt_t format,mps_pool_t pool, void *p, size_t s) and return +void. +object is the object to which the function is being +applied. +format is the format (an MPS format object) +of the object. pool is the pool in which the object +resides. p and s are copies of the +corresponding values that the client passed into mps_arena_formatted_objects_walk +originally.

p and s are passed into the function specified by the stepper argument whenever the MPS calls that function. See mps_formatted_objects_stepper_t.

@@ -3906,10 +3921,24 @@ extern void mps_arena_formatted_objects_walk(mps_arena_t,

Description

-

mps_arena_formatted_objects_walk is used to iterate over all formatted objects in the MPSheap. A client-supplied function is called for every object in all formatted pools; the object, theformat, and the pool are passed to the user supplied function, as well as some closure variables.

+

mps_arena_formatted_objects_walk +is used to iterate over all formatted objects in the MPS heap. A +client-supplied function is called for every object in all formatted +pools; the object, the format, and the pool are passed to the user +supplied function, as well as user supplied closure variables.

-

Applies stepper function to a pool-class-specific collection of objects (that is, the poolclass determines which objects in its instances get walked). Typically pool classes will arrangethat all validly formatted objects are walked. During a trace this will in general be only the blackobjects, though the leaf pool class (LO), for example, will walk all objects since they are validlyformatted whether they are black or white. Padding objects may be walked at the pool classesdiscretion, the client should handle this case.

+

Applies stepper function to a pool-class-specific collection of +objects (that is, the pool class determines which objects in its +instances get walked). Typically pool classes will arrange that all +validly formatted objects are walked. During a trace this will in +general be only the blackobjects, though the leaf pool class (LO), +for example, will walk all objects since they are validly formatted +whether they are black or white. Padding objects may be walked at +the pool classes discretion, the client should handle this case.

+

The user supplied stepper function is called in a restricted context. +It may not in general call any MPS function.

Example

@@ -3935,6 +3964,92 @@ href="#mps_formatted_objects_stepper_t">mps_formatted_objects_stepper_tNotes +

function mps_arena_park

+ + +

Name

+ +

mps_arena_has_addr

+ + +

Summary

+ +

mps_arena_has_addr tests +whether an address is managed by a particular arena. +

+ + +

Associated Protocols

+ +

Arena.

+ + +

Syntax

+ +

extern mps_bool_t mps_arena_has_addr(mps_arena_t arena, +mps_addr_t addr);

+ + +

Arguments

+ +

arena an arena

+ +

addr an address

+ + +

Returned Values

+ +

A boolean. Returns true if the address is managed by the arena, +false otherwise. + + +

Resources

+ +

mps.h

+ + +

Description

+ +

+mps_arena_has_addr determines +whether a particular address is managed by a particular arena. An arena +manages a portion of total address space available on the hardware +architecture. No two arenas overlap so for any particular address this +function will return true for at most one arena. In general not all the +architecture addresses are managed by some arena; some addreses will not +be managed by any arena. This is what allows the MPS to cooperate with +other memory managers, shared object loaders, memory mapped file I/O, +and such like - it does not steal the whole address space. +

+

+The results from this function are true only for the instant at which +the function returned. In some circumstances the results may +immediately become invalidated (for example, a garbage collection may +occur, the address in question may become free, the arena may choose to +unmap the address and return storage to the operating system); for +reliable results call this function whilst the arena is parked. +

+ +

Example

+ + +

Error Handling

+ +

Can't fail.

+ + +

See Also

+ +

+ +mps_arena_park used to park an +arena, + +

Notes

+ +

None.

+ +

function mps_arena_park

@@ -6434,12 +6549,12 @@ void go(mps_space_t space)

Summary

-

Type of the client supplied heap walker component.

+

Type of the client supplied heap walker function.

Associated Protocols

-

None.

+

Heap walking.

Type

@@ -6449,7 +6564,11 @@ void go(mps_space_t space)

Arguments

-

The function pointed to by an object of type mps_formatted_objects_stepper_t takes thefollowing argument list:

+

mps_formatted_objects_stepper +is a type not a function so it doesn't take any arguments; however the +function pointed to by an object of this type does. Such functions +take the following argument list:

(mps_addr_t object, mps_fmt_t format, mps_pool_t pool, void *p, size_t s)

@@ -6459,12 +6578,14 @@ void go(mps_space_t space)

pool in the MPS pool in which the client object resides.

-

p and s are two closure values which are copies of the corresponding values which the clientpassed into mps_arena_formatted_objects_walk.

+

p and s are two closure values which are copies of the corresponding values which the client +passed into the heap walking function, mps_arena_formatted_objects_walk.

Returned Values

-

The function pointed to by an object of type mps_formatted_objects_stepper_t returns noarguments.

+

The function pointed to by an object of type mps_formatted_objects_stepper_t returns no +arguments.

Resources

@@ -6474,7 +6595,15 @@ void go(mps_space_t space)

Description

-

A pointer to a function is passed into the function mps_arena_formatted_objects_walk; the pointer has this type. The heap walker arranges to apply this function to all objects on the heap.

+

This symbol describe the type of pointers passed into the heap +walking function +mps_arena_formatted_objects_walk. +The heap walker arranges to apply this +function to all objects on the heap, see +mps_arena_formatted_objects_walk +for details.

Example

@@ -6484,7 +6613,8 @@ void go(mps_space_t space)

Error Handling

-

The function pointed to by an object of type mps_formatted_objects_stepper_t have no way toreturn an error code to the caller.

+

The function pointed to by an object of type mps_formatted_objects_stepper_t have no way to +return an error code to the caller.

See Also