### Producer-Consumer IOApp Setup with start/join

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/tutorial.md

Alternative setup for the producer-consumer IOApp using explicit fiber creation with start and join, demonstrating manual fiber management.

```scala
import cats.effect._
import scala.collection.immutable.Queue

object InefficientProducerConsumer extends IOApp {

  def producer[F[_]: Sync](queueR: Ref[F, Queue[Int]], counter: Int): F[Unit] = ??? // As defined before
  def consumer[F[_]: Sync](queueR: Ref[F, Queue[Int]]): F[Unit] = ??? // As defined before


```

--------------------------------

### Demonstrating Fiber Cancellation

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/typeclasses/spawn.md

This example shows how to start a long-running fiber and then cancel it after a delay. It highlights the cancelable nature of fibers, ensuring resources are cleaned up.

```scala
import scala.concurrent.duration._
import cats.effect.IO

for {
  target <- IO.println("Catch me if you can!").foreverM.start
  _ <- IO.sleep(1.second)
  _ <- target.cancel
} yield ()
```

--------------------------------

### Manual Fiber Management Example

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/tutorial.md

Illustrates manual fiber creation, starting, and joining. Be aware that errors in fibers are not automatically propagated and require explicit checking of the Outcome.

```scala
def run(args: List[String]): IO[ExitCode] =
    for {
      queueR <- Ref.of[IO, Queue[Int]](Queue.empty[Int])
      producerFiber <- producer(queueR, 0).start
      consumerFiber <- consumer(queueR).start
      _ <- producerFiber.join
      _ <- consumerFiber.join
    } yield ExitCode.Error
}
```

--------------------------------

### Start and Join Fibers for Parallel Execution

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/typeclasses/spawn.md

Combines the results of two concurrent computations. This example uses `start` to fork computations and `joinWithNever` to wait for their results, assuming they will not be canceled.

```scala
// don't use this in production; it is a simplified example
def both[F[_]: Spawn, A, B](fa: F[A], fb: F[B]): F[(A, B)] = 
  for {
    fiberA <- fa.start
    fiberB <- fb.start

    a <- fiberA.joinWithNever
    b <- fiberB.joinWithNever
  } yield (a, b)
```

--------------------------------

### Example Usage of Env

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/std/env.md

An example demonstrating how to use the Env trait to retrieve an environment variable and print its value.

```APIDOC
## Example Usage

### Description
This example shows how to use the `Env` effect to read an environment variable named `MY_VARIABLE` and print its value to the console.

### Code
```scala
import cats.effect.IO
import cats.effect.std.Env

val program: IO[Unit] =
  for {
    env <- Env[IO] // Obtain an Env instance for IO
    variable <- env.get("MY_VARIABLE") // Get the environment variable
    _ <- IO.println(s"The variable is [${variable}]") // Print the result
  } yield ()
```
```

--------------------------------

### ResourceApp: Basic Resource Usage

Source: https://context7.com/typelevel/cats-effect/llms.txt

An example application demonstrating the basic usage of `Resource` by opening a file and reading its first line.

```scala
import cats.effect._
import java.io.{BufferedReader, FileReader}

// Basic Resource.make
def openFile(path: String): Resource[IO, BufferedReader] = 
  Resource.make(
    IO(new BufferedReader(new FileReader(path)))
  )(reader => IO(reader.close()))

object ResourceApp extends IOApp.Simple {
  def run: IO[Unit] = 
    openFile("/etc/hosts")
      .use(r => IO.blocking(r.readLine()).flatMap(IO.println))
}
```

--------------------------------

### Main Program Setup for Parallel Producers/Consumers

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/tutorial.md

Sets up the main program by instantiating Refs for the counter and state, and then launching multiple producer and consumer fibers in parallel.

```scala
import cats.effect._
```

--------------------------------

### Service Example

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/std/atomic-cell.md

Example of using AtomicCell within a service to manage state with effectual updates.

```APIDOC
## Using AtomicCell in a Service

### Description
Demonstrates how to use `evalUpdate` for managing state within a service, where state modifications involve IO effects.

### Class
```scala
class Service(cell: AtomicCell[IO, State])
```

### Method
- `modify(f: State => IO[State]): IO[Unit]` - Updates the service's state using an effectful function `f`.
```

--------------------------------

### Sequential Async/Await Example

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/std/async-await.md

Demonstrates sequential execution of asynchronous operations using the async and await keywords. This is semantically equivalent to a for-comprehension.

```scala
import cats.effect.IO
import cats.effect.cps._

import scala.concurrent.duration._

val io = IO.sleep(50.millis).as(1)

val program: IO[Int] = async[IO] { io.await + io.await }
```

```scala
val program: IO[Int] = for {
  x1 <- io
  x2 <- io
} yield (x1 + x2)
```

--------------------------------

### Composed Resource Example

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/std/resource.md

Presents the `concat` example rewritten using `Resource`, showcasing how `Resource` simplifies the composition of multiple resources. The `for` comprehension elegantly handles acquisition and the `.use` block defines the usage.

```scala
def file(name: String): Resource[IO, File] = Resource.make(openFile(name))(file => close(file))

val concat: IO[Unit] =
  (
    for {
      in1 <- file("file1")
      in2 <- file("file2")
      out <- file("file3")
    } yield (in1, in2, out)
  ).use { case (file1, file2, file3) =>
    for {
      bytes1 <- read(file1)
      bytes2 <- read(file2)
      _ <- write(file3, bytes1 ++ bytes2)
    } yield ()
  
  }
```

--------------------------------

### Concurrent Resource Access Example

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/std/semaphore.md

Demonstrates how to use a Semaphore to limit concurrent access to a shared resource. This example simulates three processes requesting access to a resource, with only one allowed at a time.

