Skip to content

Commit f9830cc

Browse files
wldehAbduqodiri Qurbonzoda
wldeh
and
Abduqodiri Qurbonzoda
authored
Improve configuration-options.md (#138)
Co-authored-by: Abduqodiri Qurbonzoda <[email protected]>
1 parent cad3dfb commit f9830cc

File tree

2 files changed

+70
-25
lines changed

2 files changed

+70
-25
lines changed

‎README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -289,4 +289,4 @@ To help you better understand how to use the kotlinx-benchmark library, we've pr
289289
290290
## Contributing
291291
292-
We welcome contributions to kotlinx-benchmark! If you want to contribute, please refer to our Contribution Guidelines.
292+
We welcome contributions to kotlinx-benchmark! If you want to contribute, please refer to our Contribution Guidelines.

‎docs/configuration-options.md

Lines changed: 69 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,78 @@
11
# Mastering kotlinx-benchmark Configuration
22

3-
Unleash the power of `kotlinx-benchmark` with our comprehensive guide, highlighting the breadth of configuration options that help fine-tune your benchmarking setup to suit your specific needs. Dive into the heart of the configuration process with both basic and advanced settings, offering a granular level of control to realize accurate, reliable performance measurements every time.
3+
This is a comprehensive guide to configuration options that help fine-tune your benchmarking setup to suit your specific needs.
44

5-
## Core Configuration Options: The Essential Settings
5+
## The `configurations` Section
66

7-
The `configurations` section of the `benchmark` block is where you control the parameters of your benchmark profiles. Each configuration offers a rich array of settings. Be aware that values defined in the build script will override those specified by annotations in the code.
7+
The `configurations` section of the `benchmark` block serves as the control center for setting the parameters of your benchmark profiles. The library provides a default configuration profile named "main", which can be configured according to your needs just like any other profile. Here's a basic structure of how configurations can be set up:
88

9-
| Option | Description | Possible Values | Corresponding Annotation |
10-
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------ | ------------------------ |
11-
| `iterations` | Sets the number of iterations for measurements. | Integer | @BenchmarkMode |
12-
| `warmups` | Sets the number of iterations for system warming, ensuring accurate measurements. | Integer | @Warmup |
13-
| `iterationTime` | Sets the duration for each iteration, both measurement and warm-up. | Integer | @Measurement |
14-
| `iterationTimeUnit` | Defines the unit for `iterationTime`. | "ns", "μs", "ms", "s", "m", "h", "d" | @Measurement |
15-
| `outputTimeUnit` | Sets the unit for the results display. | "ns", "μs", "ms", "s", "m", "h", "d" | @OutputTimeUnit |
16-
| `mode` | Selects "thrpt" for measuring the number of function calls per unit time or "avgt" for measuring the time per function call. | "thrpt", "avgt" | @BenchmarkMode |
17-
| `include("…")` | Applies a regular expression to include benchmarks that match the substring in their fully qualified names. | Regex pattern | - |
18-
| `exclude("…")` | Applies a regular expression to exclude benchmarks that match the substring in their fully qualified names. | Regex pattern | - |
19-
| `param("name", "value1", "value2")` | Assigns values to a public mutable property, annotated with `@Param`. | Any string values | @Param |
20-
| `reportFormat` | Defines the benchmark report's format options. | "json", "csv", "scsv", "text" | - |
9+
```kotlin
10+
// build.gradle.kts
11+
benchmark {
12+
configurations {
13+
register("smoke") {
14+
// Configure this configuration profile here
15+
}
16+
// here you can create additional profiles
17+
}
18+
}
19+
```
2120

22-
## Expert Configuration Options: The Power Settings
21+
## Understanding Configuration Profiles
2322

24-
The power of kotlinx-benchmark extends beyond basic settings. Delve into platform-specific options for tighter control over your benchmarks:
23+
Configuration profiles dictate the execution pattern of benchmarks:
2524

26-
| Option | Platform | Description | Possible Values | Corresponding Annotation |
27-
| --------------------------------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | ------------------------ |
28-
| `advanced("nativeFork", "value")` | Kotlin/Native | Executes iterations within the same process ("perBenchmark") or each iteration in a separate process ("perIteration"). | "perBenchmark", "perIteration" | - |
29-
| `advanced("nativeGCAfterIteration", "value")` | Kotlin/Native | Triggers garbage collection after each iteration when set to `true`. | `true`, `false` | - |
30-
| `advanced("jvmForks", "value")` | Kotlin/JVM | Determines how many times the harness should fork. | "0" (no fork), "1", "definedByJmh" (JMH decides) | @Fork |
31-
| `advanced("jsUseBridge", "value")` | Kotlin/JS, Kotlin/Wasm | Disables the generation of benchmark bridges to stop inlining optimizations when set to `false`. | `true`, `false` | - |
25+
- Utilize `include` and `exclude` options to select specific benchmarks for a profile.
26+
- By default, every benchmark is included.
27+
- Each configuration profile translates to a task in the `kotlinx-benchmark` Gradle plugin. For instance, the task `smokeBenchmark` is tailored to run benchmarks based on the `"smoke"` configuration profile. For an overview of tasks, refer to [tasks-overview.md](tasks-overview.md).
3228

33-
With this guide at your side, you're ready to optimize your benchmarking process with `kotlinx-benchmark`. Happy benchmarking!
29+
## Core Configuration Options
30+
31+
Note that values defined in the build script take precedence over those specified by annotations in the code.
32+
33+
| Option | Description | Possible Values | Corresponding Annotation |
34+
| ----------------------------------- |------------------------------------------------------------------------------------------------------------------------------|-------------------------------|-----------------------------------------------------|
35+
| `iterations` | Sets the number of iterations for measurements. | Integer | @Measurement(iterations: Int, ...) |
36+
| `warmups` | Sets the number of iterations for system warming, ensuring accurate measurements. | Integer | @Warmup(iterations: Int) |
37+
| `iterationTime` | Sets the duration for each iteration, both measurement and warm-up. | Integer | @Measurement(..., time: Int, ...) |
38+
| `iterationTimeUnit` | Defines the unit for `iterationTime`. | Time unit, see below | @Measurement(..., timeUnit: BenchmarkTimeUnit, ...) |
39+
| `outputTimeUnit` | Sets the unit for the results display. | Time unit, see below | @OutputTimeUnit(value: BenchmarkTimeUnit) |
40+
| `mode` | Selects "thrpt" (Throughput) for measuring the number of function calls per unit time or "avgt" (AverageTime) for measuring the time per function call. | `thrpt`(default), `Throughput`(default), `avgt`, `AverageTime` | @BenchmarkMode |
41+
| `include("…")` | Applies a regular expression to include benchmarks that match the substring in their fully qualified names. | Regex pattern | - |
42+
| `exclude("…")` | Applies a regular expression to exclude benchmarks that match the substring in their fully qualified names. | Regex pattern | - |
43+
| `param("name", "value1", "value2")` | Assigns values to a public mutable property with the specified name, annotated with `@Param`. | Any string values | @Param |
44+
| `reportFormat` | Defines the benchmark report's format options. | `json`(default), `csv`, `scsv`, `text` | - |
45+
46+
The following values can be used for specifying time unit:
47+
- "NANOSECONDS", "ns", "nanos"
48+
- "MICROSECONDS", "us", "micros"
49+
- "MILLISECONDS", "ms", "millis"
50+
- "SECONDS", "s", "sec"
51+
- "MINUTES", "m", "min"
52+
53+
## Platform-Specific Configuration Options
54+
55+
The options listed in the following sections allow you to tailor the benchmark execution behavior for specific platforms:
56+
57+
### Kotlin/Native
58+
| Option | Description | Possible Values | Default Value |
59+
|-----------------------------------------------|------------------------------------------------------------------------------------------------------------------------|--------------------------------|----------------|
60+
| `advanced("nativeFork", "value")` | Executes iterations within the same process ("perBenchmark") or each iteration in a separate process ("perIteration"). | `perBenchmark`, `perIteration` | "perBenchmark" |
61+
| `advanced("nativeGCAfterIteration", value)` | Whether to trigger garbage collection after each iteration. | `true`, `false` | `false` |
62+
63+
### Kotlin/JVM
64+
| Option | Description | Possible Values | Default Value |
65+
|---------------------------------------------|------------------------------------------------------------|--------------------------------|----------------|
66+
| `advanced("jvmForks", value)` | Specifies the number of times the harness should fork. | Integer, "definedByJmh" | `1` |
67+
68+
**Notes on "jvmForks":**
69+
- **0** - "no fork", i.e., no subprocesses are forked to run benchmarks.
70+
- A positive integer value – the amount used for all benchmarks in this configuration.
71+
- **"definedByJmh"** – Let JMH determine the amount, using the value in the [`@Fork` annotation](https://javadoc.io/static/org.openjdk.jmh/jmh-core/1.21/org/openjdk/jmh/annotations/Fork.html) for the benchmark function or its enclosing class. If not specified by `@Fork`, it defaults to [Defaults.MEASUREMENT_FORKS (`5`)](https://javadoc.io/static/org.openjdk.jmh/jmh-core/1.21/org/openjdk/jmh/runner/Defaults.html#MEASUREMENT_FORKS).
72+
73+
### Kotlin/JS & Kotlin/Wasm
74+
| Option | Description | Possible Values | Default Value |
75+
|-----------------------------------------------|-------------------------------------------------------------------------------------------------------|-----------------|---------------|
76+
| `advanced("jsUseBridge", value)` | Generate special benchmark bridges to stop inlining optimizations. | `true`, `false` | `true` |
77+
78+
**Note:** "jsUseBridge" works only when the `BuiltIn` benchmark executor is selected.

0 commit comments

Comments
 (0)