Table of Contents

Class JobExtensions

Namespace
BenchmarkDotNet.Jobs
Assembly
BenchmarkDotNet.dll
public static class JobExtensions
Inheritance
JobExtensions

Methods

AsBaseline(Job) 

public static Job AsBaseline(this Job job)

Parameters

job Job

Returns

Job

AsDefault(Job, bool)

use it if you want to specify custom default settings for default job used by console arguments parser

public static Job AsDefault(this Job job, bool value = true)

Parameters

job Job
value bool

Returns

Job

AsMutator(Job)

mutator job should not be added to the config, but instead applied to other jobs in given config

public static Job AsMutator(this Job job)

Parameters

job Job

Returns

Job

DontEnforcePowerPlan(Job)

ensures that BenchmarkDotNet does not enforce any power plan

public static Job DontEnforcePowerPlan(this Job job)

Parameters

job Job

Returns

Job

RunOncePerIteration(Job)

Run the benchmark exactly once per iteration.

public static Job RunOncePerIteration(this Job job)

Parameters

job Job

Returns

Job

WithAffinity(Job, nint)

ProcessorAffinity for the benchmark process. See also: https://msdn.microsoft.com/library/system.diagnostics.process.processoraffinity.aspx

public static Job WithAffinity(this Job job, nint affinity)

Parameters

job Job
affinity nint

Returns

Job

WithAnalyzeLaunchVariance(Job, bool) 

public static Job WithAnalyzeLaunchVariance(this Job job, bool value)

Parameters

job Job
value bool

Returns

Job

WithArguments(Job, IReadOnlyList<Argument>) 

public static Job WithArguments(this Job job, IReadOnlyList<Argument> arguments)

Parameters

job Job
arguments IReadOnlyList<Argument>

Returns

Job

WithBaseline(Job, bool) 

public static Job WithBaseline(this Job job, bool value)

Parameters

job Job
value bool

Returns

Job

WithClock(Job, IClock) 

public static Job WithClock(this Job job, IClock clock)

Parameters

job Job
clock IClock

Returns

Job

WithCustomBuildConfiguration(Job, string) 

public static Job WithCustomBuildConfiguration(this Job job, string buildConfiguration)

Parameters

job Job
buildConfiguration string

Returns

Job

WithEngineFactory(Job, IEngineFactory) 

public static Job WithEngineFactory(this Job job, IEngineFactory engineFactory)

Parameters

job Job
engineFactory IEngineFactory

Returns

Job

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.

public static Job WithEnvironmentVariable(this Job job, EnvironmentVariable environmentVariable)

Parameters

job Job

The original job

environmentVariable EnvironmentVariable

The new environment variable which should be added for the new job

Returns

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.

public static Job WithEnvironmentVariable(this Job job, string key, string value)

Parameters

job Job

The original job

key string

The key of the new environment variable

value string

The value of the new environment variable

Returns

Job

The new job with additional environment variable

