/Watchdog

Java8 function calls with timeout (if necessary interruption of the thread)

Primary LanguageJavaThe UnlicenseUnlicense

Java 8 (repeated) function call support

Each function call has a timeout and terminates the execution. After each function call (even after a timeout or an exception) a TaskResult is created with one of the following ResultCode:

  • ResultCode.OK The execution is completed without exception and the result can be obtained with TaskResult#getResult

  • ResultCode.TIMEOUT The function call was NOT completed, the task was canceled

  • ResultCode.ERROR An unexpected exception has occurred. The exception can be determined with TaskResult#getErrorReason.

Quick start

This library supports Runnable, Callable, Consumer and Function. When a timeout occurs, the worker thread is interrupted. Be careful to handle the interruption properly, otherwise a thread of an ExecutorService (⇒ your function) could end up in an infinite loop (⇒ examples). One way to handle an interruption is as follows:

if (Thread.interrupted()) {
  throw new InterruptedException();
}

Setup

  1. Import the Library in your project (see instructions below)

  2. Create & store a WatchdogFactory. Each factory stores two ExecutorServices

  3. Use Watchable.builder(…​) to create a watchable and WatchableOptions.builder(…​) to create the options
    optional: add a ResultProcessor to the watchable builder (this callback not monitored)

  4. Create an asynchronous function call with WatchdogFactory#submitFunctionCall, a synchronized function call using WatchdogFactory#waitForCompletion or create a RepeatableTask with WatchdogFactory#createRepeated

  5. In case of a RepeatableTask call the task with RepeatableTask#submitFunctionCall and RepeatableTask#waitForCompletion

Import the Library

Gradle

repositories {
    maven {
        url = uri("https://maven.pkg.github.com/JanPollmann/Watchdog")
    }
}

dependencies {
    implementation 'de.pollmann.watchdog:watchdog:<version>'
}

Maven

Follow the GitHub documentation of the desired package: https://github.com/JanPollmann/Watchdog/packages

Important

Caution

  • Please remind: ResultProcessor (if specified) will be called after the monitored function call without any timeout. If there is heavy computational work, the call will take longer as specified (or will not terminate if there is an infinite loop)

    • Obviously, you could execute a RepeatableTask as ResultProcessor :)

  • The timeout is specified in milliseconds

    • A timeout of 0 ms will be handled as no timeout

  • For not repeated function calls, the input of a function/consumer is passed to the builder!

  • As soon as the internal worker of the WatchdogFactory gets garbage collected, ExecutorServices#shutdown is called for every ExecutorServices (finalize)

    • A RepeatableTask has a reference to the internal worker

    • To terminate the RepeatableTask call RepeatableTask#terminate

    • A terminated RepeatableTask will throw a RepeatableTaskTerminatedException!

Changelog

Example

Just implement loop. Remarks:

  • A timeout of 0 ms will be handled as no timeout

  • both tasks have a ResultConsumer registered, but that’s an optional feature