Management of failure in the LLDS code generator

This document describes the arrangement for handling failure in the LLDS code generator. It builds upon allocation.html, which describes the mechanism we use to preserve the values of variables that may be needed on backtracking and the mechanism we use to set up resumption points.

Runtime data structures

In the design of the nondet stack, two registers point to nondet stack frames.

Each ordinary nondet stack frame contains five fixed slots:

Ordinary nondet stack frames may also contain the values of variables and/or temporary values such as saved trail pointers.

All temporary nondet stack frames contain the three fixed slots, prevfr, redoip and redofr. Temporary frames created by model_det and model_semi procedures also have a fourth fixed slot, detfr, which points to the stack frame (on the det stack) of the procedure that created them. Temporary nondet stack frames never contain any slots except these fixed slots. Therefore for any given nondet frame its size determines its type. If this is three words, it is a temporary frame created by a model_non procedure; if this is four words, it is a temporary frame created by a model_det or model_semi procedure; if this is five words or more, it is an ordinary frame.

The fixed slots prevfr, redoip and redofr are present in all nondet stack frames, ordinary and temporary, at the same offset and with the same semantics. Therefore code that accesses only these fields of a nondet stack frame does not need to find out what kind of frame it is.

The detfr slot is for the accurate garbage collector; it is never used by the backtracking mechanism. Therefore in the following we can and will treat all temporary frames the same.

In grades that support stack segments, the runtime system puts a sentinel frame at the bottom of every segment after the first. The sentinel frame appears as an ordinary frame, with all five of the usual fixed slots, but the two fields that ordinarily contain the success continuation are not used for that purpose, since sentinel frames do not correspond to calls, and thus cannot return. Instead, the succfr slot contains the value of the curfr abstract machine register at the time the sentinel frame was created, and the succip slot contains the address of the notreached label. The address of the memory zone structure that contains the segment the sentinel is at the bottom of is stored in the sentinel frame's one framevar. Sentinel frames can be distinguished from other ordinary frames by the fact that their redoip slot contains the address of the label in the runtime that pops the segment off the nondet stack.

Runtime actions

The redo() macro is implemented as 

curfr = redofr_slot(maxfr);
goto *redoip_slot(maxfr);

while the fail() macro discards the top nondet stack frame and then executes a redo().

It is an invariant that curfr will always point to an ordinary nondet stack frame; it will never point to a temporary frame.

It is an invariant that for any nondet stack frame whose address is frame_addr, redofr_slot(frame_addr) == frame_addr whenever curfr == frame_addr. However, it is possible that redofr_slot(frame_addr) != frame_addr at other times.

One implication of this possibility is that at a point in the code where execution may resume after a redo(), the code of a procedure can assume that curfr == maxfr at that point only if it did not hijack any frames anywhere to the left of that point.

Code generator data structures

The proposed code generator uses two data structures for managing failure: the resume point stack and the left context. It also consults the option --allow-hijacks that says whether hijacks (see below) of nondet stack frames are allowed. Grades that call for accurate garbage collection imply --no-allow-hijacks.

The resume point stack

Several kinds of goals want to get control on failure.

These kinds of goals can be nested inside each other.

Whenever we are about to generate code for a goal after whose failure we want to get back control, we push an entry onto the resume point stack. This entry gives the arrangements for the resumption point; the details of the arrangement are described in the "Resumption points" section of allocation.html.

The depth of the resume point stack reflects the depth of nesting of goals that want to get control on failure.

It is an invariant that the resume point stack is the same before and after generating code for a goal.

The left context

When the code generator looks at a goal, the left context field of code_info gives information about what happened to the left of this goal that may affect how we handle failures in this goal.

The left context has three subfields.

The resume_point_known subfield is initialized to known in all procedures. The curfr_maxfr subfield is initialized to must_be_equal in model_non procedures, and to may_be_different in other procedures. The condition_environment subfield is always initialized to not_inside_non_condition.

When the code generator processes any nondet goal, it must set the resume_point_known subfield to unknown at the end of the goal.

