Class JobExtensions
Inheritance
JobExtensions
Assembly: BenchmarkDotNet.dll
Syntax
public static class JobExtensions
Methods
AsBaseline(Job)
Declaration
public static Job AsBaseline(this Job job)
Parameters
| Type |
Name |
Description |
| Job |
job |
|
Returns
AsDefault(Job, Boolean)
use it if you want to specify custom default settings for default job used by console arguments parser
Declaration
public static Job AsDefault(this Job job, bool value = true)
Parameters
Returns
AsMutator(Job)
mutator job should not be added to the config, but instead applied to other jobs in given config
Declaration
public static Job AsMutator(this Job job)
Parameters
| Type |
Name |
Description |
| Job |
job |
|
Returns
DontEnforcePowerPlan(Job)
ensures that BenchmarkDotNet does not enforce any power plan
Declaration
public static Job DontEnforcePowerPlan(this Job job)
Parameters
| Type |
Name |
Description |
| Job |
job |
|
Returns
RunOncePerIteration(Job)
Run the benchmark exactly once per iteration.
Declaration
public static Job RunOncePerIteration(this Job job)
Parameters
| Type |
Name |
Description |
| Job |
job |
|
Returns
WithAffinity(Job, IntPtr)
Declaration
public static Job WithAffinity(this Job job, IntPtr affinity)
Parameters
| Type |
Name |
Description |
| Job |
job |
|
| IntPtr |
affinity |
|
Returns
WithAnalyzeLaunchVariance(Job, Boolean)
Declaration
public static Job WithAnalyzeLaunchVariance(this Job job, bool value)
Parameters
Returns
WithArguments(Job, IReadOnlyList<Argument>)
Declaration
public static Job WithArguments(this Job job, IReadOnlyList<Argument> arguments)
Parameters
Returns
WithBaseline(Job, Boolean)
Declaration
public static Job WithBaseline(this Job job, bool value)
Parameters
Returns
WithClock(Job, IClock)
Declaration
public static Job WithClock(this Job job, IClock clock)
Parameters
| Type |
Name |
Description |
| Job |
job |
|
| IClock |
clock |
|
Returns
WithCustomBuildConfiguration(Job, String)
Declaration
public static Job WithCustomBuildConfiguration(this Job job, string buildConfiguration)
Parameters
| Type |
Name |
Description |
| Job |
job |
|
| String |
buildConfiguration |
|
Returns
WithEngineFactory(Job, IEngineFactory)
Declaration
public static Job WithEngineFactory(this Job job, IEngineFactory engineFactory)
Parameters
Returns
WithEnvironmentVariable(Job, EnvironmentVariable)
Creates a new job based on the given job with additional environment variable.
All existed environment variables of the original job will be copied to the new one.
If the original job already contains an environment variable with the same key, it will be overriden.
Declaration
public static Job WithEnvironmentVariable(this Job job, EnvironmentVariable environmentVariable)
Parameters
| Type |
Name |
Description |
| Job |
job |
The original job
|
| EnvironmentVariable |
environmentVariable |
The new environment variable which should be added for the new job
|
Returns
| Type |
Description |
| Job |
The new job with additional environment variable
|
WithEnvironmentVariable(Job, String, String)
Creates a new job based on the given job with additional environment variable.
All existed environment variables of the original job will be copied to the new one.
If the original job already contains an environment variable with the same key, it will be overriden.
Declaration
public static Job WithEnvironmentVariable(this Job job, string key, string value)
Parameters
| Type |
Name |
Description |
| Job |
job |
The original job
|
| String |
key |
The key of the new environment variable
|
| String |
value |
The value of the new environment variable
|
Returns
| Type |
Description |
| Job |
The new job with additional environment variable
|
WithEnvironmentVariables(Job, EnvironmentVariable[])
Creates a new job based on the given job with specified environment variables.
It overrides the whole list of environment variables which were defined in the original job.
Declaration
public static Job WithEnvironmentVariables(this Job job, params EnvironmentVariable[] environmentVariables)
Parameters
| Type |
Name |
Description |
| Job |
job |
The original job
|
| EnvironmentVariable[] |
environmentVariables |
The environment variables for the new job
|
Returns
| Type |
Description |
| Job |
The new job with overriden environment variables
|
Exceptions
| Type |
Condition |
| InvalidOperationException |
Throws an exception if environmentVariables contains two variables with the same key.
|
WithEvaluateOverhead(Job, Boolean)
Specifies if the overhead should be evaluated (Idle runs) and it's average value subtracted from every result.
True by default, very important for nano-benchmarks.
Declaration
public static Job WithEvaluateOverhead(this Job job, bool value)
Parameters
Returns
WithGcAllowVeryLargeObjects(Job, Boolean)
On 64-bit platforms, enables arrays that are greater than 2 gigabytes (GB) in total size.
false: Arrays greater than 2 GB in total size are not enabled. This is the default.
true: Arrays greater than 2 GB in total size are enabled on 64-bit platforms.
Declaration
public static Job WithGcAllowVeryLargeObjects(this Job job, bool value)
Parameters
Returns
WithGcConcurrent(Job, Boolean)
Specifies whether the common language runtime runs garbage collection on a separate thread.
false: Does not run garbage collection concurrently.
true: Runs garbage collection concurrently. This is the default.
Declaration
public static Job WithGcConcurrent(this Job job, bool value)
Parameters
Returns
WithGcCpuGroups(Job, Boolean)
Specifies whether garbage collection supports multiple CPU groups.
false: Garbage collection does not support multiple CPU groups. This is the default.
true: Garbage collection supports multiple CPU groups, if server garbage collection is enabled.
Declaration
public static Job WithGcCpuGroups(this Job job, bool value)
Parameters
Returns
WithGcForce(Job, Boolean)
Specifies whether the BenchmarkDotNet's benchmark runner forces full garbage collection after each benchmark invocation
false: Does not force garbage collection.
true: Forces full garbage collection after each benchmark invocation. This is the default.
Declaration
public static Job WithGcForce(this Job job, bool value)
Parameters
Returns
WithGcMode(Job, GcMode)
Declaration
public static Job WithGcMode(this Job job, GcMode gc)
Parameters
Returns
WithGcRetainVm(Job, Boolean)
Put segments that should be deleted on a standby list for future use instead of releasing them back to the OS
The default is false
Declaration
public static Job WithGcRetainVm(this Job job, bool value)
Parameters
Returns
WithGcServer(Job, Boolean)
Specifies whether the common language runtime runs server garbage collection.
false: Does not run server garbage collection. This is the default.
true: Runs server garbage collection.
Declaration
public static Job WithGcServer(this Job job, bool value)
Parameters
Returns
WithHeapAffinitizeMask(Job, Int32)
process mask, see MSDN for more.
Declaration
public static Job WithHeapAffinitizeMask(this Job job, int heapAffinitizeMask)
Parameters
| Type |
Name |
Description |
| Job |
job |
|
| Int32 |
heapAffinitizeMask |
|
Returns
WithHeapCount(Job, Int32)
specify the # of Server GC threads/heaps, must be smaller than the # of logical CPUs the process is allowed to run on,
ie, if you don't specifically affinitize your process it means the # of total logical CPUs on the machine;
otherwise this is the # of logical CPUs you affinitized your process to.
Declaration
public static Job WithHeapCount(this Job job, int heapCount)
Parameters
| Type |
Name |
Description |
| Job |
job |
|
| Int32 |
heapCount |
|
Returns
WithId(Job, String)
Declaration
public static Job WithId(this Job job, string id)
Parameters
Returns
WithInvocationCount(Job, Int32)
Invocation count in a single iteration.
If specified, IterationTime will be ignored.
If specified, it must be a multiple of UnrollFactor.
Declaration
public static Job WithInvocationCount(this Job job, int count)
Parameters
| Type |
Name |
Description |
| Job |
job |
|
| Int32 |
count |
|
Returns
WithIterationCount(Job, Int32)
Declaration
public static Job WithIterationCount(this Job job, int count)
Parameters
| Type |
Name |
Description |
| Job |
job |
|
| Int32 |
count |
|
Returns
WithIterationTime(Job, TimeInterval)
Desired time of execution of an iteration. Used by Pilot stage to estimate the number of invocations per iteration.
The default value is 500 milliseconds.
Declaration
public static Job WithIterationTime(this Job job, TimeInterval time)
Parameters
| Type |
Name |
Description |
| Job |
job |
|
| TimeInterval |
time |
|
Returns
WithJit(Job, Jit)
Declaration
public static Job WithJit(this Job job, Jit jit)
Parameters
| Type |
Name |
Description |
| Job |
job |
|
| Jit |
jit |
|
Returns
WithLaunchCount(Job, Int32)
How many times we should launch process with target benchmark.
Declaration
public static Job WithLaunchCount(this Job job, int count)
Parameters
| Type |
Name |
Description |
| Job |
job |
|
| Int32 |
count |
|
Returns
WithMaxAbsoluteError(Job, TimeInterval)
Maximum acceptable error for a benchmark (by default, BenchmarkDotNet continue iterations until the actual error is less than the specified error).
Doesn't have a default value.
If MaxRelativeError is also provided, the smallest value is used as stop criteria.
Declaration
public static Job WithMaxAbsoluteError(this Job job, TimeInterval interval)
Parameters
| Type |
Name |
Description |
| Job |
job |
|
| TimeInterval |
interval |
|
Returns
WithMaxIterationCount(Job, Int32)
Maximum count of target iterations that should be performed.
The default value is 100.
If you set this value to below 15, then MultimodalDistributionAnalyzer is not going to work.
Declaration
public static Job WithMaxIterationCount(this Job job, int count)
Parameters
| Type |
Name |
Description |
| Job |
job |
|
| Int32 |
count |
|
Returns
WithMaxRelativeError(Job, Double)
Maximum acceptable error for a benchmark (by default, BenchmarkDotNet continue iterations until the actual error is less than the specified error).
The default value is 0.02.
If MaxAbsoluteError is also provided, the smallest value is used as stop criteria.
Declaration
public static Job WithMaxRelativeError(this Job job, double value)
Parameters
Returns
WithMaxWarmupCount(Job, Int32)
Maximum count of warmup iterations that should be performed
The default value is 50
Declaration
public static Job WithMaxWarmupCount(this Job job, int count)
Parameters
| Type |
Name |
Description |
| Job |
job |
|
| Int32 |
count |
|
Returns
WithMemoryRandomization(Job, Boolean)
specifies whether Engine should allocate some random-sized memory between iterations
it makes [GlobalCleanup] and [GlobalSetup] methods to be executed after every iteration
Declaration
public static Job WithMemoryRandomization(this Job job, bool enable = true)
Parameters
Returns
WithMinInvokeCount(Job, Int32)
Minimum count of benchmark invocations per iteration
The default value is 4.
Declaration
public static Job WithMinInvokeCount(this Job job, int value)
Parameters
| Type |
Name |
Description |
| Job |
job |
|
| Int32 |
value |
|
Returns
WithMinIterationCount(Job, Int32)
Minimum count of target iterations that should be performed.
The default value is 15.
If you set this value to below 15, then MultimodalDistributionAnalyzer is not going to work.
Declaration
public static Job WithMinIterationCount(this Job job, int count)
Parameters
| Type |
Name |
Description |
| Job |
job |
|
| Int32 |
count |
|
Returns
WithMinIterationTime(Job, TimeInterval)
Minimum time of a single iteration. Unlike Run.IterationTime, this characteristic specifies only the lower limit. In case of need, BenchmarkDotNet can increase this value.
The default value is 500 milliseconds.
Declaration
public static Job WithMinIterationTime(this Job job, TimeInterval interval)
Parameters
| Type |
Name |
Description |
| Job |
job |
|
| TimeInterval |
interval |
|
Returns
WithMinWarmupCount(Job, Int32)
Minimum count of warmup iterations that should be performed
The default value is 6
Declaration
public static Job WithMinWarmupCount(this Job job, int count)
Parameters
| Type |
Name |
Description |
| Job |
job |
|
| Int32 |
count |
|
Returns
WithNoAffinitize(Job, Boolean)
specify true to disable hard affinity of Server GC threads to CPUs
Declaration
public static Job WithNoAffinitize(this Job job, bool value)
Parameters
Returns
WithNuGet(Job, NuGetReferenceList)
Runs the job with a specific NuGet dependencies which will be resolved during the Job build process
Declaration
public static Job WithNuGet(this Job job, NuGetReferenceList nuGetReferences)
Parameters
Returns
WithNuGet(Job, String, String, Uri, Boolean)
Runs the job with a specific NuGet dependency which will be resolved during the Job build process
Declaration
public static Job WithNuGet(this Job job, string packageName, string packageVersion = null, Uri source = null, bool prerelease = false)
Parameters
| Type |
Name |
Description |
| Job |
job |
|
| String |
packageName |
The NuGet package name
|
| String |
packageVersion |
(optional)The NuGet package version
|
| Uri |
source |
(optional)Indicate the URI of the NuGet package source to use during the restore operation.
|
| Boolean |
prerelease |
(optional)Allows prerelease packages to be installed.
|
Returns
WithoutEnvironmentVariables(Job)
Creates a new job based on the given job without any environment variables.
Declaration
public static Job WithoutEnvironmentVariables(this Job job)
Parameters
| Type |
Name |
Description |
| Job |
job |
The original job
|
Returns
| Type |
Description |
| Job |
The new job which doesn't have any environment variables
|
WithOutlierMode(Job, OutlierMode)
Specifies which outliers should be removed from the distribution
Declaration
public static Job WithOutlierMode(this Job job, OutlierMode value)
Parameters
| Type |
Name |
Description |
| Job |
job |
|
| OutlierMode |
value |
|
Returns
Declaration
public static Job WithPlatform(this Job job, Platform platform)
Parameters
Returns
WithPowerPlan(Job, PowerPlan)
Power plan for benchmarks.
The default value is HighPerformance.
Only available for Windows.
Declaration
public static Job WithPowerPlan(this Job job, PowerPlan powerPlan)
Parameters
Returns
WithPowerPlan(Job, Guid)
Setting power plans by guid.
The default value is HighPerformance.
Only available for Windows.
Declaration
public static Job WithPowerPlan(this Job job, Guid powerPlanGuid)
Parameters
| Type |
Name |
Description |
| Job |
job |
|
| Guid |
powerPlanGuid |
|
Returns
WithRuntime(Job, Runtime)
Declaration
public static Job WithRuntime(this Job job, Runtime runtime)
Parameters
Returns
WithStrategy(Job, RunStrategy)
Available values: Throughput, ColdStart and Monitoring.
Throughput: default strategy which allows to get good precision level.
ColdStart: should be used only for measuring cold start of the application or testing purpose.
Monitoring: no overhead evaluating, with several target iterations. Perfect for macrobenchmarks without a steady state with high variance.
Declaration
public static Job WithStrategy(this Job job, RunStrategy strategy)
Parameters
Returns
Declaration
public static Job WithToolchain(this Job job, IToolchain toolchain)
Parameters
Returns
WithUnrollFactor(Job, Int32)
How many times the benchmark method will be invoked per one iteration of a generated loop.
The default value is 16.
Declaration
public static Job WithUnrollFactor(this Job job, int factor)
Parameters
| Type |
Name |
Description |
| Job |
job |
|
| Int32 |
factor |
|
Returns
WithWarmupCount(Job, Int32)
How many warmup iterations should be performed.
Declaration
public static Job WithWarmupCount(this Job job, int count)
Parameters
| Type |
Name |
Description |
| Job |
job |
|
| Int32 |
count |
|
Returns