0
# Cats Effect
1

2
Cats Effect is a high-performance, asynchronous, composable framework for building real-world applications in a purely functional style within the Typelevel ecosystem. It provides a concrete tool, known as 'the IO monad', for capturing and controlling actions, often referred to as 'effects', that your program wishes to perform within a resource-safe, typed context with seamless support for concurrency and coordination.
3

4
## Package Information
5

6
- **Package Name**: cats-effect_2.12
7
- **Package Type**: maven
8
- **Language**: Scala
9
- **Installation**: `libraryDependencies += "org.typelevel" %% "cats-effect" % "3.6.1"`
10

11
## Core Imports
12

13
```scala
14
import cats.effect._
15
import cats.effect.implicits._
16
```
17

18
For kernel-only (minimal dependencies):
19

20
```scala
21
import cats.effect.kernel._
22
```
23

24
For standard library implementations:
25

26
```scala
27
import cats.effect.std._
28
```
29

30
## Basic Usage
31

32
```scala
33
import cats.effect._
34

35
object MyApp extends IOApp {
36
  def run(args: List[String]): IO[ExitCode] = {
37
    for {
38
      _ <- IO.println("Hello, Cats Effect!")
39
      
40
      // Create a concurrent reference
41
      ref <- Ref.of[IO, Int](0)
42
      
43
      // Start concurrent fibers
44
      fiber1 <- (ref.update(_ + 1) >> IO.sleep(100.millis)).start
45
      fiber2 <- (ref.update(_ + 10) >> IO.sleep(50.millis)).start
46
      
47
      // Wait for both to complete
48
      _ <- fiber1.join.void
49
      _ <- fiber2.join.void
50
      
51
      // Read final value
52
      result <- ref.get
53
      _ <- IO.println(s"Final value: $result")
54
      
55
      // Resource management example
56
      _ <- Resource.make(IO.println("Acquiring resource"))(_ => IO.println("Releasing resource"))
57
        .use(_ => IO.println("Using resource"))
58
        
59
    } yield ExitCode.Success
60
  }
61
}
62
```
63

64
## Architecture
65

66
Cats Effect is built around several key architectural components:
67

68
- **Effect Typeclasses**: Abstract interfaces defining capabilities (Sync, Async, Concurrent, Temporal)
69
- **IO Monad**: Concrete implementation providing referentially transparent, composable effects
70
- **Fiber System**: Lightweight green threads for concurrent execution with structured concurrency
71
- **Resource Management**: Automatic resource cleanup with `Resource` and bracket operations
72
- **Runtime System**: High-performance work-stealing thread pool with configurable execution contexts
73

74
The library follows the typeclass pattern from category theory, providing increasingly powerful abstractions:
75
`Functor < Applicative < Monad < MonadError < MonadCancel < Spawn < Concurrent < Temporal < Async`
76

77
## Capabilities
78

79
### Core IO Operations
80

81
The IO monad and essential operations for building purely functional applications. Includes basic IO operations, error handling, and composition.
82

83
```scala { .api }
84
// IO construction and basic operations
85
def IO.pure[A](value: A): IO[A]
86
def IO.delay[A](thunk: => A): IO[A] 
87
def IO.blocking[A](thunk: => A): IO[A]
88
def IO.async[A](k: (Either[Throwable, A] => Unit) => IO[Option[IO[Unit]]]): IO[A]
89

90
// Error handling
91
def attempt: IO[Either[Throwable, A]]
92
def handleErrorWith[AA >: A](f: Throwable => IO[AA]): IO[AA]
93
def guarantee(finalizer: IO[Unit]): IO[A]
94

95
// Composition
96
def flatMap[B](f: A => IO[B]): IO[B]
97
def map[B](f: A => B): IO[B]
98
```
99

100
[Core IO Operations](./core-io.md)
101

102
### Concurrency and Fibers
103

104
Fiber-based concurrency with structured concurrency patterns. Provides fiber spawning, coordination, and cancellation.
105

106
```scala { .api }
107
// Fiber operations
108
def start: IO[Fiber[IO, Throwable, A]]
109
def race[B](other: IO[B]): IO[Either[A, B]]
110
def both[B](other: IO[B]): IO[(A, B)]
111
def background: Resource[IO, IO[Outcome[IO, Throwable, A]]]
112

113
// Coordination primitives
114
def Ref.of[F[_], A](initial: A): F[Ref[F, A]]
115
def Deferred[F[_], A]: F[Deferred[F, A]]
116
```
117

