com.swirlds.common.wiring.schedulers.builders.TaskSchedulerBuilder Maven / Gradle / Ivy
Show all versions of swirlds-common Show documentation
/*
* Copyright (C) 2023-2024 Hedera Hashgraph, LLC
*
* 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.swirlds.common.wiring.schedulers.builders;
import com.swirlds.common.wiring.counters.ObjectCounter;
import com.swirlds.common.wiring.schedulers.TaskScheduler;
import edu.umd.cs.findbugs.annotations.NonNull;
import edu.umd.cs.findbugs.annotations.Nullable;
import java.lang.Thread.UncaughtExceptionHandler;
import java.time.Duration;
import java.util.concurrent.ForkJoinPool;
/**
* A builder for {@link TaskScheduler}s.
*
* @param the output type of the primary output wire for this task scheduler (use {@link Void} for a scheduler
* with no output)
*/
public interface TaskSchedulerBuilder {
long UNLIMITED_CAPACITY = -1;
/**
* Configure this task scheduler with values from settings.
*
* @param configuration the configuration
* @return this
*/
@NonNull
TaskSchedulerBuilder configure(@NonNull TaskSchedulerConfiguration configuration);
/**
* Set the type of task scheduler to build. Alters the semantics of the scheduler (i.e. this is not just an internal
* implementation detail).
*
* @param type the type of task scheduler to build
* @return this
*/
@NonNull
TaskSchedulerBuilder withType(@NonNull TaskSchedulerType type);
/**
* Set the maximum number of permitted scheduled tasks. Default is 1.
*
* @param unhandledTaskCapacity the maximum number of permitted unhandled tasks
* @return this
*/
@NonNull
TaskSchedulerBuilder withUnhandledTaskCapacity(long unhandledTaskCapacity);
/**
* Set whether the task scheduler should enable flushing. Default false. Flushing a scheduler with this disabled
* will cause the scheduler to throw an exception. Enabling flushing may add overhead.
*
* @param requireFlushCapability true if the wire should require flush capability, false otherwise
* @return this
*/
@NonNull
TaskSchedulerBuilder withFlushingEnabled(boolean requireFlushCapability);
/**
* Set whether the task scheduler should enable squelching. Default false. Enabling squelching may add overhead.
*
* IMPORTANT: you must not enable squelching if the scheduler handles tasks that require special cleanup. If
* squelching is enabled and activated, all existing and incoming tasks will be unceremoniously dumped into the
* void!
*
* @param squelchingEnabled true if the scheduler should enable squelching, false otherwise.
* @return this
*/
@NonNull
TaskSchedulerBuilder withSquelchingEnabled(boolean squelchingEnabled);
/**
* Specify an object counter that should be notified when data is added to the task scheduler. This is useful for
* implementing backpressure that spans multiple schedulers.
*
* @param onRamp the object counter that should be notified when data is added to the task scheduler
* @return this
*/
@NonNull
TaskSchedulerBuilder withOnRamp(@NonNull ObjectCounter onRamp);
/**
* Specify an object counter that should be notified when data is removed from the task scheduler. This is useful
* for implementing backpressure that spans multiple schedulers.
*
* @param offRamp the object counter that should be notified when data is removed from the wire
* @return this
*/
@NonNull
TaskSchedulerBuilder withOffRamp(@NonNull ObjectCounter offRamp);
/**
* If true then the framework will assume that back pressure is being applied via external mechanisms.
*
* This method does not change the runtime behavior of the wiring framework. But it does affect cyclical back
* pressure detection and automatically generated wiring diagrams.
*
* @param externalBackPressure true if back pressure is being applied externally, false otherwise
* @return this
*/
@NonNull
TaskSchedulerBuilder withExternalBackPressure(boolean externalBackPressure);
/**
* If a method needs to block, this is the amount of time that is slept while waiting for the needed condition.
*
* @param backpressureSleepDuration the length of time to sleep when backpressure needs to be applied
* @return this
*/
@NonNull
TaskSchedulerBuilder withSleepDuration(@NonNull Duration backpressureSleepDuration);
/**
* Set whether the unhandled task count metric should be enabled. Default false.
*
* @param enabled true if the unhandled task count metric should be enabled, false otherwise
* @return this
*/
@NonNull
TaskSchedulerBuilder withUnhandledTaskMetricEnabled(boolean enabled);
/**
* Set whether the busy fraction metric should be enabled. Default false.
*
* Note: this metric is currently only compatible with non-concurrent task scheduler implementations. At a future
* time this metric may be updated to work with concurrent scheduler implementations.
*
* @param enabled true if the busy fraction metric should be enabled, false otherwise
* @return this
*/
@NonNull
TaskSchedulerBuilder withBusyFractionMetricsEnabled(boolean enabled);
/**
* Provide a custom thread pool for this task scheduler. If none is provided then the common fork join pool will be
* used.
*
* @param pool the thread pool
* @return this
*/
@NonNull
TaskSchedulerBuilder withPool(@NonNull ForkJoinPool pool);
/**
* Provide a custom uncaught exception handler for this task scheduler. If none is provided then the default
* uncaught exception handler will be used. The default handler will write a message to the log.
*
* @param uncaughtExceptionHandler the uncaught exception handler
* @return this
*/
@NonNull
TaskSchedulerBuilder withUncaughtExceptionHandler(@NonNull UncaughtExceptionHandler uncaughtExceptionHandler);
/**
* Provide a hyperlink to documentation for this task scheduler. If none is provided then no hyperlink will be
* generated. Used only for the automatically generated wiring diagram.
*
* @param hyperlink the hyperlink to the documentation for this task scheduler
* @return this
*/
@NonNull
TaskSchedulerBuilder withHyperlink(@Nullable String hyperlink);
/**
* Build the task scheduler.
*
* @return the task scheduler
*/
@NonNull
TaskScheduler build();
}