```scala
import cats.effect.{IO, Temporal}
import cats.effect.std.{Console, Semaphore}
import cats.implicits._
import cats.effect.syntax.all._

import scala.concurrent.duration._

class PreciousResource[F[_]: Temporal](name: String, s: Semaphore[F])(implicit F: Console[F]) {
  def use: F[Unit] = 
    for {
      x <- s.available
      _ <- F.println(s"$name >> Availability: $x")
      _ <- s.acquire
      y <- s.available
      _ <- F.println(s"$name >> Started | Availability: $y")
      _ <- s.release.delayBy(3.seconds)
      z <- s.available
      _ <- F.println(s"$name >> Done | Availability: $z")
    } yield ()
}

val program: IO[Unit] = 
  for {
    s  <- Semaphore[IO](1)
    r1 = new PreciousResource[IO]("R1", s)
    r2 = new PreciousResource[IO]("R2", s)
    r3 = new PreciousResource[IO]("R3", s)
    _  <- List(r1.use, r2.use, r3.use).parSequence.void
  } yield ()
```

--------------------------------

### CountDownLatch Usage Example

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/std/countdown-latch.md

Demonstrates how to use CountDownLatch to coordinate between fibers. It initializes a latch with 2 counts, starts a fiber that waits for the latch, and then releases the latch twice.

```scala
import cats.implicits._
import cats.effect._
import cats.effect.std.CountDownLatch
import cats.effect.unsafe.implicits.global

val run = (
  for {
    c <- CountDownLatch[IO](2)
    f <- (c.await >> IO.println("Countdown latch unblocked")).start
    _ <- c.release
    _ <- IO.println("Before latch is unblocked")
    _ <- c.release
    _ <- f.join
  } yield ()
)

run.unsafeRunSync()
```

--------------------------------

### Producer-Consumer IOApp Setup

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/tutorial.md

This IOApp sets up a shared queue using Ref and runs the producer and consumer concurrently using parMapN. It includes basic error handling.

```scala
import cats.effect._
import cats.effect.std.Console
import cats.syntax.all._
import scala.collection.immutable.Queue

object InefficientProducerConsumer extends IOApp {

  def producer[F[_]: Sync](queueR: Ref[F, Queue[Int]], counter: Int): F[Unit] = ??? // As defined before
  def consumer[F[_]: Sync](queueR: Ref[F, Queue[Int]]): F[Unit] = ??? // As defined before

  override def run(args: List[String]): IO[ExitCode] = 
    for {
      queueR <- Ref.of[IO, Queue[Int]](Queue.empty[Int])
      res <- (consumer(queueR), producer(queueR, 0))
        .parMapN((_, _) => ExitCode.Success) // Run producer and consumer in parallel until done (likely by user cancelling with CTRL-C)
        .handleErrorWith { t =>
          Console[IO].errorln(s"Error caught: ${t.getMessage}").as(ExitCode.Error)
        }
    } yield res

}
```

--------------------------------

### Start a Long-Running Task with Supervisor

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/recipes.md

Demonstrates using Supervisor to start a long-running background task from an HTTP server handler. The server responds immediately without waiting for the task to complete.

```scala
import scala.concurrent.duration._

import cats.effect._

final case class Request(path: String, paramaters: Map[String, List[String]])

sealed trait Response extends Product with Serializable
case object NotFound extends Response
final case class Ok(payload: String) extends Response

// dummy case class representing the bound server
final case class IpAddress()

// an HTTP server is a function from request to IO[Response] and is managed within a Resource
final case class HttpServer(handler: Request => IO[Response]) {
  def resource: Resource[IO, IpAddress] = Resource.eval(IO.never.as(IpAddress()))
}

val longRunningTask: Map[String, List[String]] => IO[Unit] = _ => IO.sleep(10.minutes)
```

```scala
import cats.effect.{IO, IOApp}
import cats.effect.std.Supervisor

object Server extends IOApp.Simple {

  def handler(supervisor: Supervisor[IO]): Request => IO[Response] = {
    case Request("start", params) => 
      supervisor.supervise(longRunningTask(params)).void >> IO.pure(Ok("started"))
    case Request(_, _) => IO.pure(NotFound)
  }

  val run =
    Supervisor[IO](await = true).flatMap { supervisor =>
      HttpServer(handler(supervisor)).resource
    }.useForever

}
```

--------------------------------

### Random Data Generator Example

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/std/atomic-cell.md

Example of using `evalUpdateAndGet` for generating new random data that requires effectual operations.

```APIDOC
## Random Data Generator

### Description
Illustrates using `evalUpdateAndGet` to generate new random data, where the generation process itself involves IO effects like database checks.

### Class
```scala
class RandomDataGenerator(cell: AtomicCell[IO, Data])
```

### Method
- `next: IO[Data]` - Generates a new random value by applying the `generate` function to the current state and updating the cell.

### Private Method
- `generate(previous: Data): IO[Data]` - An effectful function that produces a new `Data` value based on the previous one.
```

--------------------------------

### Using KeyedMutex

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/std/keyed-mutex.md

An example demonstrating how to use KeyedMutex in a service to protect access to a shared state managed by a MapRef.

```APIDOC
## Using KeyedMutex

### Description
This example shows a `Service` that uses `KeyedMutex` to ensure that modifications to a state associated with a key are atomic. It acquires a lock for the specific key before accessing and updating the state via a `MapRef`.

### Usage
```scala
import cats.effect.IO
import cats.effect.std.{KeyedMutex, MapRef}

trait State
trait Key

