Add Bracket type class

build.sbt

@@ -219,6 +219,14 @@ val mimaSettings = Seq(
       //   - catsStateTLiftIO
       //   - catsWriterTLiftIO
       exclude[MissingTypesProblem]("cats.effect.LiftIO$"),
+      exclude[MissingTypesProblem]("cats.effect.Effect$"),
+      exclude[IncompatibleTemplateDefProblem]("cats.effect.AsyncInstances"),
+      exclude[IncompatibleTemplateDefProblem]("cats.effect.IOInstances"),
+      exclude[ReversedMissingMethodProblem]("cats.effect.SyncInstances#WriterTSync.bracket"),
+      exclude[InheritedNewAbstractMethodProblem]("cats.effect.Bracket.bracket"),
+      exclude[ReversedMissingMethodProblem]("cats.effect.SyncInstances#StateTSync.bracket"),
+      exclude[ReversedMissingMethodProblem]("cats.effect.SyncInstances#OptionTSync.bracket"),
+      exclude[ReversedMissingMethodProblem]("cats.effect.SyncInstances#EitherTSync.bracket"),
       exclude[MissingClassProblem]("cats.effect.LiftIOInstances"),
       exclude[MissingClassProblem]("cats.effect.LiftIOInstances$OptionTLiftIO"),
       exclude[MissingClassProblem]("cats.effect.LiftIOInstances$KleisliLiftIO"),

core/shared/src/main/scala/cats/effect/Bracket.scala

@@ -0,0 +1,45 @@
+/*
+ * Copyright (c) 2017-2018 The Typelevel Cats-effect Project Developers
+ *
+ * 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 cats
+package effect
+
+trait Bracket[F[_], E] extends MonadError[F, E] {
+  def bracket[A, B](acquire: F[A])(use: A => F[B])
+    (release: (A, BracketResult[E]) => F[Unit]): F[B]
+}
+
+sealed abstract class BracketResult[+E]
+
+object BracketResult {
+  case object Completed extends BracketResult[Nothing]
+  case class Error[+E](e: E) extends BracketResult[E]
+  case class Canceled[+E](e: Option[E]) extends BracketResult[E]
+
+  def complete[E]: BracketResult[E] = Completed
+  def error[E](e: E): BracketResult[E] = Error[E](e)
+  def cancelled[E](e: Option[E] = None): BracketResult[E] = Canceled(e)
+
+  def attempt[E, A](value: Either[E, A]): BracketResult[E] =
+    value match {
+      case Left(e) => BracketResult.error(e)
+      case Right(_) => BracketResult.complete
+    }
+}
+
+object Bracket {
+  def apply[F[_], E](implicit ev: Bracket[F, E]): Bracket[F, E] = ev
+}

core/shared/src/main/scala/cats/effect/IO.scala

@@ -22,8 +22,9 @@ import cats.effect.internals._
 import cats.effect.internals.Callback.Extensions
 import cats.effect.internals.TrampolineEC.immediate
 import cats.effect.internals.IOPlatform.fusionMaxStackDepth
+
 import scala.annotation.unchecked.uncheckedVariance
-import scala.concurrent.{ExecutionContext, Future, Promise}
+import scala.concurrent.{CancellationException, ExecutionContext, Future, Promise}
 import scala.concurrent.duration._
 import scala.util.{Failure, Left, Right, Success}
 
@@ -383,6 +384,19 @@ sealed abstract class IO[+A] extends internals.IOBinaryCompat[A] {
   final def to[F[_]](implicit F: LiftIO[F]): F[A @uncheckedVariance] =
     F.liftIO(this)
 
+  private final val cancelException = new CancellationException("cancel in bracket")
+
+  def bracket[B](use: A => IO[B])(release: (A, BracketResult[Throwable]) => IO[Unit]): IO[B] =
+    for {
+      a <- this
+      etb <- use(a).onCancelRaiseError(cancelException).attempt
+      _ <- release(a, etb match {
+        case Left(e) => BracketResult.error[Throwable](e)
+        case Right(_) => BracketResult.complete
+      })
+      b <- IO.fromEither(etb)
+    } yield b
+
   override def toString = this match {
     case Pure(a) => s"IO($a)"
     case RaiseError(e) => s"IO(throw $e)"
@@ -486,6 +500,11 @@ private[effect] abstract class IOInstances extends IOLowPriorityInstances {
         case Left(a) => tailRecM(a)(f)
         case Right(b) => pure(b)
       }
+
+    override def bracket[A, B](acquire: IO[A])
+      (use: A => IO[B])
+      (release: (A, BracketResult[Throwable]) => IO[Unit]): IO[B] =
+      acquire.bracket(use)(release)
   }
 
   implicit val ioParallel: Parallel[IO, IO.Par] =
@@ -776,7 +795,11 @@ object IO extends IOInstances {
    * Lifts an Either[Throwable, A] into the IO[A] context raising the throwable
    * if it exists.
    */
-  def fromEither[A](e: Either[Throwable, A]): IO[A] = e.fold(IO.raiseError, IO.pure)
+  def fromEither[A](e: Either[Throwable, A]): IO[A] =
+    e match {
+      case Right(a) => pure(a)
+      case Left(err) => raiseError(err)
+    }
 
   /**
    * Asynchronous boundary described as an effectful `IO`, managed

core/shared/src/main/scala/cats/effect/Sync.scala

@@ -18,6 +18,7 @@ package cats
 package effect
 
 import simulacrum._
+import cats.syntax.all._
 import cats.data.{EitherT, IndexedStateT, OptionT, StateT, WriterT}
 import cats.effect.internals.{AndThen, NonFatal}
 
@@ -26,7 +27,7 @@ import cats.effect.internals.{AndThen, NonFatal}
  * in the `F[_]` context.
  */
 @typeclass
-trait Sync[F[_]] extends MonadError[F, Throwable] {
+trait Sync[F[_]] extends Bracket[F, Throwable] {
   /**
    * Suspends the evaluation of an `F` reference.
    *
@@ -69,6 +70,20 @@ object Sync {
       def raiseError[A](e: Throwable) =
         EitherT.left(Eval.now(e))
 
+      def bracket[A, B](acquire: EitherT[Eval, Throwable, A])
+        (use: A => EitherT[Eval, Throwable, B])
+        (release: (A, BracketResult[Throwable]) => EitherT[Eval, Throwable, Unit]): EitherT[Eval, Throwable, B] = {
+
+        acquire.flatMap { a =>
+          EitherT(FlatMap[Eval].flatTap(use(a).value){ etb =>
+            release(a, etb match {
+              case Left(e) => BracketResult.Error(e)
+              case Right(_) => BracketResult.Completed
+            }).value
+          })
+        }
+      }
+
       def flatMap[A, B](fa: EitherT[Eval, Throwable, A])(f: A => EitherT[Eval, Throwable, B]): EitherT[Eval, Throwable, B] =
         fa.flatMap(f)
 
@@ -126,6 +141,23 @@ object Sync {
     def raiseError[A](e: Throwable): EitherT[F, L, A] =
       EitherT.liftF(F.raiseError(e))
 
+    def bracket[A, B](acquire: EitherT[F, L, A])
+      (use: A => EitherT[F, L, B])
+      (release: (A, BracketResult[Throwable]) => EitherT[F, L, Unit]): EitherT[F, L, B] = {
+
+      EitherT(F.bracket(acquire.value) {
+        case Right(a) => use(a).value
+        case e @ Left(_) => F.pure(e.asInstanceOf[Either[L, B]])
+      } { (ea, br) =>
+        ea match {
+          case Right(a) =>
+            release(a, br).value.map(_ => ())
+          case Left(_) =>
+            F.unit // nothing to release
+        }
+      })
+    }
+
     def flatMap[A, B](fa: EitherT[F, L, A])(f: A => EitherT[F, L, B]): EitherT[F, L, B] =
       fa.flatMap(f)
 
@@ -147,6 +179,21 @@ object Sync {
     def raiseError[A](e: Throwable): OptionT[F, A] =
       OptionT.catsDataMonadErrorForOptionT[F, Throwable].raiseError(e)
 
+    def bracket[A, B](acquire: OptionT[F, A])
+      (use: A => OptionT[F, B])
+      (release: (A, BracketResult[Throwable]) => OptionT[F, Unit]): OptionT[F, B] = {
+
+      OptionT(F.bracket(acquire.value) {
+        case Some(a) => use(a).value
+        case None => F.pure[Option[B]](None)
+      } {
+        case (Some(a), br) =>
+          release(a, br).value.map(_ => ())
+        case _ =>
+          F.unit
+      })
+    }
+
     def flatMap[A, B](fa: OptionT[F, A])(f: A => OptionT[F, B]): OptionT[F, B] =
       fa.flatMap(f)
 
@@ -168,6 +215,19 @@ object Sync {
     def raiseError[A](e: Throwable): StateT[F, S, A] =
       StateT.liftF(F.raiseError(e))
 
+    def bracket[A, B](acquire: StateT[F, S, A])
+      (use: A => StateT[F, S, B])
+      (release: (A, BracketResult[Throwable]) => StateT[F, S, Unit]): StateT[F, S, B] = {
+
+      StateT { startS =>
+        F.bracket(acquire.run(startS)) { case (s, a) =>
+          use(a).run(s)
+        } { case ((s, a), br) =>
+          release(a, br).run(s).map(_ => ())
+        }
+      }
+    }
+
     override def map[A, B](fa: StateT[F, S, A])(f: A => B): StateT[F, S, B] =
       IndexedStateT.applyF[F, S, S, B](F.map(fa.runF) { safsba =>
         AndThen(safsba).andThen(fa => F.map(fa) { case (s, a) => (s, f(a)) })
@@ -202,6 +262,19 @@ object Sync {
     def raiseError[A](e: Throwable): WriterT[F, L, A] =
       WriterT.catsDataMonadErrorForWriterT[F, L, Throwable].raiseError(e)
 
+    def bracket[A, B](acquire: WriterT[F, L, A])
+      (use: A => WriterT[F, L, B])
+      (release: (A, BracketResult[Throwable]) => WriterT[F, L, Unit]): WriterT[F, L, B] = {
+
+      acquire.flatMap { a =>
+        WriterT(
+          F.bracket(F.pure(a))(use.andThen(_.run)){ (a, res) =>
+            release(a, res).value
+          }
+        )
+      }
+    }
+
     def flatMap[A, B](fa: WriterT[F, L, A])(f: A => WriterT[F, L, B]): WriterT[F, L, B] =
       fa.flatMap(f)
 

laws/shared/src/main/scala/cats/effect/laws/BracketLaws.scala

@@ -0,0 +1,41 @@
+/*
+ * Copyright (c) 2017-2018 The Typelevel Cats-effect Project Developers
+ *
+ * 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 cats
+package effect
+package laws
+
+import cats.implicits._
+import cats.laws._
+
+trait BracketLaws[F[_], E] extends MonadErrorLaws[F, E] {
+  implicit def F: Bracket[F, E]
+
+  def bracketWithPureUnitIsEqvMap[A, B](fa: F[A], f: A => B) =
+    F.bracket(fa)(a => f(a).pure[F])((_, _) => F.unit) <-> F.map(fa)(f)
+
+  def bracketWithPureUnitIsEqvFlatMap[A, B](fa: F[A], f: A => F[B]) =
+    F.bracket(fa)(f)((_, _) => F.unit) <-> F.flatMap(fa)(f)
+
+  def bracketFailureInAcquisitionRemainsFailure[A, B](e: E, f: A => F[B], release: F[Unit]) =
+    F.bracket(F.raiseError[A](e))(f)((_, _) => release) <-> F.raiseError(e)
+}
+
+object BracketLaws {
+  def apply[F[_], E](implicit F0: Bracket[F, E]): BracketLaws[F, E] = new BracketLaws[F, E] {
+    val F = F0
+  }
+}

laws/shared/src/main/scala/cats/effect/laws/ConcurrentLaws.scala

@@ -25,6 +25,8 @@ import scala.Predef.{identity => id}
 trait ConcurrentLaws[F[_]] extends AsyncLaws[F] {
   implicit def F: Concurrent[F]
 
+  //TODO Add law that ensures Bracket works with cancelation
+
   def asyncCancelableCoherence[A](r: Either[Throwable, A]) = {
     F.async[A](cb => cb(r)) <-> F.cancelable[A] { cb => cb(r); IO.unit }
   }

laws/shared/src/main/scala/cats/effect/laws/SyncLaws.scala

@@ -21,9 +21,19 @@ package laws
 import cats.implicits._
 import cats.laws._
 
-trait SyncLaws[F[_]] extends MonadErrorLaws[F, Throwable] {
+trait SyncLaws[F[_]] extends BracketLaws[F, Throwable] {
   implicit def F: Sync[F]
 
+  def bracketReleaseIsAlwaysCalled[A, B](fa: F[A], fb: F[B], g: A => A, a1: A) = {
+
+    var input = a1
+    val update = F.delay { input = g(input) }
+    val read = F.delay(input)
+
+    F.bracket(fa)(_ => fb)((a, _) => update) *> read <-> fa *> fb *> F.pure(g(a1))
+  }
+
+
   def delayConstantIsPure[A](a: A) =
     F.delay(a) <-> F.pure(a)
 

laws/shared/src/main/scala/cats/effect/laws/discipline/BracketTests.scala

@@ -0,0 +1,73 @@
+/*
+ * Copyright (c) 2017-2018 The Typelevel Cats-effect Project Developers
+ *
+ * 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 cats
+package effect
+package laws
+package discipline
+
+import cats.data._
+import cats.laws.discipline._
+import cats.laws.discipline.SemigroupalTests.Isomorphisms
+import org.scalacheck._
+import Prop.forAll
+
+trait BracketTests[F[_], E] extends MonadErrorTests[F, E] {
+  def laws: BracketLaws[F, E]
+
+  def bracket[A: Arbitrary: Eq, B: Arbitrary: Eq, C: Arbitrary: Eq](
+    implicit
+      ArbFA: Arbitrary[F[A]],
+      ArbFB: Arbitrary[F[B]],
+      ArbFC: Arbitrary[F[C]],
+      ArbFU: Arbitrary[F[Unit]],
+      ArbFAtoB: Arbitrary[F[A => B]],
+      ArbFBtoC: Arbitrary[F[B => C]],
+      ArbE: Arbitrary[E],
+      CogenA: Cogen[A],
+      CogenB: Cogen[B],
+      CogenC: Cogen[C],
+      CogenE: Cogen[E],
+      EqFA: Eq[F[A]],
+      EqFB: Eq[F[B]],
+      EqFC: Eq[F[C]],
+      EqE: Eq[E],
+      EqFEitherEU: Eq[F[Either[E, Unit]]],
+      EqFEitherEA: Eq[F[Either[E, A]]],
+      EqEitherTFEA: Eq[EitherT[F, E, A]],
+      EqFABC: Eq[F[(A, B, C)]],
+      EqFInt: Eq[F[Int]],
+      iso: Isomorphisms[F]): RuleSet = {
+    new RuleSet {
+      val name = "bracket"
+      val bases = Nil
+      val parents = Seq(monadError[A, B, C])
+
+      val props = Seq(
+        "bracket with pure unit on release is eqv to map" -> forAll(laws.bracketWithPureUnitIsEqvMap[A, B] _),
+        "bracket with failure in acquisition remains failure" -> forAll(laws.bracketFailureInAcquisitionRemainsFailure[A, B] _),
+        "bracket with pure unit on release is eqv to flatMap" -> forAll(laws.bracketWithPureUnitIsEqvFlatMap[A, B] _)
+      )
+
+    }
+  }
+}
+
+object BracketTests {
+  def apply[F[_], E](implicit ev: Bracket[F, E]): BracketTests[F, E] = new BracketTests[F, E] {
+    def laws = BracketLaws[F, E]
+  }
+}