17. Allocation frames

Deprecated

starting with version 1.111.

If you need special handling of stack-like allocation, contact us.

An allocation frame is a marker that can pushed onto an allocation point by calling mps_ap_frame_push(), and then popped by calling mps_ap_frame_pop() to indicate that all blocks allocated on the allocation point are dead (in the case of manual pools), or very likely dead (in the case of automatic pools).

Allocation frames can be used by the client program to efficiently implement stack-like patterns of allocation.

Note

All pool classes that support allocation points also support pushing and popping of allocation frames, but only the SNC (Stack No Checking) pool class actually uses these frames to manage its blocks.

mps_frame_t

The type of allocation frames.

mps_res_t mps_ap_frame_push(mps_frame_t *frame_o, mps_ap_t ap)

Declare a new allocation frame and push it onto an allocation point’s frame stack.

frame_o points to a location that will hold the new frame if the function is successful.

ap is the allocation point in which the new frame is declared.

Returns a result code. The creation of new frames (which is implicit in the action of this function) can consume resources, so this function can fail because there are insufficient resources, or if the correct protocol is not followed by the client program.

mps_res_t mps_ap_frame_pop(mps_ap_t ap, mps_frame_t frame)

Declare that a set of blocks in a allocation frame are dead or likely to be dead, and pop the frame from the allocation point’s frame stack.

ap is the allocation point in which frame was pushed.

frame is the allocation frame whose blocks are likely to be dead.

Returns a result code.

This function pops frame, making its parent the current frame. Popping invalidates frame and all frames pushed since frame. Popping frame also makes a declaration about the set of blocks which were allocated in frame and all frames which were pushed since frame.

The interpretation of this declaration depends on the pool that the allocation point belongs to. Typically, manual pool classes use this declaration to mean that the blocks are dead and their space can be reclaimed immediately, whereas automatic pool classes use this declaration to mean that the blocks are likely to be mostly dead, and may use this declaration to alter its collection decisions. See the documentation for the pool class.

In general a frame other than the current frame can be popped (all frames pushed more recently will be invalidated as well, as described above), but a pool class may impose the restriction that only the current frame may be popped. This restriction means that every push must have a corresponding pop. See the documentation for the pool class.

It is illegal to pop frames out of order (so the sequence “A = push; B = push; pop A; pop B” is illegal) or to pop the same frame twice (so the sequence “A = push, pop A, pop A” is illegal).