When the code generator processes a model_non construct that leaves this procedure (i.e. a call, higher order call or method call), it must also set the curfr_maxfr subfield to may_be_different at the end of the goal. (Since a model_non procedure can remove its own stack frame just before it succeeds for the last time, we can't say that after a call to such a procedure maxfr *will* be different from curfr.)

When the code generator processes branched structures (if-then-elses, switches or disjunctions), if resume_point_known is unknown at the end of any arm, it must be unknown after the branched structure, and if curfr_maxfr is may_be_different at the end of any arm, it must also be may_be_different after the branched structure.

When the code generator establishes a new resumption point, it will set the resume_point_known subfield to known, but it must not set the curfr_maxfr subfield to must_be_equal.

Note that in the absence of model_non code, the resume_point_known subfield will always have the value known.

Generating failure

How we generate code for failure depends on the top entry on the resume point stack and the left context.

If resume_point_known is no, the code we generate for failure is redo(). If resume_point_known is yes, the code we generate for failure is a branch to one of the labels in the resumption point; which one depends on the locations of the variables needed at the resumption point (see allocation.html).

To prepare for backtracking to a resumption point that takes place via a redo(), not via a direct branch, we must select one of the labels as the one whose address will be put in the redoip slot via which backtracking will take place. This label will be the stack label, the label whose resume map maps all the resume variables to their stack slots.

We have to make sure that this choice is always valid. We do this by enforcing three invariants:

Classifying left contexts

The code generator classifies left contexts into those in which hijacking is allowed, and those in which hijacking is not allowed. Hijacking is allowed only if the --allow-hijacks option is set, and the condition_environment subfield is not_inside_non_condition.

The code generator further classifies left contexts in which hijacking is allowed into the following three categories:

The code generator can treat any situation as a no-hijack case, it can treat best case as either middle case or worst case, and it can treat middle case as worst case. However, it should be able to generate better code if it exploits the available information.

It may be that no-hijack case yields better code than worst case; this should be investigated TODO.

Handling disjunctions

Handling nondet disjunctions

For all the hijacking cases, the choices represented by the hijacked redoip and maybe redofr slots cannot be backtracked to until the disjunction that we are generating code for has failed. This cannot happen until the last disjunct has failed, by which time the slots must have been restored. This maintains the invariant that for any nondet stack frame whose address is frame_addr, redofr_slot(frame_addr) == frame_addr whenever curfr == frame_addr.

Handling semi or det disjunctions

When the code generator enters a nonlast disjunct, it pushes a new entry on the resume point stack indicating the resume point at the start of the next disjunct. When the code generator enters the last disjunct, it does not push any entry on the resume point stack.

Handling if-then-elses

Handling nondet if-then-elses with nondet conditions

All these four manipulate the redoip slot of the nondet stack frame that is on top of the nondet stack when execution enters the condition. On entry to the condition, we set it to point the start of the else part; on exit from the condition, we reset it to some other value to prevent backtracking to the else part. If the condition hijacks this slot, this scheme will not work. (Although the code that hijacks the slot will restore it to its original value before finally failing, that is too late in this case.) Therefore before entering the condition, the code generator sets condition_environment to inside_non_condition; on exit from the condition, it restores the original value. (These are the only times the value of condition_environment is ever changed.)

Before entering the condition, the code generator will set resume_point_known to known, since the resumption point to go to on failure of the condition is known (it is the start of the else part). However, this resumption point does not apply to failures in the then part. Therefore before entering the then part, the code generator will reset resume_point_known to the value it had before entering the if-then-else, except if resume_point_known has become unknown during the generation of code for the condition, in which case it will continue to be unknown.

A failure inside the condition should cause a branch to the start of the else case only if the condition has not already succeeded. In general, the code inside the condition may branch directly to the start of the else case only up to the first goal that can succeed more than once; any other goal following such a goal should branch through the redoip slot on which the if-then-else performs the soft cut.

There are only two kinds of constructs that can succeed more than once: calls (including higher order and method calls) and disjunctions. When the code generator processes a call that can succeed more than once, it sets resume_point_known to unknown, which causes later failures to perform a redo. To ensure that code in the last disjunct of a model_non disjunction and code following a model_non disjunction also fail via a redo, the code generator will, on entering the last disjunct of a model_non disjunction, check whether condition_environment is inside_non_condition, and if yes, it will set resume_point_known to unknown. (We do not do this in disjuncts other than the last because non-last disjuncts fail to the start of the next disjunct). Since at the end of branched control structures such as disjunctions the code generator sets resume_point_known to unknown if resume_point_known was unknown at the end of any branch, this ensures that resume_point_known will stay unknown after the disjunction. (The end of branched control structures treat the curfr_vs_maxfr subfield similarly, i.e. set it to may_be_different if it was may_be_different at the end of any branch. The condition_environment subfield must, by construction, have the same value at the end of every branch, and this is the value it will have after the branched control structure.)

Handling nondet if-then-elses with semi or det conditions

We can handle these as we handle nondet if-then-elses with nondet conditions, or we can handle them as we handle semi or det if-then-elses, with the exception that we generate the then part and the else part as nondet goals. The latter is more efficient, so that is what we do.

Handling semi or det if-then-elses

Before the code generator enters the condition, it pushes a new entry on the resume point stack indicating the resume point at the start of the else part, to the stack continuation in that resume point. After the code generator emerges from the condition, it pops the new entry off the resume point stack.

Handling negations

We handle not(G) as (if G then fail else true).

Handling commits

Handling commits across nondet goals

Since we are cutting away any frames created by the goal being committed across, and since any resumption points established in that goal cannot survive across the commit, at the end of processing the commit we can reset both curfr_maxfr and resume_point_known to their values before the commit.

We do not need to push a junk frame when entering the goal to be committed across even if this goal may perform a hijacking. If the goal fails, either it did not do any hijacking, or it will have restored anything it hijacked before failing. If the goal succeeds, it may have hijacked the top frame, but we since we do not need to preserve any further solutions inside the goal, we can simply restore that frame to its original contents anyway.

Handling commits across multi goals

This is the way the code generator handles commits across nondet goals, except that we do not need to handle any failure of the goal being committed across, and thus do not need to set any redoips or hijack anything.