org.eigenbase.relopt.hep
Class HepProgramBuilder

java.lang.Object
  org.eigenbase.relopt.hep.HepProgramBuilder

public class HepProgramBuilder
extends Object

HepProgramBuilder creates instances of HepProgram.

Version:

$Id: //open/dev/farrago/src/org/eigenbase/relopt/hep/HepProgramBuilder.java#10 $

Author:

John V. Sichi

Field Summary

private HepInstruction.BeginGroup	group
private List<HepInstruction>	instructions

Constructor Summary

HepProgramBuilder()
Creates a new HepProgramBuilder with an initially empty program.

Method Summary

void	addCommonRelSubExprInstruction() Adds an instruction to attempt to match instances of CommonRelSubExprRule, but only in cases where vertices have more than one parent.
void	addConverters(boolean guaranteed) Adds an instruction to attempt to match instances of ConverterRule, but only where a conversion is actually required.
void	addGroupBegin() Adds an instruction to begin a group of rules.
void	addGroupEnd() Adds an instruction to end a group of rules, firing the group collectively.
void	addMatchLimit(int limit) Adds an instruction to limit the number of pattern matches for subsequent instructions.
void	addMatchOrder(HepMatchOrder order) Adds an instruction to change the order of pattern matching for subsequent instructions.
void	addRuleByDescription(String ruleDescription) Adds an instruction to attempt to match a specific rule identified by its unique description.
<R extends RelOptRule> void	addRuleClass(Class<R> ruleClass) Adds an instruction to attempt to match any rules of a given class.
void	addRuleCollection(Collection<RelOptRule> rules) Adds an instruction to attempt to match any rules in a given collection.
void	addRuleInstance(RelOptRule rule) Adds an instruction to attempt to match a specific rule object.
void	addSubprogram(HepProgram program) Adds an instruction to execute a subprogram.
private void	clear()
HepProgram	createProgram() Returns the constructed program, clearing the state of this program builder as a side-effect.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

instructions

private List<HepInstruction> instructions

group

private HepInstruction.BeginGroup group

Constructor Detail

HepProgramBuilder

public HepProgramBuilder()

Creates a new HepProgramBuilder with an initially empty program. The program under construction has an initial match order of HepMatchOrder.ARBITRARY, and an initial match limit of HepProgram.MATCH_UNTIL_FIXPOINT.

Method Detail

clear

private void clear()

addRuleClass

public <R extends RelOptRule> void addRuleClass(Class<R> ruleClass)

Adds an instruction to attempt to match any rules of a given class. The order in which the rules within a class will be attempted is arbitrary, so if more control is needed, use addRuleInstance instead.

Note that when this method is used, it is also necessary to add the actual rule objects of interest to the planner via RelOptPlanner.addRule(org.eigenbase.relopt.RelOptRule). If the planner does not have any rules of the given class, this instruction is a nop.

TODO: support classification via rule annotations.

Parameters:

ruleClass - class of rules to fire, e.g. ConverterRule.class

addRuleCollection

public void addRuleCollection(Collection<RelOptRule> rules)

Adds an instruction to attempt to match any rules in a given collection. The order in which the rules within a collection will be attempted is arbitrary, so if more control is needed, use addRuleInstance instead. The collection can be "live" in the sense that not all rule instances need to have been added to it at the time this method is called. The collection contents are reevaluated for each execution of the program.

Note that when this method is used, it is NOT necessary to add the rules to the planner via RelOptPlanner.addRule(org.eigenbase.relopt.RelOptRule); the instances supplied here will be used. However, adding the rules to the planner redundantly is good form since other planners may require it.

Parameters:

rules - collection of rules to fire

addRuleInstance

public void addRuleInstance(RelOptRule rule)

Adds an instruction to attempt to match a specific rule object.

Note that when this method is used, it is NOT necessary to add the rule to the planner via RelOptPlanner.addRule(org.eigenbase.relopt.RelOptRule); the instance supplied here will be used. However, adding the rule to the planner redundantly is good form since other planners may require it.

Parameters:

rule - rule to fire

addRuleByDescription

public void addRuleByDescription(String ruleDescription)

Adds an instruction to attempt to match a specific rule identified by its unique description.

Note that when this method is used, it is necessary to also add the rule object of interest to the planner via RelOptPlanner.addRule(org.eigenbase.relopt.RelOptRule). This allows for some decoupling between optimizers and plugins: the optimizer only knows about rule descriptions, while the plugins supply the actual instances. If the planner does not have a rule matching the description, this instruction is a nop.

Parameters:

ruleDescription - description of rule to fire

addGroupBegin

public void addGroupBegin()

Adds an instruction to begin a group of rules. All subsequent rules added (until the next endRuleGroup) will be collected into the group rather than firing individually. After addGroupBegin has been called, only addRuleXXX methods may be called until the next addGroupEnd.

addGroupEnd

public void addGroupEnd()

Adds an instruction to end a group of rules, firing the group collectively. The order in which the rules within a group will be attempted is arbitrary. Match order and limit applies to the group as a whole.

addConverters

public void addConverters(boolean guaranteed)

Adds an instruction to attempt to match instances of ConverterRule, but only where a conversion is actually required.

Parameters:

guaranteed - if true, use only guaranteed converters; if false, use only non-guaranteed converters

addCommonRelSubExprInstruction

public void addCommonRelSubExprInstruction()

Adds an instruction to attempt to match instances of CommonRelSubExprRule, but only in cases where vertices have more than one parent.

addMatchOrder

public void addMatchOrder(HepMatchOrder order)

Adds an instruction to change the order of pattern matching for subsequent instructions. The new order will take effect for the rest of the program (not counting subprograms) or until another match order instruction is encountered.

Parameters:

order - new match direction to set

addMatchLimit

public void addMatchLimit(int limit)

Adds an instruction to limit the number of pattern matches for subsequent instructions. The limit will take effect for the rest of the program (not counting subprograms) or until another limit instruction is encountered.

Parameters:

limit - limit to set; use HepProgram.MATCH_UNTIL_FIXPOINT to remove limit

addSubprogram

public void addSubprogram(HepProgram program)

Adds an instruction to execute a subprogram. Note that this is different from adding the instructions from the subprogram individually. When added as a subprogram, the sequence will execute repeatedly until a fixpoint is reached, whereas when the instructions are added individually, the sequence will only execute once (with a separate fixpoint for each instruction).

The subprogram has its own state for match order and limit (initialized to the defaults every time the subprogram is executed) and any changes it makes to those settings do not affect the parent program.

Parameters:

program - subprogram to execute

createProgram

public HepProgram createProgram()

Returns the constructed program, clearing the state of this program builder as a side-effect.

Returns:

immutable program