com.couchbase.client.core.env.TimerConfig Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of core-io Show documentation
The official Couchbase JVM Core IO Library
There is a newer version: 3.7.2
/*
 * Copyright (c) 2023 Couchbase, Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *    http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package com.couchbase.client.core.env;

import com.couchbase.client.core.annotation.Stability;

import java.time.Duration;
import java.util.LinkedHashMap;
import java.util.Map;

/**
 * Configures the internal Timer, which asynchronous retries and timeouts fire on.
 * 
 * Most users will have no reason to adjust these settings.  It is intended for situations
 * where testing has shown that the default settings are unable to, for example, fire high-throughput
 * timeouts or retries quickly enough or with accurate enough timing precision.
 */
@Stability.Volatile
public class TimerConfig {
  public static final int DEFAULT_NUM_TIMERS = 1;
  public static final Duration DEFAULT_TICK_DURATION = Duration.ofMillis(10);
  public static final int DEFAULT_NUM_BUCKETS = 512;

  private final int numTimers;
  private final Duration tickDuration;
  private final int numBuckets;

  private TimerConfig(Builder builder) {
    numTimers = builder.numTimers;
    tickDuration = builder.tickDuration;
    numBuckets = builder.numBuckets;
  }

  public static TimerConfig create() {
    return builder().build();
  }

  public static Builder builder() {
    return new Builder();
  }
  public int numTimers() {
    return numTimers;
  }

  public Duration tickDuration() {
    return tickDuration;
  }

  public int numBuckets() {
    return numBuckets;
  }

  @Stability.Internal
  public Map exportAsMap() {
    Map export = new LinkedHashMap<>();
    export.put("numTimers", numTimers);
    export.put("tickDurationMs", tickDuration.toMillis());
    export.put("numBuckets", numBuckets);
    return export;
  }

  public static class Builder {
    private int numTimers = DEFAULT_NUM_TIMERS;
    private Duration tickDuration = DEFAULT_TICK_DURATION;
    private int numBuckets = DEFAULT_NUM_BUCKETS;

    /**
     * Configures multiple parallel Timers, allowing more throughput of retries and timeouts.
     * 

     * It defaults to 1.
     */
    @Stability.Volatile
    public Builder numTimers(int numTimers) {
      this.numTimers = numTimers;
      return this;
    }

    /**
     * Configures the time between each 'tick' of the Timer(s).
     * 

     * Timeouts and retries can only fire as accurately as this resolution.  If reducing the value,
     * users may want to increase the {@link #numBuckets(int)} setting.
     * 

     * It defaults to 10 milliseconds.
     */
    @Stability.Volatile
    public Builder tickDuration(Duration tickDuration) {
      this.tickDuration = tickDuration;
      return this;
    }

    /**
     * Internally, each Timer divides time into a number of buckets, which this setting controls.
     * 

     * It defaults to 512.
     * 
     * If it's expected that many timeouts or retries will be firing, users may want to increase
     * this setting.
     */
    @Stability.Volatile
    public Builder numBuckets(int numBuckets) {
      this.numBuckets = numBuckets;
      return this;
    }

    public TimerConfig build() {
      return new TimerConfig(this);
    }
  }
}