class Service(mutex: KeyedMutex[IO, Key], mapref: MapRef[IO, Key, State]) {
  def modify(key: Key)(f: State => IO[State]): IO[Unit] =
    mutex.lock(key).surround {
      for {
        current <- mapref(key).get
        next <- f(current)
        _ <- mapref(key).set(next)
      } yield ()
    }
}
```
```

--------------------------------

### Example Stack Trace (Without Tracing)

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/tracing.md

This is an example of a raw stack trace from the IO runtime without asynchronous tracing enabled. It includes internal runtime frames that are typically not relevant to application developers.

```java
Exception in thread "main" java.lang.Throwable: Boom!
        at Example$.$anonfun$program$5(Main.scala:23)
	    at cats.effect.IO.$anonfun$ifM$1(IO.scala:409)
	    at cats.effect.IOFiber.runLoop(IOFiber.scala:383)
	    at cats.effect.IOFiber.execR(IOFiber.scala:1126)
	    at cats.effect.IOFiber.run(IOFiber.scala:125)
	    at cats.effect.unsafe.WorkerThread.run(WorkerThread.scala:359)
```

--------------------------------

### EvalOn Example

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/thread-model.md

Demonstrates using `evalOn` to run an effect on a specified blocking pool and then returning to the original pool for the continuation.

```scala
CS.evalOn(blockingPool)(
    IO(println("I run on the blocking pool"))
  ) >> IO(println("I am shifted onto the pool that CS represents"))
```

--------------------------------

### Fiber Demo: Spawning, Joining, and Canceling Fibers

Source: https://context7.com/typelevel/cats-effect/llms.txt

Demonstrates starting two fibers concurrently, joining one, and canceling the other. Also shows background execution, race conditions, and parallel execution with `both`.

```scala
import cats.effect._
import cats.effect.kernel.Outcome
import scala.concurrent.duration._

object FiberDemo extends IOApp.Simple {
  def run: IO[Unit] = 
    for {
      // Start two fibers concurrently
      fiberA <- (IO.sleep(1.second) *> IO.println("fiber A done")).start
      fiberB <- (IO.sleep(500.millis) *> IO.println("fiber B done")).start

      // Await fiber A; handle all outcomes
      outcomeA <- fiberA.join
      _ <- outcomeA match {
             case Outcome.Succeeded(fa) => fa
             case Outcome.Errored(e)    => IO.println(s"A errored: $e")
             case Outcome.Canceled()    => IO.println("A was canceled")
           }

      // Cancel fiber B before it completes
      _ <- fiberB.cancel
      _ <- IO.println("fiber B canceled")

      // background — fiber lifecycle bound to a Resource
      result <- IO(42)
                  .background
                  .use(joinIO => IO.sleep(100.millis) *> joinIO)
      _ <- IO.println(s"background result: $result")

      // race — first to finish wins; loser is canceled
      winner <- IO.race(
                  IO.sleep(200.millis).as("slow"),
                  IO.sleep(50.millis).as("fast")
                )
      _ <- IO.println(s"race winner: ${winner.merge}")

      // both — run in parallel, collect both results
      (x, y) <- IO.both(IO(1), IO(2))
      _ <- IO.println(s"both: $x, $y")
    } yield () 
}
```

--------------------------------

### Example Stack Trace (With Enhanced Tracing)

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/tracing.md

This is an example of an augmented stack trace when asynchronous stack tracing is enabled. It preserves relevant application frames while replacing internal runtime frames with asynchronous call-site information.

```java
Exception in thread "main" java.lang.Throwable: Boom!
        at Example$.$anonfun$program$5(Main.scala:25)
        at apply @ Example$.$anonfun$program$3(Main.scala:24)
        at ifM @ Example$.$anonfun$program$3(Main.scala:25)
        at map @ Example$.$anonfun$program$3(Main.scala:24)
        at apply @ Example$.$anonfun$program$1(Main.scala:23)
        at flatMap @ Example$.$anonfun$program$1(Main.scala:23)
        at apply @ Example$.fib(Main.scala:13)
        at flatMap @ Example$.fib(Main.scala:13)
        at apply @ Example$.fib(Main.scala:13)
        at flatMap @ Example$.fib(Main.scala:13)
        at apply @ Example$.fib(Main.scala:13)
        at flatMap @ Example$.fib(Main.scala:13)
        at apply @ Example$.fib(Main.scala:13)
        at flatMap @ Example$.fib(Main.scala:13)
        at apply @ Example$.fib(Main.scala:13)
        at flatMap @ Example$.fib(Main.scala:13)
        at apply @ Example$.fib(Main.scala:13)
        at flatMap @ Example$.fib(Main.scala:13)
        at apply @ Example$.fib(Main.scala:13)
        at flatMap @ Example$.fib(Main.scala:13)
        at apply @ Example$.fib(Main.scala:13)
        at flatMap @ Example$.fib(Main.scala:13)
        at apply @ Example$.fib(Main.scala:13)
        at flatMap @ Example$.fib(Main.scala:13)
        at apply @ Example$.fib(Main.scala:13)
        at flatMap @ Example$.fib(Main.scala:13)
        at apply @ Example$.fib(Main.scala:13)
        at flatMap @ Example$.fib(Main.scala:13)
        at apply @ Example$.fib(Main.scala:13)
        at flatMap @ Example$.fib(Main.scala:13)
        at apply @ Example$.fib(Main.scala:13)
        at flatMap @ Example$.fib(Main.scala:13)
        at apply @ Example$.fib(Main.scala:13)
        at flatMap @ Example$.fib(Main.scala:13)
        at apply @ Example$.fib(Main.scala:13)
        at flatMap @ Example$.fib(Main.scala:13)
        at apply @ Example$.fib(Main.scala:13)
        at flatMap @ Example$.fib(Main.scala:13)
        at apply @ Example$.fib(Main.scala:13)
        at flatMap @ Example$.fib(Main.scala:13)
        at apply @ Example$.fib(Main.scala:13)
        at flatMap @ Example$.fib(Main.scala:13)
        at apply @ Example$.fib(Main.scala:13)
        at flatMap @ Example$.fib(Main.scala:13)
        at apply @ Example$.fib(Main.scala:13)
        at flatMap @ Example$.fib(Main.scala:13)
        at flatMap @ Example$.program(Main.scala:22)
        at run$ @ Example$.run(Main.scala:10)
```

