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 Details

    • 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 Details

    • 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 Details

    • 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()