Creates a simple, non-cancelable F[A] instance that executes an asynchronous process on evaluation.

The given function is being injected with a side-effectful callback for signaling the final result of an asynchronous process.

This operation could be derived from asyncF, because:

F.async(k) <-> F.asyncF(cb => F.delay(k(cb)))

As an example of wrapping an impure async API, here's the implementation of Async.shift:

def shift[F[_]](ec: ExecutionContext)(implicit F: Async[F]): F[Unit] =
  F.async { cb =>
    // Scheduling an async boundary (logical thread fork)
    ec.execute(new Runnable {
      def run(): Unit = {
        // Signaling successful completion
        cb(Right(()))
      }
    })
  }

Creates a simple, non-cancelable F[A] instance that executes an asynchronous process on evaluation.

The given function is being injected with a side-effectful callback for signaling the final result of an asynchronous process. And its returned result needs to be a pure F[Unit] that gets evaluated by the runtime.

Note the simpler async variant async can be derived like this:

F.async(k) <-> F.asyncF(cb => F.delay(k(cb)))

For wrapping impure APIs usually you can use the simpler async, however asyncF is useful in cases where impure APIs are wrapped with the help of pure abstractions, such as Ref.

For example here's how a simple, "pure Promise" implementation could be implemented via Ref (sample is for didactic purposes, as you have a far better Deferred available):

import cats.effect.concurrent.Ref

type Callback[-A] = Either[Throwable, A] => Unit

class PurePromise[F[_], A](ref: Ref[F, Either[List[Callback[A]], A]])
  (implicit F: Async[F]) {

  def get: F[A] = F.asyncF { cb =>
    ref.modify {
      case current @ Right(result) =>
        (current, F.delay(cb(Right(result))))
      case Left(list) =>
        (Left(cb :: list), F.unit)
    }
  }

  def complete(value: A): F[Unit] =
    F.flatten(ref.modify {
      case Left(list) =>
        (Right(value), F.delay(list.foreach(_(Right(value)))))
      case right =>
        (right, F.unit)
    })
}

N.B. if F[_] is a cancelable data type (i.e. implementing Concurrent), then the returned F[Unit] can be cancelable, its evaluation hooking into the underlying cancelation mechanism of F[_], so something like this behaves like you'd expect:

def delayed[F[_], A](thunk: => A)
  (implicit F: Async[F], timer: Timer[F]): F[A] = {

  timer.sleep(1.second) *> F.delay(cb(
    try cb(Right(thunk))
    catch { case NonFatal(e) => Left(cb(Left(e))) }
  ))
}

The asyncF operation behaves like Sync.suspend, except that the result has to be signaled via the provided callback.

ERROR HANDLING

As a matter of contract the returned F[Unit] should not throw errors. If it does, then the behavior is undefined.

This is because by contract the provided callback should only be called once. Calling it concurrently, multiple times, is a contract violation. And if the returned F[Unit] throws, then the implementation might have called it already, so it would be a contract violation to call it without expensive synchronization.

In case errors are thrown the behavior is implementation specific. The error might get logged to stderr, or via other mechanisms that are implementations specific.

A generalized version of bracket which uses ExitCase to distinguish between different exit cases when releasing the acquired resource.

Run two tasks concurrently, creating a race between them and returns a pair containing both the winner's successful value and the loser represented as a still-unfinished fiber.

If the first task completes in error, then the result will complete in error, the other task being canceled.

On usage the user has the option of canceling the losing task, this being equivalent with plain race:

val ioA: IO[A] = ???
val ioB: IO[B] = ???

Concurrent[IO].racePair(ioA, ioB).flatMap {
  case Left((a, fiberB)) =>
    fiberB.cancel.map(_ => a)
  case Right((fiberA, b)) =>
    fiberA.cancel.map(_ => b)
}

See race for a simpler version that cancels the loser immediately.

Start concurrent execution of the source suspended in the F context.

Returns a Fiber that can be used to either join or cancel the running computation, being similar in spirit (but not in implementation) to starting a thread.

Suspends the evaluation of an F reference.

Equivalent to FlatMap.flatten for pure expressions, the purpose of this function is to suspend side effects in F.

Returns a resource that will start execution of the effect in the background.

In case the resource is closed while the effect is still running (e.g. due to a failure in use), the background action will be canceled.

A basic example with IO:

val longProcess = (IO.sleep(5.seconds) *> IO(println("Ping!"))).foreverM

val srv: Resource[IO, ServerBinding[IO]] = for {
  _ <- longProcess.background
  server <- server.run
} yield server

val application = srv.use(binding => IO(println("Bound to " + binding)) *> IO.never)

Here, we are starting a background process as part of the application's startup. Afterwards, we initialize a server. Then, we use that server forever using IO.never. This will ensure we never close the server resource unless somebody cancels the whole application action.