--------------------------------

### Git Remote Setup for Cats Effect

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/CONTRIBUTING.md

Instructions for adding the typelevel/cats-effect repository as a remote. Use SSH or HTTPS based on your preference.

```bash
git remote add upstream git@github.com:typelevel/cats-effect.git
```

```bash
git remote add upstream https://github.com/typelevel/cats-effect.git
```

--------------------------------

### Stack Tracing Configuration

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/tracing.md

These are example system properties used to configure the stack tracing behavior. The `full` mode and buffer size can be adjusted to control the level of detail and memory usage.

```properties
-Dcats.effect.tracing.mode=full -Dcats.effect.tracing.buffer.size=64
```

```properties
-Dcats.effect.tracing.exceptions.enhanced=false
```

--------------------------------

### Async fromFuture Implementation

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/typeclasses/async.md

Example of `Async[F].fromFuture` using `Future#onComplete` to invoke a callback. Requires `flatMap` and `executionContext`.

```scala
def fromFuture[A](fut: F[Future[A]]): F[A] =
  flatMap(fut) {
    f =>
      flatMap(executionContext) { implicit ec =>
        async_[A](cb => f.onComplete(t => cb(t.toEither)))
      }
  }
```

--------------------------------

### Using Console

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/std/console.md

An example demonstrating how to use the Console trait within an IO program to print messages, read user input, and conditionally print output or an error message.

```APIDOC
## Using Console

### Description
An example program that utilizes the `Console` trait to interact with the user. It prompts for a name, reads the input, and then prints a greeting or an error message based on whether the name is empty.

### Code Example
```scala
import cats.effect.IO
import cats.effect.std.Console

val program: IO[Unit] =
  for {
    _ <- Console[IO].println("Please enter your name: ")
    n <- Console[IO].readLine
    _ <- if (n.nonEmpty) Console[IO].println("Hello, " + n) else Console[IO].errorln("Name is empty!")
  } yield ()
```
```

--------------------------------

### Blocker Usage Example

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/thread-model.md

Shows how `blockOn` executes a given effect on the blocker's pool and then shifts the continuation back to the pool represented by `cs`.

```scala
blocker.blockOn(IO(readFile)) >> IO(println("Shifted back to the pool that CS represents"))
```

--------------------------------

### Scala Native Project Setup

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/core/scala-native.md

Configure your sbt project to use the Scala Native plugin and add Cats Effect as a dependency. Ensure the main class is correctly specified.

```scala
// project/plugins.sbt
addSbtPlugin("org.scala-native" % "sbt-scala-native" % "0.4.7")
```

```scala
// build.sbt
ThisBuild / organization := "com.example"
ThisBuild / scalaVersion := "2.13.8"

lazy val root = project.in(file("."))
  .enablePlugins(ScalaNativePlugin)
  .settings(
    name                := "cats-effect-3-hello-world",
    libraryDependencies += "org.typelevel" %%% "cats-effect" % "3.7.0",
    Compile / mainClass := Some("com.example.Main")
 )
```

--------------------------------

### Timeout Example in Scala

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/concepts.md

Demonstrates how to use the `timeout` function to cancel an infinitely running fiber after a specified duration. This is useful for preventing runaway computations.

```scala
import scala.concurrent.duration._

lazy val loop: IO[Unit] = IO.println("Hello, World!") >> loop

loop.timeout(5.seconds)   // => IO[Unit]
```

--------------------------------

### Threadpool Shifting Example

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/typeclasses/async.md

Demonstrates threadpool shifting using `IO.executionContext` and `IO.evalOn`. Execution shifts to `someEc` for the middle `printThread` call and returns to the default context afterward.

```scala
val printThread: IO[Unit] =
  IO.executionContext.flatMap(IO.println(_))

for {
  _ <- printThread //io-compute-1
  _ <- IO.evalOn(printThread, someEc) //some-ec-thread
  _ <- printThread //io-compute-1
} yield ()
```

--------------------------------

### Sorting with a Bounded Priority Queue

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/std/pqueue.md

Demonstrates how to use a bounded PQueue to sort a list of integers. Elements are offered to the queue and then taken out in priority order. This example requires `cats.Order` and `cats.effect`.

```scala
import cats.Order
import cats.implicits._
import cats.effect._
import cats.effect.std.PQueue
import cats.effect.unsafe.implicits.global

val list = List(1,4,3,7,5,2,6,9,8)

implicit val orderForInt: Order[Int] = Order.fromLessThan((x, y) => x < y)

def absurdlyOverengineeredSort(list: List[Int]) = (
  for {
    pq <- PQueue.bounded[IO, Int](10)
    _ <- list.traverse(pq.offer(_))
    l <- List.fill(list.length)(()).traverse( _ => pq.take)
  } yield l
)

absurdlyOverengineeredSort(list).flatMap(IO.println(_)).unsafeRunSync()
```

--------------------------------

### CyclicBarrier Usage Example

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/std/cyclic-barrier.md

Demonstrates initializing a CyclicBarrier with a count of 2 and coordinating two fibers. One fiber is faster, while the other is delayed. Both fibers wait at the barrier and proceed once both have arrived.

