1 /* 2 * Copyright 2023 Code Intelligence GmbH 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package com.code_intelligence.jazzer.mutation.api; 18 19 /** 20 * Knows how to initialize and mutate (parts of) an existing object of type {@code T} in place and 21 * how to incorporate (cross over) parts of another object of the same type. 22 * 23 * <p>Certain types, such as immutable and primitive types, can not be mutated in place. For 24 * example, {@link java.util.List} can be mutated in place whereas {@link String} and {@code int} 25 * can't. In such cases, use {@link ValueMutator} instead. 26 * 27 * <p>Implementations 28 * <ul> 29 * <li>MAY weakly associate mutable state with the identity (not equality class) of objects they 30 * have been passed as arguments or returned from initialization functions; 31 * <li>MAY assume that they are only passed arguments that they have initialized or mutated;</li> 32 * <li>SHOULD use {@link com.code_intelligence.jazzer.mutation.support.WeakIdentityHashMap} for 33 * this purpose; 34 * <li>MUST otherwise be deeply immutable; 35 * <li>SHOULD override {@link Object#toString()} to return {@code 36 * Debuggable.getDebugString(this)}. 37 * </ul> 38 * 39 * @param <T> the reference type this mutator operates on 40 */ 41 public interface InPlaceMutator<T> extends Debuggable { 42 /** 43 * Implementations 44 * <ul> 45 * <li>MUST accept any mutable instance of {@code T}, not just those it creates itself. 46 * <li>SHOULD, when called repeatedly, initialize the object in ways that are likely to be 47 * distinct. 48 * </ul> 49 */ initInPlace(T reference, PseudoRandom prng)50 void initInPlace(T reference, PseudoRandom prng); 51 52 /** 53 * Implementations 54 * <ul> 55 * <li>MUST ensure that {@code reference} does not {@link Object#equals(Object)} the state it 56 * had prior to the call (if possible); 57 * <li>MUST accept any mutable instance of {@code T}, not just those it creates itself. 58 * <li>SHOULD, when called repeatedly, be able to eventually reach any valid state of the part 59 * of {@code T} governed by this mutator; 60 * </ul> 61 */ mutateInPlace(T reference, PseudoRandom prng)62 void mutateInPlace(T reference, PseudoRandom prng); 63 64 /** 65 * Implementations 66 * <ul> 67 * <li>MUST ensure that {@code reference} does not {@link Object#equals(Object)} the state it 68 * had prior to the call (if possible); 69 * <li>MUST accept any mutable instance of {@code T}, not just those it creates itself. 70 * <li>MUST NOT mutate {@code otherReference}</li> 71 * </ul> 72 */ crossOverInPlace(T reference, T otherReference, PseudoRandom prng)73 void crossOverInPlace(T reference, T otherReference, PseudoRandom prng); 74 } 75