0
# Cats Effect
1

2
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.
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" % "2.5.5"`
10
- **Documentation**: https://typelevel.org/cats-effect/
11

12
## Core Imports
13

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

19
For specific components:
20

21
```scala
22
import cats.effect.{IO, Resource, Sync, Async, Concurrent}
23
import cats.effect.concurrent.{Ref, Deferred, Semaphore, MVar}
24
```
25

26
## Basic Usage
27

28
```scala
29
import cats.effect._
30

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

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

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

48
fileResource.use { reader =>
49
  IO(reader.readLine()).flatMap(line => IO(println(line)))
50
}
51
```
52

53
## Architecture
54

55
Cats Effect is built around several key architectural components:
56

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

64
## Capabilities
65

66
### IO Monad
67

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

70
```scala { .api }
71
// Core IO construction
72
object IO {
73
  def pure[A](a: A): IO[A]
74
  def delay[A](body: => A): IO[A] 
75
  def defer[A](thunk: => IO[A]): IO[A]
76
  def async[A](k: (Either[Throwable, A] => Unit) => Unit): IO[A]
77
  def raiseError[A](e: Throwable): IO[A]
78
  def never[A]: IO[Nothing]
79
}
80

81
// Core IO operations
82
abstract class IO[+A] {
83
  def map[B](f: A => B): IO[B]
84
  def flatMap[B](f: A => IO[B]): IO[B]
85
  def attempt: IO[Either[Throwable, A]]
86
  def handleErrorWith[AA >: A](f: Throwable => IO[AA]): IO[AA]
87
  def start: IO[Fiber[IO, A]]
88
  def unsafeRunSync(): A
89
  def unsafeRunAsync(cb: Either[Throwable, A] => Unit): Unit
90
}
91
```
92

93
[IO Monad Operations](./io.md)
94

95
### Effect Type Classes
96

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

99
```scala { .api }
100
trait Sync[F[_]] extends Bracket[F, Throwable] {
101
  def delay[A](thunk: => A): F[A]
102
  def defer[A](fa: => F[A]): F[A]
103
}
104

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

110
trait Concurrent[F[_]] extends Async[F] {
111
  def start[A](fa: F[A]): F[Fiber[F, A]]
112
  def race[A, B](fa: F[A], fb: F[B]): F[Either[A, B]]
113
  def cancelable[A](k: (Either[Throwable, A] => Unit) => CancelToken[F]): F[A]
114
}
115
```
116

117
[Effect Type Classes](./type-classes.md)
118

119
### Concurrent Primitives
120

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

123
```scala { .api }
124
abstract class Ref[F[_], A] {
125
  def get: F[A]
126
  def set(a: A): F[Unit] 
127
  def modify[B](f: A => (A, B)): F[B]
128
  def update(f: A => A): F[Unit]
129
}
130

131
abstract class Deferred[F[_], A] {
132
  def get: F[A]
133
  def complete(a: A): F[Unit]
134
}
135

136
abstract class Semaphore[F[_]] {
137
  def acquire: F[Unit]
138
  def release: F[Unit]
139
  def withPermit[A](t: F[A]): F[A]
140
}
141
```
142

143
[Concurrent Primitives](./concurrency.md)
144

145
### Resource Management
146

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

149
```scala { .api }
150
abstract class Resource[F[_], A] {
151
  def use[B](f: A => F[B]): F[B]
152
  def allocated: F[(A, F[Unit])]
153
  def map[B](f: A => B): Resource[F, B]
154
  def flatMap[B](f: A => Resource[F, B]): Resource[F, B]
155
}
156

157
object Resource {
158
  def make[F[_], A](acquire: F[A])(release: A => F[Unit]): Resource[F, A]
159
  def fromAutoCloseable[F[_], A <: AutoCloseable](fa: F[A]): Resource[F, A]
160
  def liftF[F[_], A](fa: F[A]): Resource[F, A]
161
}
162
```
163

164
[Resource Management](./resources.md)
165

166
### Application Framework
167

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

170
```scala { .api }
171
trait IOApp {
172
  def run(args: List[String]): IO[ExitCode]
173
  
174
  implicit def contextShift: ContextShift[IO]
175
  implicit def timer: Timer[IO]
176
  
177
  final def main(args: Array[String]): Unit
178
}
179

180
case class ExitCode(code: Int)
181
object ExitCode {
182
  val Success: ExitCode
183
  val Error: ExitCode
184
}
185
```
186

187
[Application Framework](./application.md)