```scala
import cats.implicits._
import cats.effect._
import cats.effect.std.CyclicBarrier
import cats.effect.unsafe.implicits.global
import scala.concurrent.duration._

val run = (for {
  b <- CyclicBarrier[IO](2)
  f1 <- (IO.println("fast fiber before barrier") >>
      b.await >> 
      IO.println("fast fiber after barrier")
    ) .start
  f2 <- (IO.sleep(1.second) >>
      IO.println("slow fiber before barrier") >>
      IO.sleep(1.second) >>
      b.await >>
      IO.println("slow fiber after barrier")
    ).start
  _ <- (f1.join, f2.join).tupled
} yield ()) 

run.unsafeRunSync()
```

--------------------------------

### Supervisor with Awaiting Termination

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/std/supervisor.md

Demonstrates using a Supervisor with `await = true`, where termination waits for active fibers. This example shows a potential indefinite suspension if a supervised effect never completes.

```scala
import cats.effect.IO
import cats.effect.std.Supervisor

Supervisor[IO](await = true).use {
  supervisor =>
    supervisor.supervise(IO.never).void
}
```

--------------------------------

### Build Documentation Site

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/README.md

Execute this script to build the documentation site locally. Your browser will open upon completion.

```bash
./build.sh host
```

--------------------------------

### Simplified IO Runloop Example

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/thread-model.md

A basic representation of the IO data type and its runloop, illustrating `Pure`, `Suspend`, and `FlatMap` operations. This simplified version lacks error handling and stack safety.

```scala
sealed abstract class IO[A] {
  def flatMap[B](f: A => IO[B]): IO[B] = FlatMap(this, f)

  def unsafeRun(): A = this match {
    case Pure(a) => a
    case Suspend(thunk) => thunk()
    case FlatMap(io, f) => f(io.unsafeRun()).unsafeRun()
  }
}

case class Pure[A](a: A) extends IO[A]
case class Suspend[A](thunk: () => A) extends IO[A]
case class FlatMap[A, B](io: IO[B], f: B => IO[A]) extends IO[A]
```

--------------------------------

### Hello World with IOApp.Simple

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/README.md

A simple entry point for Cats Effect applications that prints 'Hello, World!' to the console. No arguments or exit codes are handled.

```scala
import cats.effect._

object Main extends IOApp.Simple {
  val run = IO.println("Hello, World!")
}
```

--------------------------------

### Resource Construction with make

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/std/resource.md

Shows how to create a `Resource` using `Resource.make`, which takes an acquisition action and a release action. This is the primary way to define a resource that needs cleanup.

```scala
def make[F[_], A](acquire: F[A])(release: A => F[Unit]): Resource[F, A]
```

--------------------------------

### IOApp.Simple Application Entry Point

Source: https://context7.com/typelevel/cats-effect/llms.txt

Demonstrates the simplest way to define an application entry point using `IOApp.Simple`. The `run` method returns an `IO[Unit]` and the application exits with code 0.

```scala
import cats.effect._

// Simple variant — run returns IO[Unit], exit code is always 0
object HelloWorld extends IOApp.Simple {
  def run: IO[Unit] = 
    IO.println("Hello, World!")
}
```

--------------------------------

### Hello World with IOApp and Arguments

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/README.md

An entry point for Cats Effect applications that handles command-line arguments and returns an ExitCode. It checks for a '--do-it' argument.

```scala
import cats.effect._

object Main extends IOApp {
  def run(args: List[String]): IO[ExitCode] = 
    if (args.headOption.map(_ == "--do-it").getOrElse(false))
      IO.println("I did it!").as(ExitCode.Success)
    else
      IO.println("Didn't do it").as(ExitCode(-1))
}
```

--------------------------------

### CPU-Bound Operation Example

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/thread-model.md

An example of a potentially long-running, CPU-bound operation within an IO. Such operations can monopolize a thread, necessitating explicit yielding mechanisms like `IO.cede` in CE3.

```scala
def calculate(data: Vector[BigInt]): IO[BigInt] =
  IO(longSubTaskA(data))
    .map(xs => longSubTaskB(xs))
    .map(ys => longSubTaskC(ys))
```

--------------------------------

### Concurrent FizzBuzz Example

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/getting-started.md

A more complex example demonstrating concurrent fibers in Cats Effect. It uses `IOApp.Simple` to run multiple concurrent tasks that interact with a shared mutable state.

```scala
import cats.effect.{IO, IOApp}
import scala.concurrent.duration._

// obviously this isn't actually the problem definition, but it's kinda fun
object StupidFizzBuzz extends IOApp.Simple {
  val run =
    for {
      ctr <- IO.ref(0)

      wait = IO.sleep(1.second)
      poll = wait *> ctr.get

      _ <- poll.flatMap(IO.println(_)).foreverM.start
      _ <- poll.map(_ % 3 == 0).ifM(IO.println("fizz"), IO.unit).foreverM.start
      _ <- poll.map(_ % 5 == 0).ifM(IO.println("buzz"), IO.unit).foreverM.start

      _ <- (wait *> ctr.update(_ + 1)).foreverM.void
    } yield ()
}
```

--------------------------------

### SBT Error Example

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/CONTRIBUTING.md

An example of a fatal error encountered when running sbt due to missing git tags, often occurring if a fork is not created with the default branch only unchecked.

```sbt
[error] fatal: No names found, cannot describe anything.
[error] Nonzero exit code (128) running git.
```

--------------------------------

### IOApp for File Copy Program

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/tutorial.md

Implement the `run` method for an `IOApp` to handle program arguments, initiate file copying, and report success or failure. This example demonstrates argument validation and using `IO.println` for output.

