Linebacker Build Status Maven Central Gitter chat

Enabling Functional Blocking where you need it.

Quick Start

To use linebacker in an existing SBT project with Scala 2.11 or a later version, add the following dependency to your build.sbt:

libraryDependencies += "io.chrisdavenport" %% "linebacker" % "<version>"

Why Linebacker

Concurrency is hard.

No Seriously, Why Linebacker

Generally threading models have to deal with the idea that in java/scala some of our fundamental calls are still blocking. Looking at you JDBC! In order to handle this we generally utilize Executors or ExecutionContexts. Additionally many libraries now utilize implicit execution contexts for their shifting. This puts us in a position where we need to manually and explicitly pass around two contexts raising one explicitly where appropriate and then shifting work back and forth from the pools as appropriate.

Here is where we attempt to make these patterns easier. This library provides abstractions for managing pools and shifting behavior between your pools.

Why should you care? Let us propose you have a single pool on 5 threads and you receive 5 requests that require communicating with a database. What happens if a 6th call comes in when all these CPU bound threads are blocked on network IO? Obviously we are waiting for threads.

Some additional resources for why this is important:

Examples

First some imports

import scala.concurrent.ExecutionContext.global
import cats.effect._
import cats.implicits._
import io.chrisdavenport.linebacker.Linebacker
import io.chrisdavenport.linebacker.contexts.Executors

Creating And Evaluating Pool Behavior

scala> val getThread = IO(Thread.currentThread().getName)
getThread: cats.effect.IO[String] = IO$1632495264

scala> val checkRun = {
     |   Executors.unbound[IO] // Create Executor
     |     .map(Linebacker.fromExecutorService[IO](_)) // Create Linebacker From Executor
     |     .use{ implicit linebacker => // Raise Implicitly
     |       implicit val cs = IO.contextShift(global)
     |       Linebacker[IO].blockCS(getThread) // Block On Linebacker Pool Not Global
     |         .flatMap(threadName => IO(println(threadName))) >>
     |       getThread // Running On Global
     |         .flatMap(threadName => IO(println(threadName)))
     |     }
     | }
checkRun: cats.effect.IO[Unit] = IO$121679743

scala> checkRun.unsafeRunSync
linebacker-thread-0
scala-execution-context-global-113

Dual Contexts Are Also Very Useful

scala> import scala.concurrent.ExecutionContext
import scala.concurrent.ExecutionContext

scala> import io.chrisdavenport.linebacker.DualContext
import io.chrisdavenport.linebacker.DualContext

scala> Executors.unbound[IO].map(blockingExecutor =>
     |   DualContext.fromContexts[IO](IO.contextShift(global),  ExecutionContext.fromExecutorService(blockingExecutor))
     | )
res1: cats.effect.Resource[cats.effect.IO,io.chrisdavenport.linebacker.DualContext[cats.effect.IO]] = Bind(Bind(Suspend(<function1>),io.chrisdavenport.linebacker.contexts.Executors$$$Lambda$6107/369984598@2a693e78),cats.effect.Resource$$Lambda$6109/2030909242@4f563c73)