WithEnvironmentVariables(Job, params 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.

public static Job WithEnvironmentVariables(this Job job, params EnvironmentVariable[] environmentVariables)

Parameters

job Job

The original job

environmentVariables EnvironmentVariable[]

The environment variables for the new job

Returns

Job

The new job with overriden environment variables

Exceptions

InvalidOperationException

Throws an exception if environmentVariables contains two variables with the same key.

WithEvaluateOverhead(Job, bool)

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.

public static Job WithEvaluateOverhead(this Job job, bool value)

Parameters

job Job
value bool

Returns

Job

WithGcAllowVeryLargeObjects(Job, bool)

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.

public static Job WithGcAllowVeryLargeObjects(this Job job, bool value)

Parameters

job Job
value bool

Returns

Job

WithGcConcurrent(Job, bool)

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.

public static Job WithGcConcurrent(this Job job, bool value)

Parameters

job Job
value bool

Returns

Job

WithGcCpuGroups(Job, bool)

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.

public static Job WithGcCpuGroups(this Job job, bool value)

Parameters

job Job
value bool

Returns

Job

WithGcForce(Job, bool)

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.

public static Job WithGcForce(this Job job, bool value)

Parameters

job Job
value bool

Returns

Job

WithGcMode(Job, GcMode) 

public static Job WithGcMode(this Job job, GcMode gc)

Parameters

job Job
gc GcMode

Returns

Job

WithGcRetainVm(Job, bool)

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

public static Job WithGcRetainVm(this Job job, bool value)

Parameters

job Job
value bool

Returns

Job

WithGcServer(Job, bool)

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.

public static Job WithGcServer(this Job job, bool value)

Parameters

job Job
value bool

Returns

Job

WithHeapAffinitizeMask(Job, int)

process mask, see MSDN for more.

public static Job WithHeapAffinitizeMask(this Job job, int heapAffinitizeMask)

Parameters

job Job
heapAffinitizeMask int

Returns

Job

WithHeapCount(Job, int)

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.

public static Job WithHeapCount(this Job job, int heapCount)

Parameters

job Job
heapCount int

Returns

Job

WithId(Job, string) 

public static Job WithId(this Job job, string id)

Parameters

job Job
id string

Returns

Job

WithInvocationCount(Job, long)

Invocation count in a single iteration. If specified, IterationTime will be ignored. If specified, it must be a multiple of UnrollFactor.

public static Job WithInvocationCount(this Job job, long count)

Parameters

job Job
count long

Returns

Job

WithIterationCount(Job, int)

How many target iterations should be performed. If specified, MinIterationCount will be ignored. If specified, MaxIterationCount will be ignored.

public static Job WithIterationCount(this Job job, int count)

Parameters

job Job
count int

Returns

Job

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.

public static Job WithIterationTime(this Job job, TimeInterval time)

Parameters

job Job
time TimeInterval

Returns

Job

WithJit(Job, Jit) 

public static Job WithJit(this Job job, Jit jit)

Parameters

job Job
jit Jit

Returns

Job

WithLargeAddressAware(Job, bool)

Specifies that benchmark can handle addresses larger than 2 gigabytes.

public static Job WithLargeAddressAware(this Job job, bool value = true)

Parameters

job Job
value bool

Returns

Job

WithLaunchCount(Job, int)

How many times we should launch process with target benchmark.

public static Job WithLaunchCount(this Job job, int count)

Parameters

job Job
count int

Returns

Job

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.

public static Job WithMaxAbsoluteError(this Job job, TimeInterval interval)

Parameters

job Job
interval TimeInterval

Returns

Job

WithMaxIterationCount(Job, int)

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.

public static Job WithMaxIterationCount(this Job job, int count)

Parameters

job Job
count int

Returns

Job

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.

public static Job WithMaxRelativeError(this Job job, double value)

Parameters

job Job
value double

Returns

Job

WithMaxWarmupCount(Job, int)

Maximum count of warmup iterations that should be performed The default value is 50

public static Job WithMaxWarmupCount(this Job job, int count)

Parameters

job Job
count int

Returns

Job

WithMemoryRandomization(Job, bool)

specifies whether Engine should allocate some random-sized memory between iterations it makes [GlobalCleanup] and [GlobalSetup] methods to be executed after every iteration

public static Job WithMemoryRandomization(this Job job, bool enable = true)

Parameters

job Job
enable bool

Returns

Job

WithMinInvokeCount(Job, int)

Minimum count of benchmark invocations per iteration The default value is 4.

public static Job WithMinInvokeCount(this Job job, int value)

Parameters

job Job
value int

Returns

Job

WithMinIterationCount(Job, int)

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.

public static Job WithMinIterationCount(this Job job, int count)

Parameters

job Job
count int

Returns

Job

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.

public static Job WithMinIterationTime(this Job job, TimeInterval interval)

Parameters

job Job
interval TimeInterval

Returns

Job

WithMinWarmupCount(Job, int)

Minimum count of warmup iterations that should be performed The default value is 6

public static Job WithMinWarmupCount(this Job job, int count)

Parameters

job Job
count int

Returns

Job

WithNoAffinitize(Job, bool)

specify true to disable hard affinity of Server GC threads to CPUs

public static Job WithNoAffinitize(this Job job, bool value)

Parameters

job Job
value bool

Returns

Job

WithNuGet(Job, NuGetReferenceList)

Runs the job with a specific NuGet dependencies which will be resolved during the Job build process

public static Job WithNuGet(this Job job, NuGetReferenceList nuGetReferences)

Parameters

job Job
nuGetReferences NuGetReferenceList

A collection of NuGet dependencies

Returns

Job

WithNuGet(Job, string, string?, Uri?, bool)

Runs the job with a specific NuGet dependency which will be resolved during the Job build process

public static Job WithNuGet(this Job job, string packageName, string? packageVersion = null, Uri? source = null, bool prerelease = false)

Parameters

job Job
packageName string

The NuGet package name

packageVersion string

(optional)The NuGet package version

source Uri

(optional)Indicate the URI of the NuGet package source to use during the restore operation.

prerelease bool

(optional)Allows prerelease packages to be installed.

Returns

Job

WithOutlierMode(Job, OutlierMode)

Specifies which outliers should be removed from the distribution

public static Job WithOutlierMode(this Job job, OutlierMode value)

Parameters

job Job
value OutlierMode

Returns

Job

WithPlatform(Job, Platform) 

public static Job WithPlatform(this Job job, Platform platform)

Parameters

job Job
platform Platform

Returns

Job

WithPowerPlan(Job, PowerPlan)

Power plan for benchmarks. The default value is HighPerformance. Only available for Windows.

public static Job WithPowerPlan(this Job job, PowerPlan powerPlan)

Parameters

job Job
powerPlan PowerPlan

Returns

Job

WithPowerPlan(Job, Guid)

Setting power plans by guid. The default value is HighPerformance. Only available for Windows.

public static Job WithPowerPlan(this Job job, Guid powerPlanGuid)

Parameters

job Job
powerPlanGuid Guid

Returns

Job

WithRuntime(Job, Runtime) 

public static Job WithRuntime(this Job job, Runtime runtime)

Parameters

job Job
runtime Runtime

Returns

Job

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.

public static Job WithStrategy(this Job job, RunStrategy strategy)

Parameters

job Job
strategy RunStrategy

Returns

Job

WithToolchain(Job, IToolchain) 

public static Job WithToolchain(this Job job, IToolchain toolchain)

Parameters

job Job
toolchain IToolchain

Returns

Job

WithUnrollFactor(Job, int)

How many times the benchmark method will be invoked per one iteration of a generated loop. The default value is 16.

public static Job WithUnrollFactor(this Job job, int factor)

Parameters

job Job
factor int

Returns

Job

WithWarmupCount(Job, int)

How many warmup iterations should be performed.

public static Job WithWarmupCount(this Job job, int count)

Parameters

job Job
count int

Returns

Job

WithoutEnvironmentVariables(Job)

Creates a new job based on the given job without any environment variables.

public static Job WithoutEnvironmentVariables(this Job job)

Parameters

job Job

The original job

Returns

Job

The new job which doesn't have any environment variables