```scala
import cats.effect._
import java.io.File

object CopyFile extends IOApp {

  // copy as defined before
  def copy(origin: File, destination: File): IO[Long] = ???

  override def run(args: List[String]): IO[ExitCode] = 
    for {
      _ <- IO.raiseWhen(args.length < 2)(new IllegalArgumentException("Need origin and destination files"))
      orig = new File(args(0))
      dest = new File(args(1))
      count <- copy(orig, dest)
      _     <- IO.println(s"$count bytes copied from ${orig.getPath} to ${dest.getPath}")
    } yield ExitCode.Success
}
```

--------------------------------

### Checkout Documentation Branch and Submodules

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/README.md

Use these Git commands to checkout the documentation branch and initialize its submodules.

```bash
git checkout --track origin/docs
git submodule update --init --recursive
```

--------------------------------

### NonEmptyHotswap Trait Definition

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/std/hotswap.md

Defines the NonEmptyHotswap trait with swap and get methods. The swap method allows transitioning to the next resource in the sequence, while get provides access to the current resource.

```scala
sealed trait NonEmptyHotswap[F[_], R] {
  def swap(next: Resource[F, R]): F[Unit]
  def get: Resource[F, R]
}
```

--------------------------------

### Running IO Effects with IOApp.Simple

Source: https://context7.com/typelevel/cats-effect/llms.txt

Provides an example of an application entry point using `IOApp.Simple`. This variant is suitable for applications where the `run` method returns `IO[Unit]` and a default exit code of 0 is acceptable.

```scala
// Running effects (end of the world)
object Main extends IOApp.Simple {
  def run: IO[Unit] = 
    program.flatMap(IO.println) >> IO.println("done")
}
```

--------------------------------

### Parking Tower Example with AtomicMap

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/std/atomic-map.md

Illustrates a practical use case of AtomicMap in a parking tower scenario. It shows how to manage parking spaces on different floors, allowing concurrent parking attempts on separate floors without blocking.

```scala
import cats.effect.IO
import cats.effect.std.AtomicMap

trait Car
trait Floor
trait ParkingSpace

class ParkingTowerService(state: AtomicMap[IO, Floor, List[ParkingSpace]]) {
  // Tries to park the given Car in the solicited Floor.
  // Returns either the assigned ParkingSpace, or None if this Floor is full.
  def parkCarInFloor(floor: Floor, car: Car): IO[Option[ParkingSpace]] =
    state(key = floor).evalModify {
      case firstFreeParkingSpace :: remainingParkingSpaces =>
        markParkingSpaceAsUsed(parkingSpace = firstFreeParkingSpace, car).as(
          remainingParkingSpaces -> Some(firstFreeParkingSpace)
        )

      case Nil =>
        IO.pure(List.empty -> None)
    }

  private def markParkingSpaceAsUsed(parkingSpace: ParkingSpace, car: Car): IO[Unit] = 
    ???
}
```

--------------------------------

### JavaScript Fiber Dump Example

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/core/fiber-dumps.md

This is an example of a fiber dump output from a Cats Effect application running on a JavaScript runtime like Node.js. It shows the state and call stack of various fibers, including internal Cats Effect fibers.

```text
cats.effect.IOFiber@d WAITING
 
cats.effect.IOFiber@9 WAITING
 ╰ deferred @ <jscode>.null.$c_LDeadlock$(/workspace/cats-effect/example/js/src/main/scala/cats/effect/example/Example.scala:22)
 
cats.effect.IOFiber@a WAITING
 ├ flatMap @ <jscode>.null.<anonymous>(/workspace/cats-effect/example/js/src/main/scala/cats/effect/example/Example.scala:26)
 ├ flatMap @ <jscode>.null.<anonymous>(/workspace/cats-effect/example/js/src/main/scala/cats/effect/example/Example.scala:25)
 ├ deferred @ <jscode>.null.$c_LDeadlock$(/workspace/cats-effect/example/js/src/main/scala/cats/effect/example/Example.scala:22)
 ╰ flatMap @ <jscode>.null.$c_LDeadlock$(/workspace/cats-effect/example/js/src/main/scala/cats/effect/example/Example.scala:22)
 
cats.effect.IOFiber@b WAITING
 
Global: enqueued 0, waiting 4
```

--------------------------------

### Initialize Cats Effect Project with Giter8

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/README.md

Use the provided Giter8 template to quickly set up a new Cats Effect project. This is an alternative to manual dependency management.

```bash
$ sbt new typelevel/ce3.g8
```

--------------------------------

### Custom IOApp ExecutionContext

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/thread-model.md

Example of overriding executionContextResource in an IOApp to provide a custom threadpool.

```scala
object Main extends IOApp.WithContext {

  override protected def executionContextResource: Resource[SyncIO, ExecutionContext] =
    instantiateSomeCustomThreadpoolHere()

  override def run(args: List[String]): IO[ExitCode] = {
    val computeEC = executionContext
    program(computeEC)
  }
}
```

--------------------------------

### REPL Setup with Cats Effect

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/getting-started.md

Instructions for setting up and running Cats Effect code within a Scala REPL using Ammonite. Includes adding the library dependency and running a simple IO program.

```scala
import $ivy.`org.typelevel::cats-effect:3.7.0`

import cats.effect.unsafe.implicits._
import cats.effect.IO

val program = IO.println("Hello, World!")
program.unsafeRunSync()
```

--------------------------------

### Shift Example

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/thread-model.md

Illustrates the use of `shift` to move the continuation of an effect to the pool represented by the `ContextShift`.

```scala
IO(println("I run on some pool")) >> CS.shift >> IO(println("I run on the pool that CS represents"))
```

--------------------------------