118
[Concurrency and Fibers](./concurrency.md)
119

120
### Resource Management
121

122
Safe resource acquisition, usage, and cleanup with the `Resource` data type and bracket patterns.
123

124
```scala { .api }
125
sealed abstract class Resource[F[_], +A] {
126
  def use[B](f: A => F[B]): F[B]
127
  def allocated: F[(A, F[Unit])]
128
  def map[B](f: A => B): Resource[F, B]
129
  def flatMap[B](f: A => Resource[F, B]): Resource[F, B]
130
}
131

132
def Resource.make[F[_], A](acquire: F[A])(release: A => F[Unit]): Resource[F, A]
133
def bracket[A, B](acquire: F[A])(use: A => F[B])(release: A => F[Unit]): F[B]
134
```
135

136
[Resource Management](./resources.md)
137

138
### Time and Scheduling
139

140
Time-based operations including delays, timeouts, and scheduling.
141

142
```scala { .api }
143
def IO.sleep(duration: Duration): IO[Unit]
144
def timeout(duration: Duration): IO[A]
145
def timeoutTo[AA >: A](duration: Duration, fallback: IO[AA]): IO[AA]
146
def delayBy(duration: Duration): IO[A]
147
def timed: IO[(Duration, A)]
148
```
149

150
[Time and Scheduling](./time.md)
151

152
### Standard Library
153

154
Standard implementations of common concurrent data structures and system integration.
155

156
```scala { .api }
157
// Queues
158
abstract class Queue[F[_], A] {
159
  def offer(a: A): F[Unit]
160
  def take: F[A]  
161
  def size: F[Int]
162
}
163

164
// Synchronization
165
abstract class Semaphore[F[_]] {
166
  def acquire: F[Unit]
167
  def release: F[Unit]
168
  def withPermit[A](fa: F[A]): F[A]
169
}
170

171
// System integration
172
trait Console[F[_]] {
173
  def println(line: Any): F[Unit]
174
  def readLine: F[String]
175
}
176
```
177

178
[Standard Library](./std.md)
179

180
### Runtime and Execution
181

182
Runtime configuration, unsafe operations, and application patterns.
183

184
```scala { .api }
185
final class IORuntime {
186
  def unsafeRunSync[A](io: IO[A]): A
187
  def unsafeRunAsync[A](io: IO[A])(cb: Either[Throwable, A] => Unit): Unit
188
  def shutdown(): Unit
189
}
190

191
trait IOApp {
192
  def run(args: List[String]): IO[ExitCode]
193
}
194
```
195

196
[Runtime and Execution](./runtime.md)
197

198
## Types
199

200
### Core Effect Types
201

202
```scala { .api }
203
// Primary effect types
204
sealed abstract class IO[+A]
205
sealed abstract class SyncIO[+A] 
206
sealed abstract class Resource[F[_], +A]
207

208
// Coordination primitives
209
abstract class Ref[F[_], A] {
210
  def get: F[A]
211
  def set(a: A): F[Unit]
212
  def modify[B](f: A => (A, B)): F[B]
213
}
214

215
abstract class Deferred[F[_], A] {
216
  def get: F[A]
217
  def complete(a: A): F[Unit]
218
}
219

220
// Fiber execution results
221
sealed trait Outcome[F[_], E, A]
222
final case class Succeeded[F[_], E, A](fa: F[A]) extends Outcome[F, E, A]
223
final case class Errored[F[_], E, A](e: E) extends Outcome[F, E, A]
224
final case class Canceled[F[_], E, A]() extends Outcome[F, E, A]
225

226
// Fiber handles
227
trait Fiber[F[_], E, A] {
228
  def cancel: F[Unit]
229
  def join: F[Outcome[F, E, A]]
230
}
231
```
232

233
### Type Aliases
234

235
```scala { .api }
236
type OutcomeIO[A] = Outcome[IO, Throwable, A]
237
type FiberIO[A] = Fiber[IO, Throwable, A]
238
type ResourceIO[A] = Resource[IO, A]
239
```