or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

application.mdconcurrency.mdindex.mdio.mdresources.mdtype-classes.md
tile.json

tessl/maven-org-typelevel--cats-effect-2-12

High-performance, asynchronous, composable framework for building real-world applications in a purely functional style

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.typelevel/cats-effect_2.12@2.5.x

To install, run

npx @tessl/cli install tessl/maven-org-typelevel--cats-effect-2-12@2.5.0

index.mddocs/

Cats Effect

Cats Effect is a high-performance, asynchronous, composable framework for building real-world applications in a purely functional style. It provides the IO monad for capturing and controlling effects, actions that programs perform within a resource-safe, typed context with seamless support for concurrency and coordination.

Package Information

  • Package Name: cats-effect_2.12
  • Package Type: maven
  • Language: Scala
  • Installation: libraryDependencies += "org.typelevel" %% "cats-effect" % "2.5.5"
  • Documentation: https://typelevel.org/cats-effect/

Core Imports

import cats.effect._
import cats.effect.implicits._

For specific components:

import cats.effect.{IO, Resource, Sync, Async, Concurrent}
import cats.effect.concurrent.{Ref, Deferred, Semaphore, MVar}

Basic Usage

import cats.effect._

// Basic IO construction and execution
val program: IO[Unit] = for {
  _ <- IO(println("Hello, World!"))
  _ <- IO.sleep(1.second)
  _ <- IO(println("Goodbye!"))
} yield ()

// Safe execution within IOApp
object MyApp extends IOApp {
  def run(args: List[String]): IO[ExitCode] = 
    program.as(ExitCode.Success)
}

// Resource management
val fileResource: Resource[IO, BufferedReader] = 
  Resource.fromAutoCloseable(IO(new BufferedReader(new FileReader("file.txt"))))

fileResource.use { reader =>
  IO(reader.readLine()).flatMap(line => IO(println(line)))
}

Architecture

Cats Effect is built around several key architectural components:

  • Effect Type Classes: A hierarchy of type classes (Sync, Async, Concurrent) that define capabilities for different effect types
  • IO Monad: The primary concrete effect type providing referentially transparent side effect management
  • Concurrent Primitives: Thread-safe data structures for coordination (Ref, Deferred, Semaphore, MVar)
  • Resource Management: Bracket-based resource handling for safe allocation and cleanup
  • Fiber System: Lightweight threads for concurrent computation with cancellation support
  • Application Framework: IOApp for building complete applications with proper resource cleanup

Capabilities

IO Monad

The core effect type providing referentially transparent side effect management with full monad operations, error handling, and concurrency support.

// Core IO construction
object IO {
  def pure[A](a: A): IO[A]
  def delay[A](body: => A): IO[A] 
  def defer[A](thunk: => IO[A]): IO[A]
  def async[A](k: (Either[Throwable, A] => Unit) => Unit): IO[A]
  def raiseError[A](e: Throwable): IO[A]
  def never[A]: IO[Nothing]
}

// Core IO operations
abstract class IO[+A] {
  def map[B](f: A => B): IO[B]
  def flatMap[B](f: A => IO[B]): IO[B]
  def attempt: IO[Either[Throwable, A]]
  def handleErrorWith[AA >: A](f: Throwable => IO[AA]): IO[AA]
  def start: IO[Fiber[IO, A]]
  def unsafeRunSync(): A
  def unsafeRunAsync(cb: Either[Throwable, A] => Unit): Unit
}

IO Monad Operations

Effect Type Classes

Type class hierarchy defining capabilities for synchronous, asynchronous, and concurrent effects, enabling abstraction over different effect types.

trait Sync[F[_]] extends Bracket[F, Throwable] {
  def delay[A](thunk: => A): F[A]
  def defer[A](fa: => F[A]): F[A]
}

trait Async[F[_]] extends Sync[F] {
  def async[A](k: (Either[Throwable, A] => Unit) => Unit): F[A]
  def asyncF[A](k: (Either[Throwable, A] => Unit) => F[Unit]): F[A]
}

trait Concurrent[F[_]] extends Async[F] {
  def start[A](fa: F[A]): F[Fiber[F, A]]
  def race[A, B](fa: F[A], fb: F[B]): F[Either[A, B]]
  def cancelable[A](k: (Either[Throwable, A] => Unit) => CancelToken[F]): F[A]
}

Effect Type Classes

Concurrent Primitives

Thread-safe, purely functional data structures for coordination and state management in concurrent programs.

abstract class Ref[F[_], A] {
  def get: F[A]
  def set(a: A): F[Unit] 
  def modify[B](f: A => (A, B)): F[B]
  def update(f: A => A): F[Unit]
}

abstract class Deferred[F[_], A] {
  def get: F[A]
  def complete(a: A): F[Unit]
}

abstract class Semaphore[F[_]] {
  def acquire: F[Unit]
  def release: F[Unit]
  def withPermit[A](t: F[A]): F[A]
}

Concurrent Primitives

Resource Management

Safe resource handling with automatic cleanup, supporting both simple resources and complex resource hierarchies.

abstract class Resource[F[_], A] {
  def use[B](f: A => F[B]): F[B]
  def allocated: F[(A, F[Unit])]
  def map[B](f: A => B): Resource[F, B]
  def flatMap[B](f: A => Resource[F, B]): Resource[F, B]
}

object Resource {
  def make[F[_], A](acquire: F[A])(release: A => F[Unit]): Resource[F, A]
  def fromAutoCloseable[F[_], A <: AutoCloseable](fa: F[A]): Resource[F, A]
  def liftF[F[_], A](fa: F[A]): Resource[F, A]
}

Resource Management

Application Framework

IOApp trait for building complete applications with proper lifecycle management, threading, and shutdown handling.

trait IOApp {
  def run(args: List[String]): IO[ExitCode]
  
  implicit def contextShift: ContextShift[IO]
  implicit def timer: Timer[IO]
  
  final def main(args: Array[String]): Unit
}

case class ExitCode(code: Int)
object ExitCode {
  val Success: ExitCode
  val Error: ExitCode
}

Application Framework