### Basic IO Construction and Composition

Source: https://context7.com/typelevel/cats-effect/llms.txt

Demonstrates fundamental ways to create and sequence IO actions. Use `IO.pure` for existing values, `IO.delay` or `IO` for suspending computations, and `for`-comprehensions for sequential composition. `IO.raiseError` creates a failing effect, and `IO.never` creates a non-terminating one.

```scala
import cats.effect._
import cats.effect.implicits._
import scala.concurrent.duration._

// Basic construction
val pure: IO[Int]    = IO.pure(42)          // already-computed pure value
val delay: IO[Int]   = IO.delay(42)         // suspend side-effecting thunk
val alias: IO[Int]   = IO(42)               // alias for delay
val fail: IO[Int]    = IO.raiseError(new RuntimeException("boom"))
val never: IO[Nothing] = IO.never           // non-terminating

// Sequential composition
val program: IO[String] = for {
  a <- IO(10)
  b <- IO(32)
  _ <- IO.println(s"computing sum of $a and $b")
} yield s"sum = ${a + b}"
```

--------------------------------

### Resource.make: Basic File Opening

Source: https://context7.com/typelevel/cats-effect/llms.txt

Opens a file for reading and ensures it is closed afterwards. Requires a file path as input.

```scala
import cats.effect._
import java.io.{BufferedReader, FileReader}

// Basic Resource.make
def openFile(path: String): Resource[IO, BufferedReader] = 
  Resource.make(
    IO(new BufferedReader(new FileReader(path)))
  )(reader => IO(reader.close()))
```

--------------------------------

### Deferred Abstract Class Definition

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/std/deferred.md

Defines the abstract interface for Deferred, including methods for getting the value and completing the deferred.

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

--------------------------------

### Server Endpoint Implementation with Spawn

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/typeclasses/spawn.md

This example demonstrates how to implement a server endpoint using the Spawn typeclass to handle incoming connections concurrently. It uses `MonadCancel` for resource safety and `.start` to spawn new fibers for each connection.

```scala
import cats.effect.{MonadCancel, Spawn}
import cats.effect.syntax.all._
import cats.syntax.all._

trait Server[F[_]] {
  def accept: F[Connection[F]]
}

trait Connection[F[_]] {
  def read: F[Array[Byte]]
  def write(bytes: Array[Byte]): F[Unit]
  def close: F[Unit]
}

def endpoint[F[_]: Spawn](
    server: Server[F])(
    body: Array[Byte] => F[Array[Byte]])
    : F[Unit] = {

  def handle(conn: Connection[F]): F[Unit] = 
    for {
      request <- conn.read
      response <- body(request)
      _ <- conn.write(response)
    } yield ()

  val handler = MonadCancel[F] uncancelable { poll =>
    poll(server.accept) flatMap { conn =>
      handle(conn).guarantee(conn.close).start
    }
  }

  handler.foreverM
}
```

--------------------------------

### Pathological example with IO.cede.foreverM

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/core/test-runtime.md

Demonstrates a program that behaves differently under `TestControl` compared to production runtimes due to `IO.cede` in an infinite loop.

```scala
IO.cede.foreverM.start flatMap {
  fiber =>
    IO.sleep(1.second) *> fiber.cancel
}
```

--------------------------------

### Specs2 Test with IO

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/getting-started.md

Write Specs2 specifications where examples can return IO. This integrates seamlessly with the Cats Effect testing library.

```scala
import cats.effect.IO
import cats.effect.testing.specs2.CatsEffect

import org.specs2.mutable.Specification

class ExampleSpec extends Specification with CatsEffect {
  "my example" should {
    "make sure IO computes the right result" in {
      IO.pure(1).map(_ + 2) flatMap {
        result =>
          IO(result mustEqual 3)
      }
    }
  }
}
```

--------------------------------

### Demonstrate Cats Effect Queue Flavors and Producer/Consumer Pattern

Source: https://context7.com/typelevel/cats-effect/llms.txt

Illustrates various Queue implementations (bounded, unbounded, dropping, circularBuffer) and a common producer/consumer pattern using a bounded queue with Option for signaling completion. Also shows non-blocking tryOffer/tryTake and size operations.

```scala
import cats.effect._
import cats.effect.std.Queue
import scala.concurrent.duration._

object QueueDemo extends IOApp.Simple {
  def run: IO[Unit] = 
    for {
      // Bounded queue — offer blocks when full
      bounded   <- Queue.bounded[IO, Int](10)
      // Unbounded queue — offer never blocks
      unbounded <- Queue.unbounded[IO, String]
      // Dropping queue — offer drops when full (non-blocking)
      dropping  <- Queue.dropping[IO, Int](5)
      // Circular buffer — offer overwrites oldest when full
      circular  <- Queue.circularBuffer[IO, Int](5)

      // Producer / consumer pattern
      q <- Queue.bounded[IO, Option[Int]](16)

      producer = (1 to 5).toList.traverse_(n => q.offer(Some(n))) *> q.offer(None)

      consumer: IO[List[Int]] = {
        def loop(acc: List[Int]): IO[List[Int]] = 
          q.take.flatMap {
            case None    => IO.pure(acc.reverse)
            case Some(n) => loop(n :: acc)
          }
        loop(Nil)
      }

      (_, items) <- IO.both(producer, consumer)
      _          <- IO.println(s"consumed: $items")

      // tryOffer / tryTake — non-blocking variants
      _ <- bounded.offer(1)
      v <- bounded.tryTake          // IO[Option[Int]] = Some(1)
      _ <- IO.println(s"tryTake: $v")

      empty <- bounded.tryTake      // IO[Option[Int]] = None
      _ <- IO.println(s"empty: $empty")

      // size — current element count
      _ <- unbounded.offer("a") *> unbounded.offer("b")
      n <- unbounded.size
      _ <- IO.println(s"queue size: $n")
    } yield () 
}
```

