Skip to content

ChristopherDavenport/linebacker

Repository files navigation

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:

Thread pool best practices.
For more info, see @djspiewak & @alexelcu posts:https://t.co/pr6McpU3tHhttps://t.co/Vz617IMjRB pic.twitter.com/gJgzZI6yGJ

— Impure Pics (@impurepics) April 21, 2018
<script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>

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

val getThread = IO(Thread.currentThread().getName)

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.unsafeRunSync

Dual Contexts Are Also Very Useful

import scala.concurrent.ExecutionContext
import io.chrisdavenport.linebacker.DualContext

Executors.unbound[IO].map(blockingExecutor =>
  DualContext.fromContexts[IO](IO.contextShift(global),  ExecutionContext.fromExecutorService(blockingExecutor))
)