Show / Hide Table of Contents

Class JobExtensions

Inheritance
Object
JobExtensions
Namespace: BenchmarkDotNet.Jobs
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
Type Description
Job

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
Type Name Description
Job job
Boolean value
Returns
Type Description
Job

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
Type Description
Job

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
Type Description
Job

RunOncePerIteration(Job)

Run the benchmark exactly once per iteration.

Declaration
public static Job RunOncePerIteration(this Job job)
Parameters
Type Name Description
Job job
Returns
Type Description
Job

WithAffinity(Job, IntPtr)

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

Declaration
public static Job WithAffinity(this Job job, IntPtr affinity)
Parameters
Type Name Description
Job job
IntPtr affinity
Returns
Type Description
Job

WithAnalyzeLaunchVariance(Job, Boolean)

Declaration
public static Job WithAnalyzeLaunchVariance(this Job job, bool value)
Parameters
Type Name Description
Job job
Boolean value
Returns
Type Description
Job

WithArguments(Job, IReadOnlyList<Argument>)

Declaration
public static Job WithArguments(this Job job, IReadOnlyList<Argument> arguments)
Parameters
Type Name Description
Job job
IReadOnlyList<Argument> arguments
Returns
Type Description
Job

WithBaseline(Job, Boolean)

Declaration
public static Job WithBaseline(this Job job, bool value)
Parameters
Type Name Description
Job job
Boolean value
Returns
Type Description
Job

WithClock(Job, IClock)

Declaration
public static Job WithClock(this Job job, IClock clock)
Parameters
Type Name Description
Job job
IClock clock
Returns
Type Description
Job

WithCustomBuildConfiguration(Job, String)

Declaration
public static Job WithCustomBuildConfiguration(this Job job, string buildConfiguration)
Parameters
Type Name Description
Job job
String buildConfiguration
Returns
Type Description
Job

WithEngineFactory(Job, IEngineFactory)

Declaration
public static Job WithEngineFactory(this Job job, IEngineFactory engineFactory)
Parameters
Type Name Description
Job job
IEngineFactory engineFactory
Returns
Type Description
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.

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
Type Name Description
Job job
Boolean value
Returns
Type Description
Job

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
Type Name Description
Job job
Boolean value
Returns
Type Description
Job

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
Type Name Description
Job job
Boolean value
Returns
Type Description
Job

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
Type Name Description
Job job
Boolean value
Returns
Type Description
Job

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
Type Name Description
Job job
Boolean value
Returns
Type Description
Job

WithGcMode(Job, GcMode)

Declaration
public static Job WithGcMode(this Job job, GcMode gc)
Parameters
Type Name Description
Job job
GcMode gc
Returns
Type Description
Job

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
Type Name Description
Job job
Boolean value
Returns
Type Description
Job

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
Type Name Description
Job job
Boolean value
Returns
Type Description
Job

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
Type Description
Job

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
Type Description
Job

WithId(Job, String)

Declaration
public static Job WithId(this Job job, string id)
Parameters
Type Name Description
Job job
String id
Returns
Type Description
Job

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
Type Description
Job

WithIterationCount(Job, Int32)

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

Declaration
public static Job WithIterationCount(this Job job, int count)
Parameters
Type Name Description
Job job
Int32 count
Returns
Type Description
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.

Declaration
public static Job WithIterationTime(this Job job, TimeInterval time)
Parameters
Type Name Description
Job job
TimeInterval time
Returns
Type Description
Job

WithJit(Job, Jit)

Declaration
public static Job WithJit(this Job job, Jit jit)
Parameters
Type Name Description
Job job
Jit jit
Returns
Type Description
Job

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
Type Description
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.

Declaration
public static Job WithMaxAbsoluteError(this Job job, TimeInterval interval)
Parameters
Type Name Description
Job job
TimeInterval interval
Returns
Type Description
Job

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
Type Description
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.

Declaration
public static Job WithMaxRelativeError(this Job job, double value)
Parameters
Type Name Description
Job job
Double value
Returns
Type Description
Job

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
Type Description
Job

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
Type Name Description
Job job
Boolean enable
Returns
Type Description
Job

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
Type Description
Job

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
Type Description
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.

Declaration
public static Job WithMinIterationTime(this Job job, TimeInterval interval)
Parameters
Type Name Description
Job job
TimeInterval interval
Returns
Type Description
Job

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
Type Description
Job

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
Type Name Description
Job job
Boolean value
Returns
Type Description
Job

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
Type Name Description
Job job
NuGetReferenceList nuGetReferences

A collection of NuGet dependencies

Returns
Type Description
Job

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
Type Description
Job

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
Type Description
Job

WithPlatform(Job, Platform)

Declaration
public static Job WithPlatform(this Job job, Platform platform)
Parameters
Type Name Description
Job job
Platform platform
Returns
Type Description
Job

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
Type Name Description
Job job
PowerPlan powerPlan
Returns
Type Description
Job

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
Type Description
Job

WithRuntime(Job, Runtime)

Declaration
public static Job WithRuntime(this Job job, Runtime runtime)
Parameters
Type Name Description
Job job
Runtime runtime
Returns
Type Description
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.

Declaration
public static Job WithStrategy(this Job job, RunStrategy strategy)
Parameters
Type Name Description
Job job
RunStrategy strategy
Returns
Type Description
Job

WithToolchain(Job, IToolchain)

Declaration
public static Job WithToolchain(this Job job, IToolchain toolchain)
Parameters
Type Name Description
Job job
IToolchain toolchain
Returns
Type Description
Job

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
Type Description
Job

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
Type Description
Job
In This Article
Back to top Copyright © 2013–2021 .NET Foundation and contributors