--------------------------------

### Producer-Consumer Bounded Queue Implementation

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/tutorial.md

This is the main program setup for the producer-consumer pattern with a bounded queue. It initializes the state, creates multiple producers and consumers, and runs them concurrently. Error handling is included to catch exceptions during execution.

```scala
import cats.effect._
import cats.effect.std.Console
import cats.syntax.all._

import scala.collection.immutable.Queue

object ProducerConsumerBounded extends IOApp {

  case class State[F[_], A](queue: Queue[A], capacity: Int, takers: Queue[Deferred[F,A]], offerers: Queue[(A, Deferred[F,Unit])])

  object State {
    def empty[F[_], A](capacity: Int): State[F, A] = State(Queue.empty, capacity, Queue.empty, Queue.empty)
  }

  def producer[F[_]: Async](id: Int, counterR: Ref[F, Int], stateR: Ref[F, State[F,Int]]): F[Unit] = ??? // As defined before

  def consumer[F[_]: Async](id: Int, stateR: Ref[F, State[F, Int]]): F[Unit] = ??? // As defined before

  override def run(args: List[String]): IO[ExitCode] =
    for {
      stateR <- Ref.of[IO, State[IO, Int]](State.empty[IO, Int](capacity = 100))
      counterR <- Ref.of[IO, Int](1)
      producers = List.range(1, 11).map(producer(_, counterR, stateR)) // 10 producers
      consumers = List.range(1, 11).map(consumer(_, stateR))           // 10 consumers
      res <- (producers ++ consumers)
        .parSequence.as(ExitCode.Success) // Run producers and consumers in parallel until done (likely by user cancelling with CTRL-C)
        .handleErrorWith {
          case t =>
            Console[IO].errorln(s"Error caught: ${t.getMessage}").as(ExitCode.Error)
        }
    } yield res
}
```

--------------------------------

### IOApp Full Application Entry Point

Source: https://context7.com/typelevel/cats-effect/llms.txt

Shows the full `IOApp` structure for defining an application entry point. The `run` method returns an `IO[ExitCode]`, allowing for custom exit codes based on application logic.

```scala
// Full variant — run returns IO[ExitCode]
object Server extends IOApp {
  def run(args: List[String]): IO[ExitCode] = 
    args.headOption match {
      case Some(port) =>
        IO.println(s"Starting on port $port")
          .as(ExitCode.Success)
      case None =>
        IO.println("Usage: server <port>")
          .as(ExitCode(1))
    }
}
```

--------------------------------

### Add Cats Effect Dependency

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/README.md

Include this dependency in your build.sbt file to use the core Cats Effect library. This is the most common setup.

```scala
libraryDependencies += "org.typelevel" %% "cats-effect" % "3.7.0"
```

--------------------------------

### Defining the Main Fiber with IOApp.Simple

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/concepts.md

Use `IOApp.Simple` to define the entry point of a Cats Effect application. The `run` method returns the main `IO` effect that will be executed.

```scala
object Hi extends IOApp.Simple {
  val run = IO.println("Hello") >> IO.println("World")
}
```

--------------------------------

### Deferred Trait Definition

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/thread-model.md

Defines the Deferred trait, a purely functional promise that can only be completed once. `get` is fiber blocking until `complete` is called.

```scala
trait Deferred[F[_], A] {
  def get: F[A]

  def complete(a: A): F[Boolean]
}
```

--------------------------------

### API requiring Blocker and ContextShift

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/thread-model.md

An example of a common library API pattern in Cats Effect 2 that requires both a `Blocker` and an implicit `ContextShift`.

```scala
def api[F[_] : ContextShift](blocker: Blocker): F[Api]
```

--------------------------------

### Uncancelable Blocking Effect

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/faq.md

Effects constructed with `blocking` are uncancelable by default. This example shows that a `timeout` will not interrupt a `Thread.sleep` within a `blocking` effect.

```scala
IO.blocking(Thread.sleep(1000))
```

--------------------------------

### JVM readLine Timeout Deadlock Example

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/std/console.md

Illustrates a deadlock scenario when using `timeoutTo` with `IO.readLine` on JVM due to underlying blocking I/O.

```scala
IO.readLine.timeoutTo(3.seconds, IO.pure("hello"))
```

--------------------------------

### Weaver Test with IO

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/getting-started.md

Write tests directly against IO using Weaver's SimpleIOSuite. This setup allows for efficient concurrent testing.

```scala
import cats.effect.IO
import weaver._

object ExampleSuite extends SimpleIOSuite {
  test("make sure IO computes the right result") {
    IO.pure(1).map(_ + 2) map {
      result =>
        expect.eql(result, 3)
    }
  }
}
```

--------------------------------

### Create Site PR for Stable Releases

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/RELEASING.md

Run this script for stable releases (not milestones or release candidates) to open a PR that updates the landing page on the docs branch.

```shell
scripts/make-site-pr.sh <old-version> <new-version>
```

```shell
scripts/make-site-pr.sh v3.5.1 v3.5.2
```

--------------------------------

### Ref Abstract Class Definition

Source: https://github.com/typelevel/cats-effect/blob/series/3.x/docs/std/ref.md

Defines the core interface for a concurrent mutable reference, including methods for getting, setting, and updating its value.

```scala
abstract class Ref[F[_], A] {
  def get: F[A]
  def set(a: A): F[Unit]
  def updateAndGet(f: A => A): F[A]
  def modify[B](f: A => (A, B)): F[B]
  // ... and more
}
```