ham-fisted.fjp

Support for java.util.concurrent.ForkJoinPool-specific operations such as managed block and task fork/join. Additionally supports concept of 'exception-safe' via wrapping executing code and unwrapper result post execution in order avoid wrapping exceptions and breaking calling code that may be expecting specific exception types.

Some of the api's fall back to regular executor service code when called.

Example:

(defn split-parallel-reduce
  "Perform a parallel reduction of a spliterator using the provided ExecutorService"
  [executor-service split ideal-split init-fn rfn merge-fn]
  (let [n-elems (proto/estimate-count split)
        pool (or executor-service (ForkJoinPool/commonPool))]
    (if (or (<= n-elems (long ideal-split)) (= n-elems Long/MAX_VALUE))
      (split-reduce rfn (init-fn) split)
      (if-let [[lhs rhs] (proto/split split)]
        (let [lt (fjp/safe-fork-task pool (split-parallel-reduce pool lhs ideal-split init-fn rfn merge-fn))
              rt (fjp/safe-fork-task pool (split-parallel-reduce pool rhs ideal-split init-fn rfn merge-fn))]
          (merge-fn (fjp/managed-block-unwrap lt) (fjp/managed-block-unwrap rt)))))))

common-pool

(common-pool)

Returns (ForkJoinPool/commonPool)

common-pool-parallelism

(common-pool-parallelism)

Integer parallelism assigned to the common pool

compute

(compute t)

compute a task in current thread - returns result

exception-safe

macro

(exception-safe & code)

Wrap code in an exception-safe wrapper - returns a map with either :ham-fisted.fjp/result or :ham-fisted.fjp.error.

fork-task

(fork-task pool f)

Begin a separate execution for f. If already in a fork join pool fork the task else submit f to passed in pool.

in-fork-join-pool?

(in-fork-join-pool?)

Returns true if this task is executing in a fork join pool thread

join

(join t)

join a previously forked task returning the result

managed-block

(managed-block dly)(managed-block finished? wait-till-finished get-value)

Block on a delay or future using the fjp system's managed blocking facility. Safe to call all the time whether the current system is in a forkjoinpool task or not.

managed-block-unwrap

(managed-block-unwrap dly)

managed block then safe unwrap the exception-safe result

on-cp

macro

(on-cp & code)

Run arbitrary code on the common-pool. Make sure any blocking operations are wrapped in managed-block.

safe-common-pool

(safe-common-pool safe-code)

Run safe code - see exception-safe unwrapping the result and re-throwing the wrapped exception. This allows systems based on typed exceptions to pass error info.

safe-fork-task

macro

(safe-fork-task pool & code)

Called from within an executing task, fork a executing some code and wrapping it in exception-safe then calling fork-task

task

(task f)

Create a task from a clojure IFn or something that implements IDeref

unsafe-common-pool

(unsafe-common-pool code)

Run a callable on the common pool. If the callable throws you will get a wrapped exception thrown which may confuse calling code - specifically code that relies on exact exception types or ex-info.

unwrap-safe

(unwrap-safe m)

Unwrap result created via executing code wrapped in exception-safe. Throws original exception if found.