Skip to content

GitLab

DiSL
DiSL
Commit 9add01a7 authored by Lubomir Bulej's avatar Lubomir Bulej
Browse files
Options

Various cosmetic changes to simplify merging of the remaining bits from the newagent branch.

parent 15c55396
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 2517 additions and 2348 deletions
src-disl/ch/usi/dag/disl/annotation/After.java
View file @ 9add01a7
package ch.usi.dag.disl.annotation;
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Target;
import ch.usi.dag.disl.classcontext.ClassContext;
import ch.usi.dag.disl.dynamiccontext.DynamicContext;
import ch.usi.dag.disl.marker.Marker;
import ch.usi.dag.disl.processorcontext.ArgumentProcessorContext;
import ch.usi.dag.disl.staticcontext.StaticContext;
/**
* Marks a method as a DiSL snippet to be inserted after the marked code region.
* The snippet code will be executed both after normal and exceptional exit from
* the marked code region.
* <p>
* The After annotation instructs DiSL to insert the snippet body after the
* marked region. The snippet will be invoked after a normal exit of the region
* or after an exit caused by an exception.
*
* <b>Note:</b> This is a general contract. The actual implementation depends on
* the particular marker used with the snippet.
* <p>
* <b>note:</b> This is only general contract. It depends on particular marker
* how the contract will be implemented.
*
* The annotation has the following parameters which control the inlining of a
* snippet into target code:
* <ul>
* <li>{@link #marker}
* <li>{@link #args}
* <li>{@link #guard}
* <li>{@link #scope}
* <li>{@link #order}
* <li>{@link #dynamicBypass}
* </ul>
* <p>
* <b>usage:</b>
*
* This annotation can be only used with methods. In particular, a method
* representing a snippet must be {@code static}, must not return any value, and
* must not throw any exceptions.
* <p>
* There are multiple optional parameters the annotation takes. Browse them for
* more details on usage.
* The method can declare parameters the following types:
* <ul>
* <li>{@link #marker}</li>
* <li>{@link #args}</li>
* <li>{@link #guard}</li>
* <li>{@link #scope}</li>
* <li>{@link #order}</li>
* <li>{@link #dynamicBypass}</li>
* <li>{@link StaticContext} (or another type implementing it),
* <li>{@link DynamicContext},
* <li>{@link ClassContext}, and
* <li>{@link ArgumentProcessorContext}.
* </ul>
*
* <p>
* This annotation should be used only with static methods that does not return
* any value or throw any exception.
*
* <p>
* The method might be specified with arguments of following types.
* {@link ch.usi.dag.disl.staticcontext.StaticContext StaticContext (or
* derived)}, {@link ch.usi.dag.disl.dynamiccontext.DynamicContext
* DynamicContext}, {@link ch.usi.dag.disl.classcontext.ClassContext
* ClassContext} and
* {@link ch.usi.dag.disl.processorcontext.ArgumentProcessorContext
* ArgumentProcessContext}. There's no restriction on order or number of these
* arguments.
* The ordering and the number of the parameters is arbitrary.
*/
@Documented
@Target (ElementType.METHOD)
public @interface After {
// NOTE if you want to change names, you need to change
// SnippetParser.SnippetAnnotationData class
// NOTE because of implementation of annotations in java the defaults
// are not retrieved from here but from class mentioned above
//
// NOTE
//
// If you change any names here, you also need to change them
// in the DiSL class parser. Only do that if absolutely necessary,
// because this annotation is part of the DiSL public API.
//
// Also note that the defaults are not retrieved from here, but
// are set in the DiSL class parser.
//
/**
* <p>
* Marker class defines a region where the snippet is applied.
*
* Selects the marker class. A marker determines the region of code within a
* method where to apply the snippet.
*
* @see ch.usi.dag.disl.marker.Marker Implementation details
*/
Class<? extends Marker> marker();
Class <? extends Marker> marker();
/**
* Optional argument for the marker class, passed as a {@link String}.
* <p>
* Argument for the marker (as string).
*
* <p>
* Default value means none.
* Default value: {@code ""}, means "no arguments".
*/
String args() default ""; // cannot be null :(
String args() default "";
/**
* Selects methods in which to apply the snippet.
* <p>
* Scope of the methods, where the snippet is applied.
*
* See the {@link ch.usi.dag.disl.scope} package for more information about
* the scoping language.
* <p>
* Default value means everything.
*
* @see ch.usi.dag.disl.scope.ScopeImpl Implementation details
* Default value: {@code "*"}, means "everywhere".
*/
String scope() default "*";
/**
* Selects the guard class. A guard class determines whether a snippet
* will be inlined at a particular location or not. In general, guards
* provide more fine-grained control compared to scopes.
* <p>
* The guard class defining if the snippet will be inlined in particular
* region or not.
*
* <p>
* Default value means none.
* Default value: {@code void.class}, means "no guard used".
*/
Class<? extends Object> guard() default Object.class; // cannot be null :(
Class <? extends Object> guard() default void.class;
/**
* Determines snippet order when multiple snippets are to be inlined
* at the same location. The smaller the number, the closer to the boundary
* of the marked code region will be the snippet inlined.
* <p>
* Defines ordering of the snippets. Smaller number indicates that snippet
* will be inlined closer to the instrumented code.
*
* <p>
* Default is 100.
* Default value: {@code 100}
*/
int order() default 100;
/**
* Controls automatic bypass activation. This is an advanced option that
* allows to turn off automatic bypass activation for inlined snippets. This
* can be used when a snippet does not use any other (instrumented) classes,
* or when manual control over bypass activation is desired.
* <p>
* You can in general disable dynamic bypass on snippets, that are not using
* any other class. (Advanced option)
*
* <p>
* <b>note:</b> Usage of dynamic bypass is determined by the underlying
* NOTE: Usage of dynamic bypass is determined by the underlying
* instrumentation framework.
* <p>
* Default value: {@code true}, means "automatic bypass activation".
*/
boolean dynamicBypass() default true;
}
src-disl/ch/usi/dag/disl/annotation/AfterReturning.java
View file @ 9add01a7
package ch.usi.dag.disl.annotation;
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Target;
import ch.usi.dag.disl.classcontext.ClassContext;
import ch.usi.dag.disl.dynamiccontext.DynamicContext;
import ch.usi.dag.disl.marker.Marker;
import ch.usi.dag.disl.processorcontext.ArgumentProcessorContext;
import ch.usi.dag.disl.staticcontext.StaticContext;
/**
* <p>
* The AfterReturning annotation instructs DiSL to insert the snippet body after
* the marked region. The snippet will be invoked after a normal exit of the
* Marks a method as a DiSL snippet to be inserted after the marked code region.
* The snippet code will be executed after a normal exit from the marked code
* region.
*
* <p>
* <b>note:</b> This is only general contract. It depends on particular marker
* how the contract will be implemented.
*
* <b>Note:</b> This is a general contract. The actual implementation depends on
* the particular marker used with the snippet.
* <p>
* <b>usage:</b>
*
* <p>
* There are multiple optional parameters the annotation takes. Browse them for
* more details on usage.
* The annotation has the following parameters which control the inlining of a
* snippet into target code:
* <ul>
* <li>{@link #marker}</li>
* <li>{@link #args}</li>
* <li>{@link #guard}</li>
* <li>{@link #scope}</li>
* <li>{@link #order}</li>
* <li>{@link #dynamicBypass}</li>
* <li>{@link #marker}
* <li>{@link #args}
* <li>{@link #guard}
* <li>{@link #scope}
* <li>{@link #order}
* <li>{@link #dynamicBypass}
* </ul>
*
* <p>
* This annotation should be used only with static methods that does not return
* any value or throw any exception.
*
* This annotation can be only used with methods. In particular, a method
* representing a snippet must be {@code static}, must not return any value, and
* must not throw any exceptions.
* <p>
* The method might be specified with arguments of following types.
* {@link ch.usi.dag.disl.staticcontext.StaticContext StaticContext (or
* derived)}, {@link ch.usi.dag.disl.dynamiccontext.DynamicContext
* DynamicContext}, {@link ch.usi.dag.disl.classcontext.ClassContext
* ClassContext} and
* {@link ch.usi.dag.disl.processorcontext.ArgumentProcessorContext
* ArgumentProcessContext}. There's no restriction on order or number of these
* arguments.
* The method can declare parameters the following types:
* <ul>
* <li>{@link StaticContext} (or another type implementing it),
* <li>{@link DynamicContext},
* <li>{@link ClassContext}, and
* <li>{@link ArgumentProcessorContext}.
* </ul>
* <p>
* The ordering and the number of the parameters is arbitrary.
*/
@Documented
@Target (ElementType.METHOD)
public @interface AfterReturning {
// NOTE if you want to change names, you need to change
// SnippetParser.SnippetAnnotationData class
// NOTE because of implementation of annotations in java the defaults
// are not retrieved from here but from class mentioned above
//
// NOTE
//
// If you change any names here, you also need to change them
// in the DiSL class parser. Only do that if absolutely necessary,
// because this annotation is part of the DiSL public API.
//
// Also note that the defaults are not retrieved from here, but
// are set in the DiSL class parser.
//
/**
* <p>
* Marker class defines a region where the snippet is applied.
*
* Selects the marker class. A marker determines the region of code within a
* method where to apply the snippet.
*
* @see ch.usi.dag.disl.marker.Marker Implementation details
*/
Class<? extends Marker> marker();
Class <? extends Marker> marker();
/**
* Optional argument for the marker class, passed as a {@link String}.
* <p>
* Argument for the marker (as string).
*
* <p>
* Default value means none.
* Default value: {@code ""}, means "no arguments".
*/
String args() default ""; // cannot be null :(
String args() default "";
/**
* Selects methods in which to apply the snippet.
* <p>
* Scope of the methods where the snippet is applied.
*
* See the {@link ch.usi.dag.disl.scope} package for more information about
* the scoping language.
* <p>
* Default value means everything.
*
* @see ch.usi.dag.disl.scope.ScopeImpl Implementation details
* Default value: {@code "*"}, means "everywhere".
*/
String scope() default "*";
/**
* Selects the guard class. A guard class determines whether a snippet
* will be inlined at a particular location or not. In general, guards
* provide more fine-grained control compared to scopes.
* <p>
* The guard class defining if the snippet will be inlined in particular
* region or not.
*
* <p>
* Default value means none.
* Default value: {@code void.class}, means "no guard used".
*/
Class<? extends Object> guard() default Object.class; // cannot be null :(
Class <? extends Object> guard() default void.class;
/**
* Determines snippet order when multiple snippets are to be inlined
* at the same location. The smaller the number, the closer to the boundary
* of the marked code region will be the snippet inlined.
* <p>
* Defines ordering of the snippets. Smaller number indicates that snippet
* will be inlined closer to the instrumented code.
*
* <p>
* Default is 100.
* Default value: {@code 100}
*/
int order() default 100;
/**
* Controls automatic bypass activation. This is an advanced option that
* allows to turn off automatic bypass activation for inlined snippets. This
* can be used when a snippet does not use any other (instrumented) classes,
* or when manual control over bypass activation is desired.
* <p>
* You can in general disable dynamic bypass on snippets that are not using
* any other class. (Advanced option)
*
* <p>
* <b>note:</b> Usage of dynamic bypass is determined by the underlying
* NOTE: Usage of dynamic bypass is determined by the underlying
* instrumentation framework.
* <p>
* Default value: {@code true}, means "automatic bypass activation".
*/
boolean dynamicBypass() default true;
}
src-disl/ch/usi/dag/disl/annotation/AfterThrowing.java
View file @ 9add01a7
package ch.usi.dag.disl.annotation;
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Target;
import ch.usi.dag.disl.classcontext.ClassContext;
import ch.usi.dag.disl.dynamiccontext.DynamicContext;
import ch.usi.dag.disl.marker.Marker;
import ch.usi.dag.disl.processorcontext.ArgumentProcessorContext;
import ch.usi.dag.disl.staticcontext.StaticContext;
/**
* Marks a method as a DiSL snippet to be inserted after the marked code region.
* The snippet code will be executed after an exit cause by an exception.
* <p>
* The AfterThrowing annotation instructs DiSL to insert the snippet body after
* the marked region. The snippet will be invoked after an exit caused by an
* exception.
*
* <b>Note:</b> This is a general contract. The actual implementation depends on
* the particular marker used with the snippet.
* <p>
* <b>note:</b> This is only general contract. It depends on particular marker
* how the contract will be implemented.
*
* The annotation has the following parameters which control the inlining of a
* snippet into target code:
* <ul>
* <li>{@link #marker}
* <li>{@link #args}
* <li>{@link #guard}
* <li>{@link #scope}
* <li>{@link #order}
* <li>{@link #dynamicBypass}
* </ul>
* <p>
* <b>usage:</b>
*
* This annotation can be only used with methods. In particular, a method
* representing a snippet must be {@code static}, must not return any value, and
* must not throw any exceptions.
* <p>
* There are multiple optional parameters the annotation takes. Browse them for
* more details on usage.
* The method can declare parameters the following types:
* <ul>
* <li>{@link #marker}</li>
* <li>{@link #args}</li>
* <li>{@link #guard}</li>
* <li>{@link #scope}</li>
* <li>{@link #order}</li>
* <li>{@link #dynamicBypass}</li>
* <li>{@link StaticContext} (or another type implementing it),
* <li>{@link DynamicContext},
* <li>{@link ClassContext}, and
* <li>{@link ArgumentProcessorContext}.
* </ul>
*
* <p>
* This annotation should be used only with static methods that does not return
* any value or throw any exception.
*
* <p>
* The method might be specified with arguments of following types.
* {@link ch.usi.dag.disl.staticcontext.StaticContext StaticContext (or
* derived)}, {@link ch.usi.dag.disl.dynamiccontext.DynamicContext
* DynamicContext}, {@link ch.usi.dag.disl.classcontext.ClassContext
* ClassContext} and
* {@link ch.usi.dag.disl.processorcontext.ArgumentProcessorContext
* ArgumentProcessContext}. There's no restriction on order or number of these
* arguments.
* The ordering and the number of the parameters is arbitrary.
*/
@Documented
@Target (ElementType.METHOD)
public @interface AfterThrowing {
// NOTE if you want to change names, you need to change
// SnippetParser.SnippetAnnotationData class
// NOTE because of implementation of annotations in java the defaults
// are not retrieved from here but from class mentioned above
//
// NOTE
//
// If you change any names here, you also need to change them
// in the DiSL class parser. Only do that if absolutely necessary,
// because this annotation is part of the DiSL public API.
//
// Also note that the defaults are not retrieved from here, but
// are set in the DiSL class parser.
//
/**
* <p>
* Marker class defines a region where the snippet is applied.
*
* Selects the marker class. A marker determines the region of code within a
* method where to apply the snippet.
*
* @see ch.usi.dag.disl.marker.Marker Implementation details
*/
Class<? extends Marker> marker();
Class <? extends Marker> marker();
/**
* Optional argument for the marker class, passed as a {@link String}.
* <p>
* Argument for the marker (as string).
*
* <p>
* Default value means none.
* Default value: {@code ""}, means "no arguments".
*/
String args() default ""; // cannot be null :(
String args() default "";
/**
* Selects methods in which to apply the snippet.
* <p>
* Scope of the methods, where the snippet is applied.
*
* See the {@link ch.usi.dag.disl.scope} package for more information about
* the scoping language.
* <p>
* Default value means everything.
*
* @see ch.usi.dag.disl.scope.ScopeImpl Implementation details
* Default value: {@code "*"}, means "everywhere".
*/
String scope() default "*";
/**
* Selects the guard class. A guard class determines whether a snippet
* will be inlined at a particular location or not. In general, guards
* provide more fine-grained control compared to scopes.
* <p>
* The guard class defining if the snippet will be inlined in particular
* region or not.
*
* <p>
* Default value means none.
* Default value: {@code void.class}, means "no guard used".
*/
Class<? extends Object> guard() default Object.class; // cannot be null :(
Class <? extends Object> guard() default void.class;
/**
* Determines snippet order when multiple snippets are to be inlined
* at the same location. The smaller the number, the closer to the boundary
* of the marked code region will be the snippet inlined.
* <p>
* Defines ordering of the snippets. Smaller number indicates that snippet
* will be inlined closer to the instrumented code.
*
* <p>
* Default is 100.
* Default value: {@code 100}
*/
int order() default 100;
/**
* Controls automatic bypass activation. This is an advanced option that
* allows to turn off automatic bypass activation for inlined snippets. This
* can be used when a snippet does not use any other (instrumented) classes,
* or when manual control over bypass activation is desired.
* <p>
* You can in general disable dynamic bypass on snippets, that are not using
* any other class. (Advanced option)
*
* <p>
* <b>note:</b> Usage of dynamic bypass is determined by the underlying
* NOTE: Usage of dynamic bypass is determined by the underlying
* instrumentation framework.
* <p>
* Default value: {@code true}, means "automatic bypass activation".
*/
boolean dynamicBypass() default true;
}
src-disl/ch/usi/dag/disl/annotation/ArgumentProcessor.java
View file @ 9add01a7
package ch.usi.dag.disl.annotation;
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Target;
import ch.usi.dag.disl.classcontext.ClassContext;
import ch.usi.dag.disl.dynamiccontext.DynamicContext;
import ch.usi.dag.disl.processorcontext.ArgumentContext;
import ch.usi.dag.disl.staticcontext.StaticContext;
/**
* Annotated class defines method for processing method arguments. The specified
* methods will be inlined into snippets to process one method argument value.
* <br>
* <br>
* First argument of the method is a type, that will be processed by the method.
* The allowed types are all basic types, String and Object class. The processed
* type can be extend in some special cases by ProcessAlso annotation.
* During run-time, the argument will contain a processed method argument value.
* ArgumentContext can be used to fetch additional data about the argument.
* <br>
* <br>
* This annotation should be used with classes.
* <br>
* The method should be static, not return any values and not throw any
* exceptions.
* <br>
* Method argument can be StaticContext, DynamicContext, ClassContext and
* ArgumentContext.
* Indicates that the class contains methods for processing method arguments
* with corresponding types. Methods corresponding to argument types will be
* invoked with the type and value of the argument. The invocations of the
* argument processor methods will be inlined into each snippet that uses the
* argument processor.
* <p>
* An argument processor <b>method</b> has the argument type as its first
* parameter. Only primitive, {@link String}, and {@link Object} types are
* allowed. In some cases, the type accepted by the argument processor method
* can be extended using the {@link ProcessAlso} annotation. At runtime, the
* second parameter of the argument processor will contain the value of the
* argument being processed.
* <p>
* Additional information (e.g. position) about the argument can be obtained
* using the {@link ArgumentContext} interface. To use it, an argument processor
* method must have a parameter of type {@link ArgumentContext}. Other allowed
* contexts are {@link StaticContext}, {@link DynamicContext}, and
* {@link ClassContext}.
* <p>
* All argument processor methods must be static, may not return any values, and
* may not throw any exceptions.
*/