Summon an instance of Concurrent for F.

Function that creates an async and cancelable F[A], similar with Concurrent.cancelable, but with the semantics of Async.asyncF.

Example building an asynchronous queue, with the state being kept in cats.effect.concurrent.Ref and thus needing cancelableF:

import cats.syntax.all._
import cats.effect.{CancelToken, Concurrent}
import cats.effect.concurrent.Ref
import scala.collection.immutable.Queue

final class AsyncQueue[F[_], A] private (
  ref: Ref[F, AsyncQueue.State[A]])
  (implicit F: Concurrent[F]) {

  import AsyncQueue._

  def poll: F[A] =
    Concurrent.cancelableF { cb =>
      ref.modify {
        case Await(listeners) =>
          (Await(listeners.enqueue(cb)), F.pure(unregister(cb)))
        case Available(queue) =>
          queue.dequeueOption match {
            case None =>
              (Await(Queue(cb)), F.pure(unregister(cb)))
            case Some((a, queue2)) =>
              (Available(queue2), F.delay(cb(Right(a))).as(unregister(cb)))
          }
      }.flatten
    }

  def offer(a: A): F[Unit] = {
    // Left as an exercise for the reader ;-)
    ???
  }

  private def unregister(cb: Either[Throwable, A] => Unit): CancelToken[F] =
    ref.update {
      case Await(listeners) => Await(listeners.filter(_ != cb))
      case other => other
    }
}

object AsyncQueue {
  def empty[F[_], A](implicit F: Concurrent[F]): F[AsyncQueue[F, A]] =
    for {
      ref <- Ref.of[F, State[A]](Available(Queue.empty))
    } yield {
      new AsyncQueue[F, A](ref)
    }

  private sealed trait State[A]

  private case class Await[A](listeners: Queue[Either[Throwable, A] => Unit])
    extends State[A]

  private case class Available[A](values: Queue[A])
    extends State[A]
}

Contract

The given generator function will be executed uninterruptedly, via bracket, because due to the possibility of auto-cancellation we can have a resource leak otherwise.

This means that the task generated by k cannot be cancelled while being evaluated. This is in contrast with Async.asyncF, which does allow cancelable tasks.

Lifts any IO value into any data type implementing Concurrent.

Compared with Async.liftIO, this version preserves the interruptibility of the given IO value.

This is the default Concurrent.liftIO implementation.

Lazily memoizes f. Assuming no cancellation happens, the effect f will be performed at most once for every time the returned F[F[A]] is bound (when the inner F[A] is bound the first time).

If you try to cancel an inner F[A], f is only interrupted if there are no other active subscribers, whereas if there are, f keeps running in the background.

If f is successfully canceled, the next time an inner F[A] is bound f will be restarted again. Note that this can mean the effects of f happen more than once.

You can look at Async.memoize for a version of this function which does not allow cancellation.

Returns an effect that either completes with the result of the source within the specified time duration or otherwise raises a TimeoutException.

The source is cancelled in the event that it takes longer than the specified time duration to complete.

Returns an effect that either completes with the result of the source within the specified time duration or otherwise evaluates the fallback.

The source is cancelled in the event that it takes longer than the FiniteDuration to complete, the evaluation of the fallback happening immediately after that.