Package edu.berkeley.cs.jqf.fuzz.ei

Class ExecutionIndexingGuidance.MappedInput

java.lang.Object

edu.berkeley.cs.jqf.fuzz.ei.ZestGuidance.Input<ExecutionIndex>

edu.berkeley.cs.jqf.fuzz.ei.ExecutionIndexingGuidance.MappedInput

All Implemented Interfaces:

Iterable<Integer>

Direct Known Subclasses:

ExecutionIndexingGuidance.MappedSeedInput

Enclosing class:

ExecutionIndexingGuidance

public class ExecutionIndexingGuidance.MappedInput
extends ZestGuidance.Input<ExecutionIndex>

A candidate test input represented as a map from execution indices to integer values.

When a quickcheck-like generator requests a new ``random'' byte, the current execution index is used to retrieve the input from this input map (a fresh value is generated and stored in the map if the key is not mapped).

Inputs should not be publicly mutable. The only way to mutate an input is via the fuzz(java.util.Random) method which produces a new input object with some values mutated.

Field Summary

Fields

Modifier and Type	Field	Description
protected boolean	executed	Whether this input has been executed.
protected ArrayList<ExecutionIndex>	orderedKeys	A list of execution indexes that are actually requested by the test program when executed with this input.
protected LinkedHashMap<ExecutionIndex,Integer>	valuesMap	A map from execution indexes to the byte (0-255) to be returned at that index.

Constructor Summary

Constructors

Constructor	Description
MappedInput()	Create an empty input map.
MappedInput(ExecutionIndexingGuidance.MappedInput toClone)	Create a copy of an existing input map.

Method Summary

Modifier and Type	Method	Description
ZestGuidance.Input	fuzz(Random random)	Return a new input derived from this one with some values mutated.
protected ExecutionIndexingGuidance.MappedInput	fuzz(Random random, Map<ExecutionContext,ArrayList<edu.berkeley.cs.jqf.fuzz.ei.ExecutionIndexingGuidance.InputLocation>> ecToInputLoc)	Return a new input derived from this one with some values mutated.
void	gc()	Trims the input map of all keys that were never actually requested since its construction.
int	getOrGenerateFresh(ExecutionIndex key, Random random)	Retrieve a value for an execution index if mapped, else generate a fresh value.
protected Integer	getValueAtKey(ExecutionIndex ei)	Gets the byte mapped by this input at a given execution index.
Iterator<Integer>	iterator()
protected void	setValueAtKey(ExecutionIndex ei, int val)	Sets the byte mapped by this input at a given execution index.
int	size()	Returns the size of this input, in terms of number of bytes in its value map.

Methods inherited from class edu.berkeley.cs.jqf.fuzz.ei.ZestGuidance.Input

isFavored, sampleGeometric, setFavored

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Field Detail

executed

protected boolean executed

Whether this input has been executed. When this field is false, the field orderedKeys is not yet populated and must not be used. When this field is true, the input should be considered immutable and neither orderedKeys nor valuesMap must be modified.

valuesMap

protected LinkedHashMap<ExecutionIndex,Integer> valuesMap

A map from execution indexes to the byte (0-255) to be returned at that index.

orderedKeys

protected ArrayList<ExecutionIndex> orderedKeys

A list of execution indexes that are actually requested by the test program when executed with this input.

This list is initially empty, and is populated at the end of the run, after which it is frozen. The list of keys are in order of their occurrence in the execution trace and can therefore be used to serialize the map into a sequence of bytes.

Constructor Detail

MappedInput

public MappedInput()

Create an empty input map.

MappedInput

public MappedInput(ExecutionIndexingGuidance.MappedInput toClone)

Create a copy of an existing input map.

Parameters:

toClone - the input map to clone

Method Detail

size

public final int size()

Returns the size of this input, in terms of number of bytes in its value map.

Specified by:

size in class ZestGuidance.Input<ExecutionIndex>

Returns:

the size of this input

getOrGenerateFresh

public int getOrGenerateFresh(ExecutionIndex key,
                              Random random)
                       throws IllegalStateException

Retrieve a value for an execution index if mapped, else generate a fresh value.

Specified by:

getOrGenerateFresh in class ZestGuidance.Input<ExecutionIndex>

Parameters:

key - the execution index of the trace event requesting a new byte

random - the PRNG

Returns:

the value to return to the quickcheck-like generator

Throws:

IllegalStateException - if this method is called after the input has been executed

getValueAtKey

protected final Integer getValueAtKey(ExecutionIndex ei)
                               throws IndexOutOfBoundsException

Gets the byte mapped by this input at a given execution index.

Parameters:

ei - the execution index

Returns:

the value mapped for this index, or null if no such mapping exists

Throws:

IndexOutOfBoundsException - if the offset is negative or larger than size()()-1

setValueAtKey

protected final void setValueAtKey(ExecutionIndex ei,
                                   int val)
                            throws IndexOutOfBoundsException,
                                   IllegalStateException

Sets the byte mapped by this input at a given execution index.

Parameters:

ei - the execution index at which to insert

val - the byte to insert

Throws:

IndexOutOfBoundsException - if the offset is negative or larger than size()()-1

IllegalStateException - if this method is called after the input has been executed

gc

public void gc()

Trims the input map of all keys that were never actually requested since its construction.

Although this operation mutates the underlying object, the effect should not be externally visible (at least as long as the test executions are deterministic).

Specified by:

gc in class ZestGuidance.Input<ExecutionIndex>

fuzz

public ZestGuidance.Input fuzz(Random random)

Return a new input derived from this one with some values mutated. Pass-through to fuzz(Random, Map)

Specified by:

fuzz in class ZestGuidance.Input<ExecutionIndex>

Parameters:

random - a pseudo-random source

Returns:

a mutated input

fuzz

protected ExecutionIndexingGuidance.MappedInput fuzz(Random random,
                                                     Map<ExecutionContext,ArrayList<edu.berkeley.cs.jqf.fuzz.ei.ExecutionIndexingGuidance.InputLocation>> ecToInputLoc)

Return a new input derived from this one with some values mutated.

This method performs one or both of random mutations and splicing.

Random mutations are done by performing M mutation operations each on a random contiguous sequence of N bytes, where M and N are sampled from a geometric distribution with mean ExecutionIndexingGuidance.MEAN_MUTATION_COUNT and ExecutionIndexingGuidance.MEAN_MUTATION_SIZE respectively.

Splicing is performed by first randomly choosing a location and its corresponding execution context in this input's value map, and then copying a contiguous sequence of up to Z bytes from another input, starting with a location that also maps the same execution context. Here, Z is sampled from a uniform distribution from 0 to ExecutionIndexingGuidance.MAX_SPLICE_SIZE.

Parameters:

random - the PRNG

ecToInputLoc - map of execution contexts to input-location pairs

Returns:

a newly fuzzed input

iterator

public Iterator<Integer> iterator()