If at some point of using the resource you want to wait for the result of the background action, you can do so by sequencing the value inside the resource (it's equivalent to join on Fiber).

This will start the background process, run another action, and wait for the result of the background process:

longProcess.background.use(await => anotherProcess *> await)

In case the result of such an action is canceled, both processes will receive cancelation signals. The same result can be achieved by using anotherProcess &> longProcess with the Parallel type class syntax.

Operation meant for specifying tasks with safe resource acquisition and release in the face of errors and interruption.

This operation provides the equivalent of try/catch/finally statements in mainstream imperative languages for resource acquisition and release.

Creates a cancelable F[A] instance that executes an asynchronous process on evaluation.

This builder accepts a registration function that is being injected with a side-effectful callback, to be called when the asynchronous process is complete with a final result.

The registration function is also supposed to return a CancelToken, which is nothing more than an alias for F[Unit], capturing the logic necessary for canceling the asynchronous process for as long as it is still active.

Example:

import java.util.concurrent.ScheduledExecutorService
import scala.concurrent.duration._

def sleep[F[_]](d: FiniteDuration)
  (implicit F: Concurrent[F], ec: ScheduledExecutorService): F[Unit] = {

  F.cancelable { cb =>
    // Schedules task to run after delay
    val run = new Runnable { def run() = cb(Right(())) }
    val future = ec.schedule(run, d.length, d.unit)

    // Cancellation logic, suspended in F
    F.delay(future.cancel(true))
  }
}

If no interruption happens during the execution of this method, it behaves like .attempt.flatMap.

Unlike .attempt.flatMap however, in the presence of interruption this method offers the _continual guarantee_: fa is interruptible, but if it completes execution, the effects of f are guaranteed to execute. This does not hold for attempt.flatMap since interruption can happen in between flatMap steps.

The typical use case for this function arises in the implementation of concurrent abstractions, where you have asynchronous operations waiting on some condition (which have to be interruptible), mixed with operations that modify some shared state if the condition holds true (which need to be guaranteed to happen or the state will be inconsistent).

Note that for the use case above: - We cannot use:

waitingOp.bracket(..., modifyOp)

because it makes waitingOp uninterruptible.

- We cannot use

waitingOp.guaranteeCase {
  case Success => modifyOp(???)
  ...

if we need to use the result of waitingOp.

- We cannot use

waitingOp.attempt.flatMap(modifyOp)

because it could be interrupted after waitingOp is done, but before modifyOp executes.

To access this implementation as a standalone function, you can use Concurrent.continual in the companion object.

Alias for suspend that suspends the evaluation of an F reference and implements cats.Defer typeclass.

Lifts any by-name parameter into the F context.

Equivalent to Applicative.pure for pure expressions, the purpose of this function is to suspend side effects in F.

Executes the given finalizer when the source is finished, either in success or in error, or if canceled.

This variant of guaranteeCase evaluates the given finalizer regardless of how the source gets terminated:

• normal completion
• completion in error
• cancelation

This equivalence always holds:

F.guarantee(fa)(f) <-> F.bracket(F.unit)(_ => fa)(_ => f)

As best practice, it's not a good idea to release resources via guaranteeCase in polymorphic code. Prefer bracket for the acquisition and release of resources.

Executes the given finalizer when the source is finished, either in success or in error, or if canceled, allowing for differentiating between exit conditions.

This variant of guarantee injects an ExitCase in the provided function, allowing one to make a difference between:

• normal completion
• completion in error
• cancelation

This equivalence always holds:

F.guaranteeCase(fa)(f) <-> F.bracketCase(F.unit)(_ => fa)((_, e) => f(e))

As best practice, it's not a good idea to release resources via guaranteeCase in polymorphic code. Prefer bracketCase for the acquisition and release of resources.

Inherited from LiftIO, defines a conversion from IO in terms of the Concurrent type class.

N.B. expressing this conversion in terms of Concurrent and its capabilities means that the resulting F is cancelable in case the source IO is.

To access this implementation as a standalone function, you can use Concurrent.liftIO (on the object companion).

Returns a non-terminating F[_], that never completes with a result, being equivalent to async(_ => ())

Executes the given finalizer when the source is canceled.

The typical use case for this function arises in the implementation of concurrent abstractions, which generally consist of operations that perform asynchronous waiting after concurrently modifying some state: in case the user asks for cancelation, we want to interrupt the waiting operation, and restore the state to its previous value.

waitingOp.onCancel(restoreState)

A direct use of bracket is not a good fit for this case as it would make the waiting action uncancelable.

NOTE: This function handles interruption only, you need to take care of the success and error case elsewhere in your code

Run two tasks concurrently and return the first to finish, either in success or error. The loser of the race is canceled.

The two tasks are potentially executed in parallel, the winner being the first that signals a result.

As an example see Concurrent.timeoutTo

Also see racePair for a version that does not cancel the loser automatically on successful results.