├── .scalafmt.conf
├── project
    ├── build.properties
    └── plugins.sbt
├── docs
    ├── concurrency-thread-pools.png
    ├── typeclasses-cheat-sheet.jpeg
    ├── typeclasses-cheat-sheet.png
    └── index.html
├── slides
    └── mdoc
    │   ├── concurrency-thread-pools.png
    │   ├── typeclasses-cheat-sheet.jpeg
    │   └── index.html
├── core
    └── src
    │   └── main
    │       └── scala
    │           └── daenyth
    │               └── talk
    │                   └── ce
    │                       ├── Foo.scala
    │                       └── MdocConsoleWorkaround.scala
├── .gitignore
└── README.md


/.scalafmt.conf:
--------------------------------------------------------------------------------
1 | version = "2.0.1"
2 | 


--------------------------------------------------------------------------------
/project/build.properties:
--------------------------------------------------------------------------------
1 | sbt.version=1.5.5
2 | 


--------------------------------------------------------------------------------
/project/plugins.sbt:
--------------------------------------------------------------------------------
1 | addSbtPlugin("org.scalameta" % "sbt-mdoc" % "2.2.22")


--------------------------------------------------------------------------------
/docs/concurrency-thread-pools.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/Daenyth/intro-cats-effect/HEAD/docs/concurrency-thread-pools.png


--------------------------------------------------------------------------------
/docs/typeclasses-cheat-sheet.jpeg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/Daenyth/intro-cats-effect/HEAD/docs/typeclasses-cheat-sheet.jpeg


--------------------------------------------------------------------------------
/docs/typeclasses-cheat-sheet.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/Daenyth/intro-cats-effect/HEAD/docs/typeclasses-cheat-sheet.png


--------------------------------------------------------------------------------
/slides/mdoc/concurrency-thread-pools.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/Daenyth/intro-cats-effect/HEAD/slides/mdoc/concurrency-thread-pools.png


--------------------------------------------------------------------------------
/slides/mdoc/typeclasses-cheat-sheet.jpeg:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/Daenyth/intro-cats-effect/HEAD/slides/mdoc/typeclasses-cheat-sheet.jpeg


--------------------------------------------------------------------------------
/core/src/main/scala/daenyth/talk/ce/Foo.scala:
--------------------------------------------------------------------------------
1 | package daenyth.talk.ce
2 | 
3 | sealed trait Foo extends Product with Serializable
4 | 
5 | object Foo {
6 |   case class FooInt(i: Int) extends Foo
7 |   case class FooString(s: String) extends Foo
8 | }


--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
 1 | ## IntelliJ files to ignore
 2 | *.iml
 3 | *.iws
 4 | *.ipr
 5 | .idea
 6 | .idea/*
 7 | 
 8 | ## NetBeans files to ignore
 9 | .*_nb
10 | 
11 | # bench output
12 | *.csv
13 | 
14 | ## scala specific files to ignore
15 | *.class
16 | target/
17 | project/project/
18 | _site/
19 | 
20 | .metals/
21 | .bloop/
22 | project/.bloop/
23 | .bsp/
24 | 


--------------------------------------------------------------------------------
/core/src/main/scala/daenyth/talk/ce/MdocConsoleWorkaround.scala:
--------------------------------------------------------------------------------
 1 | package daenyth.talk.ce
 2 | 
 3 | import cats.effect.IO
 4 | 
 5 | import cats.effect.unsafe.implicits.global
 6 | 
 7 | object MdocConsoleWorkaround {
 8 |   implicit class IOOps[A](fa: IO[A]) {
 9 |     def unsafeRunSyncWithRedirect(): A = {
10 |       val oldOut = System.out
11 |       val newOut = Console.out // important to do this on the calling thread!
12 |       try {
13 |         System.setOut(newOut)
14 |         fa.unsafeRunSync()
15 |       } finally System.setOut(oldOut)
16 |     }
17 |   }
18 | }
19 | 
20 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
 1 | # Intro to Cats-Effect
 2 | 
 3 | Cats Effect is a functional side effect library - I'll explain what that means, what it gives you, how to use it, and why you should care.
 4 | 
 5 | At Teikametrics we adopted this library in 2018, and I'll discuss how we approach application design using it, both from a green field perspective as well as the techniques we used to migrate a living codebase away from akka-streams without "the big rewrite".
 6 | 
 7 | ## Slides
 8 | 
 9 | [Available online](https://daenyth.github.io/intro-cats-effect/)
10 | 
11 | ## Video recording
12 | 
13 | The current version for Cats-Effect 3 is [on Vimeo](https://vimeo.com/586829749)
14 | 
15 | The older version for Cats-Effect 2 is [on YouTube](https://www.youtube.com/watch?v=83pXEdCpY4A)
16 | 
17 | ## Building
18 | 
19 | Code in `core` module is accessible in your slides
20 | 
21 | Raw slides are in `slides/tut/index.html`
22 | 
23 | ### How to compile slides
24 | 
25 | run `sbt slides/mdoc` to compile slides using [mdoc][mdoc]. 
26 | You can then view the slides by opening `docs/index.html` in your browser.
27 | 
28 | ### How to publish slides with github
29 | 
30 | When you are ready push the repository to github (including the compiled slides in `docs`).
31 | Then go to project settings -> GitHub Pages and select `master branch /docs folder` for 
32 | the source of github pages.
33 | 
34 | 
35 | 
36 | This project was generated using [Giter8][g8] with template [presentation.g8][presentation.g8]
37 | 
38 | 
39 | [g8]: http://www.foundweekends.org/giter8/
40 | [presentation.g8]: https://github.com/julien-truffaut/presentation.g8
41 | [mdoc]: https://scalameta.org/mdoc/
42 | 


--------------------------------------------------------------------------------
/slides/mdoc/index.html:
--------------------------------------------------------------------------------
  1 | <!DOCTYPE html>
  2 | <html>
  3 | 
  4 | <head>
  5 |   <title>Intro to Cats-Effect</title>
  6 |   <meta charset="utf-8">
  7 |   <style>
  8 |     @import url(https://fonts.googleapis.com/css?family=Yanone+Kaffeesatz);
  9 |     @import url(https://fonts.googleapis.com/css?family=Droid+Serif:400,700,400italic);
 10 |     @import url(https://fonts.googleapis.com/css?family=Ubuntu+Mono:400,700,400italic);
 11 | 
 12 |     body {
 13 |       font-family: 'Droid Serif', 'Helvetica';
 14 |       /*line-height: 1.25em;*/
 15 |     }
 16 | 
 17 |     li {
 18 |       margin: 10px 0;
 19 |     }
 20 | 
 21 |     h1,
 22 |     h2,
 23 |     h3 {
 24 |       font-family: 'Yanone Kaffeesatz', 'Gill Sans';
 25 |       font-weight: normal;
 26 |     }
 27 | 
 28 |     img {
 29 |       width: 100%;
 30 |       height: 100%;
 31 |       object-fit: contain;
 32 |     }
 33 | 
 34 |     .remark-code,
 35 |     .remark-inline-code {
 36 |       font-family: 'Ubuntu Mono', 'Consolas', 'Courier New';
 37 |     }
 38 |   </style>
 39 | </head>
 40 | 
 41 | <body>
 42 |   <textarea id="source">
 43 | 
 44 | class: center, middle
 45 | 
 46 | # Intro to Cats-Effect
 47 | Gavin Bisesi • `@Daenyth`
 48 | 
 49 | @47Degrees
 50 | 
 51 | ???
 52 | 
 53 | Questions at the end
 54 | 
 55 | ---
 56 | # What is a "Functional side effect" library?
 57 | 
 58 | --
 59 | 
 60 | Programming with "pure functions", aka programming with *Referential Transparency*
 61 | 
 62 | ---
 63 | # Referential Transparency
 64 | 
 65 | --
 66 | 
 67 | A property of *expressions* (not statements (`return`) or declarations (`def`, `class`))
 68 | 
 69 | --
 70 | 
 71 | > The result of any expression can be replaced by its definition without changing the meaning
 72 | 
 73 | ---
 74 | # Referential Transparency
 75 | > The result of any expression can be replaced by its definition without changing the meaning
 76 | 
 77 | ```scala mdoc
 78 | val two = 1 + 1
 79 | 
 80 | two
 81 | 1 + 1
 82 | 
 83 | ```
 84 | 
 85 | 👍
 86 | 
 87 | ---
 88 | # Referential Transparency
 89 | > The result of any expression can be replaced by its definition without changing the meaning
 90 | 
 91 | ```scala mdoc
 92 | val hello = println("hello")
 93 | 
 94 | hello
 95 | println("hello")
 96 | 
 97 | ```
 98 | 
 99 | 👎
100 | 
101 | ---
102 | # Who cares? Why use FP?
103 | 
104 | Why program with Referential Transparency?
105 | 
106 | RT means we can:
107 | - Read code and know what it means and what it does, without reading the rest of the codebase
108 | - Change existing code without breaking it  
109 | 
110 | ---
111 | # Who cares? Why use FP?
112 | 
113 | In other words:
114 | 
115 | We use FP because we want a codebase that
116 | - Developers can read and understand
117 | - Can be changed without breaking things
118 | 
119 | (among other reasons)
120 | 
121 | ---
122 | # Functional Programming - Combinators
123 | 
124 | *Combinators* are composable building block functions that modify some input in a reusable way
125 | - `map`
126 | - `filter`
127 | 
128 | ---
129 | # Some setup
130 | ```scala mdoc:silent
131 | import cats._
132 | import cats.syntax.all._
133 | import cats.effect._
134 | import cats.effect.implicits._
135 | import scala.concurrent._
136 | import scala.concurrent.duration._
137 | 
138 | import ExecutionContext.Implicits.{global => futureEC}
139 | 
140 | import cats.effect.unsafe.implicits.{global => ioRuntime}
141 | 
142 | // Custom `unsafeRunSync` for mdoc reasons
143 | import daenyth.talk.ce.MdocConsoleWorkaround._
144 | def yolo[A](description: IO[A]) = description.unsafeRunSyncWithRedirect()
145 | 
146 | ```
147 | 
148 | ```scala mdoc:invisible
149 | import java.util.UUID
150 | trait Database
151 | ```
152 | 
153 | ---
154 | # cats-effect `IO`
155 | 
156 | A lot like scala `Future` at first glance
157 | - `apply` to wrap blocks of code
158 | - `map`, `flatMap`
159 | - Don't use `Await` with `Future`; don't use `unsafeRun*` with `IO`
160 | 
161 | ```scala mdoc
162 | val rndUUID: IO[UUID] = IO(UUID.randomUUID())
163 | val helloIO = rndUUID.flatMap(uuid => IO(println(s"Hello $uuid")))
164 | 
165 | yolo(helloIO >> helloIO)
166 | ```
167 | 
168 | ---
169 | # `IO[A]` values
170 | 
171 | `IO[A]` describes a computation that will:
172 | - Eventually produce a value of `A`, or
173 | - Fail with a `Throwable`, or
174 | - Never complete
175 | 
176 | ```scala mdoc:compile-only
177 | def game = for {
178 |   _ <- IO.println("Guess a number")
179 |   n <- IO.readLine
180 |   _ <- if (n == 10) IO.println("Yay!")
181 |        else IO.raiseError(new Exception("wrong"))
182 | } yield ()
183 | 
184 | def clock: IO[Unit] =
185 |   IO.sleep(1.minute) >>
186 |     Clock[IO].realTimeInstant.flatMap(IO.println) >>
187 |     clock
188 | ```
189 | 
190 | ---
191 | # Fibers
192 | 
193 | `IO` is based on the `Fiber` abstraction for low-level concurrency
194 | ```scala
195 | // Simplified
196 | trait IO[A] {
197 |   def start: Fiber[A]
198 | }
199 | trait Fiber[A] {
200 |   def cancel: F[Unit]
201 |   def join: F[Outcome[F, Throwable, A]]
202 | }
203 | ```
204 | 
205 | A low level building block - you usually don't need to interact with them directly
206 | 
207 | ---
208 | # `IO` Execution
209 | 
210 | - Can describe both concurrency and parallelism
211 | - Uses N:M green-threading
212 |   - Cheap: thousands of concurrent `Fiber`s are not a problem
213 | - Nonblocking asynchronous execution
214 |   - Run as as few as 1 thread (including Scala.JS)
215 | 
216 | ---
217 | # `IO` Concurrency
218 | 
219 | Both low-level `Fibers` and high-level combinators
220 | - Forking: `io.start`, `Fiber`
221 | - Cancellation (low level): `Fiber#cancel`
222 | - Cancellation (high level):
223 |   - `IO.race(first, second)` - concurrently execute, return the winner and cancel the loser,
224 |   - `io.timeout(duration)` - fails with `TimeoutException` if not complete within `duration`
225 |   - `io.timeoutTo(duration, fallbackIO)` - Execute `fallbackIO` if `io` is not complete within `duration`
226 | - Nonblocking asynchronous sleep: `IO.sleep(duration)`
227 | - Concurrent execution: `start`, `listOfIO.parSequence`, `(ioA, ioB).parTupled`
228 | 
229 | ---
230 | # Resource management
231 | 
232 | `Resource[IO, A]` describes the ability to initialize and release a resource
233 | - Similar to `try`/`finally`, but composable and referentially transparent
234 |   - `catch`/`finally` aren't transparent - they don't talk about *return values*.
235 | - Allows tracking resource lifetime at the type level
236 |   - Function accepting `Resource[IO, A]` parameter will acquire and release internally
237 |   - Function accepting `A` reuses the live value
238 | - Allows *guaranteed* finalization
239 |   - Whether the function given to `use` completes, fails, or is cancelled, the Resource is closed. Will not leak.
240 | 
241 | ---
242 | # cats-effect typeclasses
243 | 
244 | All the capabilities that `IO` exposes are described by typeclasses, allowing more generic code and multi-library compatibility.
245 | 
246 | This talk focus on `IO` and not the typeclasses
247 | 
248 | ---
249 | # cats-effect typeclasses
250 | 
251 | <img src="typeclasses-cheat-sheet.jpeg">
252 | 
253 | ---
254 | # `IO` vs `Future` - Overview
255 | 
256 | Actions:
257 | - `IO` is a value that describes an action (possibly asynchronous)
258 | - `Future` is a handle to the result of an already-running action (possibly asynchronous)
259 | 
260 | ---
261 | # `IO` vs `Future` - Speed
262 | 
263 | - `IO` is optimized for throughput
264 |   - Thread shift on demand
265 |   - Has utilities for introducing manual shifts for fairness
266 |   - Benchmarks faster for most workloads
267 |   - Work-stealing runtime implementation inspired by Rust's Tokio
268 | - `Future` is optimized for fairness
269 |   - Thread shift every single `map`/`flatMap` (hence implicit `ec`)
270 |   - Can only be configured using a specialized `ec` argument
271 | 
272 | ---
273 | # `IO` vs `Future` - Cancellation
274 | 
275 | - `Future[A]` can't be cancelled - once constructed, it can't be stopped
276 |   - Wasted resources
277 | - `IO[A]` can be concurrently forked, and then either `join`ed or `cancel`ed  
278 |   - There are high-level constructs around this in cats-effect
279 |   - More sophisticated abstractions built on top can be found in other libraries
280 | 
281 | ---
282 | # `IO` vs `Future` - Concurrency
283 | 
284 | - Future has concurrency depending where you invoke functions
285 | - IO has structured concurrency via explicit combinators
286 | 
287 | ---
288 | # `IO` vs `Future` - Concurrency with Future
289 | ```scala mdoc:silent:nest
290 | // Sequential execution
291 | def jobOne: Future[Int] = Future(???)
292 | def jobTwo: Future[String] = Future(???)
293 | 
294 | jobOne.flatMap(i => jobTwo.map(s => (i, s)))
295 | ```
296 | 
297 | ```scala mdoc:silent:nest
298 | // Concurrent execution
299 | val jobOne: Future[Int] = Future(???)
300 | val jobTwo: Future[String] = Future(???)
301 | 
302 | jobOne.flatMap(i => jobTwo.map(s => (i, s)))
303 | ```
304 | 
305 | ---
306 | # `IO` vs `Future` - Concurrency with Future
307 | 
308 | 
309 | Does this expression evaluate concurrently or sequentially?
310 | 
311 | ```scala mdoc:silent
312 | jobOne.flatMap(i => jobTwo.map(s => (i, s)))
313 | ```
314 | 
315 | Impossible to tell - have to read the implementation details
316 | 
317 | ---
318 | # `IO` vs `Future` - Concurrency with `IO`
319 | 
320 | ```scala mdoc:silent:nest
321 | val jobOne: IO[Int] = IO(???)
322 | val jobTwo: IO[String] = IO(???)
323 | 
324 | // Sequential execution
325 | jobOne.flatMap(i => jobTwo.map(s => (i, s)))
326 | // Also Sequential
327 | val result1: IO[(Int, String)] = (jobOne, jobTwo).tupled
328 | 
329 | // Concurrent execution (manually)
330 | for {
331 |   j1Fiber <- jobOne.start
332 |   j2Fiber <- jobTwo.start
333 |   i <- j1Fiber.join
334 |   s <- j2Fiber.join
335 | } yield (i, s)
336 | 
337 | // Concurrent execution (higher level)
338 | val result2: IO[(Int, String)] = (jobOne, jobTwo).parTupled
339 | 
340 | ```
341 | 
342 | ---
343 | # A tour of cats-effect
344 | 
345 | - Utilities around Thread pools, controlling where and when things execute
346 |   - Temporal, Clock
347 | - Concurrency primitives
348 |   - Semaphore - Has `N` permits, can acquire or release permits as needed. Acquire blocks until permits are available
349 |   - Ref - Lock-free concurrency-safe mutable shared memory. A pure replacement for `var`
350 |   - Deferred - A pure promise. Can complete with a value or get the completed value. Get blocks until complete.
351 |   - And more!
352 | 
353 | 
354 | ---
355 | # A tour of cats-effect
356 | 
357 | - Dispatcher - Allows you to have controlled regions of `unsafeRun*` methods, for wrapping imperative libraries
358 | 
359 | - `IOApp` - Whole "pure" applications
360 |   - Handles all the initialization, cancellation hooks, jvm actions so you can write your main method in `IO`
361 | 
362 | - IORuntime
363 |   - An optimized work-stealing compute-based Execution context, bundled with an appropriate pool for thread-blocking work and a high-priority scheduler pool.
364 | 
365 | ---
366 | # Thread pool management
367 | 
368 | <img src="concurrency-thread-pools.png">
369 | 
370 | ---
371 | # Thread pool management - `ExecutionContext.global`
372 | 
373 | `global` isn't an ideal choice.
374 | - Designed for mixed cpu + blocking-io work in a single pool
375 | - Optimal for neither
376 | - CPU-bound work suffers in performance from cpu context shifting; `global` creates more threads than cpu cores
377 | - I/O-bound work can preempt cpu-bound work if `global` decides not to make a new Thread
378 | - This applies for all fork-join pools - even if you don't use cats-effect.
379 | 
380 | ---
381 | # Thread pool management - 3 Pool Model
382 | 
383 | - Computation: Fixed size pool for cpu work
384 |   - Normal `IO` values run here
385 | - Blocking IO: Cached thread pool for thread-blocking work
386 |   - Wrap side-effecting code with `IO.blocking` or `IO.interruptible` (if you can `Thread.interrupt()` it)
387 | - Event Dispatcher: High-priority pool for scheduling and timers
388 |  - Used to schedule asynchronous `sleep` calls
389 | 
390 | ---
391 | # Blocking threads
392 | 
393 | Blocking threads should be avoided
394 | - Your cpu core is doing no work, waiting for a result while it could be computing something else
395 | - It reduces your bandwidth for concurrent work
396 | 
397 | Instead of `IO.apply`, use:
398 | - `IO.blocking` to wrap thread-blocking code
399 | - `IO.interruptible` if that code will behave well under `Thread.interrupt()`
400 | 
401 | ---
402 | # Blocking threads - `IO.blocking`
403 | - `IO.blocking` to wrap thread-blocking code
404 | 
405 | ```scala mdoc:silent
406 | def fos: java.io.FileOutputStream = ???
407 | def bytes: Array[Byte] = ???
408 | val writeFile: IO[Unit] = IO.blocking(fos.write(bytes))
409 | ```
410 | 
411 | ---
412 | # Blocking Threads - `IO.interruptible`
413 | - `IO.interruptible` if that code will behave well under `Thread.interrupt()`
414 | 
415 | ```scala mdoc
416 | val tenMinutes = 10 * 60 * 1000
417 | def blockingTask = IO.interruptible(many = false)(Thread.sleep(tenMinutes))
418 | def printTime = Clock[IO].realTimeInstant.flatMap(t => IO.println(s"It is now $t"))
419 | yolo(for {
420 |   _ <- printTime
421 |   task <- blockingTask.start
422 |   _ <- IO.sleep(2.seconds)
423 |   _ <- task.cancel
424 |   _ <- printTime
425 | } yield ())
426 | 
427 | ```
428 | 
429 | ---
430 | # Time
431 | 
432 | `Temporal` and `Clock`
433 |  - Nonblocking async sleep: `IO.sleep(duration)` (or `Temporal[IO].sleep(duration)`)
434 |  - Get the time: `Clock[IO].realTime`, `.realTimeInstant`
435 | 
436 | ```scala mdoc
437 | // Time since epoch
438 | yolo(Clock[IO].realTime)
439 | 
440 | // Current Instant
441 | yolo(Clock[IO].realTimeInstant)
442 | 
443 | // Monotonically incrementing clock
444 | yolo(Clock[IO].monotonic)
445 | ```
446 | 
447 | ---
448 | # Applications
449 | 
450 | `IOApp` for your "main" classes
451 | 
452 | ```scala mdoc:compile-only
453 | object MyMain extends IOApp {
454 |   def run(args: List[String]): IO[ExitCode] = {
455 |     val myAppResource = 
456 |       for {
457 |         _ <- Resource.eval(IO.println("hello cats"))
458 |         db <- getDatabase
459 |         result <- Resource.eval(myAppLogic(db))
460 |         _ <- Resource.eval(IO.println(s"got $result"))
461 |       } yield ()
462 |     
463 |       myAppResource.useForever.as(ExitCode.Success)
464 |     }
465 | 
466 | 
467 |   def getDatabase: Resource[IO, Database] = ???
468 |   def myAppLogic(db: Database): IO[Int] = ???
469 | } 
470 | ```
471 | 
472 | ---
473 | # But I already have an application!
474 | 
475 | `IO` can be introduced to a codebase using `Future` or using its own "main" class.
476 | 
477 | ---
478 | # Calling `Future` from `IO`
479 | 
480 | Tip: Instantiating a `Future` value is a side effect, so it gets wrapped with `IO.apply`
481 | 
482 | ```scala mdoc:silent
483 | def existingLogic(x: Int): Future[Int] = ???
484 | def moreLogic(y: Int): IO[Int] =
485 |   for {
486 |     xResult <- IO.fromFuture(IO(existingLogic(42))) 
487 |   } yield xResult + y
488 | ```
489 | 
490 | ---
491 | 
492 | # Calling `IO` from `Future`
493 | 
494 | ```scala mdoc:silent
495 | import cats.effect.unsafe
496 | 
497 | trait MyTrait { def doWork: Future[Int] }
498 | 
499 | // NB: You can use `IORuntime.global`, but it's more flexible to take a parameter
500 | class MyTraitImpl(implicit ioRuntime: unsafe.IORuntime) extends MyTrait {
501 |   override def doWork: Future[Int] =
502 |     ioLogic.map(_.length).unsafeToFuture()
503 |   
504 |   def ioLogic: IO[String] = ???
505 | }
506 | ```
507 | 
508 | ---
509 | # Converting to IO - Sequential imperative
510 | 
511 | Sequential code:
512 | - Replace `;` with `flatMap`
513 | 
514 | ```scala mdoc:silent:nest
515 | 
516 | // Imperative
517 | def oneStep(): Unit = println("one")
518 | def anotherStep(): Unit = println("two")
519 | 
520 | oneStep()
521 | anotherStep()
522 | 
523 | // IO
524 | def oneStepIO(): IO[Unit] = IO(println("one"))
525 | def anotherStepIO(): IO[Unit] = IO(println("two"))
526 | 
527 | for {
528 |   _ <- oneStepIO()
529 |   _ <- anotherStepIO()
530 | } yield ()
531 | ```
532 | 
533 | ---
534 | # Converting to `IO` - `Future` code
535 | 
536 | - `Future.apply` -> `IO.apply`
537 | - `Future.successful` -> `IO.pure`
538 | - `Future.failed` -> `IO.raiseError`
539 | - Implicit `Future` concurrency -> Explicit concurrency combinators
540 | - Side effects in `map` -> explicit effects with `IO(sideEffect())` in `flatMap`
541 | 
542 | ---
543 | # Converting to `IO` - imperative code and mutation
544 | 
545 | - `new` on a stateful class is stateful; wrap it in `IO`
546 | - Reading or writing to stateful classes is stateful; wrap it in `IO`
547 | - Imperative setup/close methods -> `Resource.make`
548 | - Use `Random[IO]` for pure, performant, concurrecy-safe randomness. Avoid `IO(Random.xyz())`
549 | - Use `Clock[IO]` for pure access to time.
550 | - Two sequential imperative lines -> two `IO` expressions combined with `flatMap`
551 | - "I need a `Foo` value but I have `IO[Foo]`, how do I get it out?
552 |   - You never "get it out"; use `flatMap`; `getFooIO.flatMap(foo => useFooIO(foo))`
553 | 
554 | ---
555 | IO Examples
556 | 
557 | ```scala mdoc:silent
558 | import cats.effect.std.Random
559 | 
560 | val ioExample = for {
561 |   _ <- IO.println("Hello cats!") // Uses the `Console[IO]` capability
562 | 
563 |   time <- Clock[IO].realTimeInstant
564 |   _ <- IO.println(s"It is now $time")
565 | 
566 |   rnd <- Random.scalaUtilRandom[IO]
567 |   _ <- rnd.nextInt.flatMap(n => IO.println(s"Your lucky number is: $n"))
568 | 
569 | } yield ()
570 | ```
571 | 
572 | ```scala mdoc
573 | yolo(ioExample)
574 | ```
575 | 
576 | ---
577 | # Converting to `IO` - general tips
578 | - Sometimes you'll want to `import cats.syntax.all._` for generic combinators (eg `tupled`, `handleError`)
579 | - Sometimes you'll want `import cats.effect.implicits._` for effect methods (eg `parSequence`, `parTupled`, `parMapN`)
580 | - To imperative run an `IO`, you need either an `IORuntime` or create a `Dispatcher[IO]`.
581 |    - `IORuntime.global` is fine for production! It's not like `ExecutionContext.global`
582 |    - `Dispatcher[F]` is cheap and works with "capability trait" style (aka "tagless final")
583 | - Understand the risks when using `.unsafe*` methods on `IO`
584 | 
585 | ---
586 | # Converting to `IO` - Common errors
587 | - Discarding an `IO` without flatMap-ing it
588 | - Side effects not wrapped `IO`, eg in `map`
589 | - Implicit `Future` concurrency
590 | - Use `-Ywarn-value-discard`!
591 |   - Optionally but recommended, set a lot of "save me from myself" flags at once using `sbt-tpolecat`
592 | 
593 | ---
594 | # Common Errors - discarding your `IO`
595 | 
596 | ```scala mdoc:compile-only
597 | def doStuff: IO[Unit] = ???
598 | def oops = {
599 |    // This IO never executes!
600 |    IO.println("About to do stuff")
601 |    doStuff
602 | }
603 | 
604 | def correct =
605 |   IO.println("About to do stuff")
606 |     .flatMap(_ => doStuff)
607 | ```
608 | 
609 | Tip: `fa.flatMap(_ => fb)` is so common it has an operator; `fa >> fb`
610 | 
611 | ---
612 | # Converting to `IO` - Application structure
613 | - Semantic interfaces, not mechanical ones
614 | - New code in `IO`
615 | - Interop where needed
616 | - Convert one class at a time
617 |   - You don't need to convert the whole project!
618 |   - Stop whenever you reach "good enough"
619 |   - Update code sections when you need to; if it's not broken and isn't being modified, leave it
620 | 
621 | ---
622 | # Cats-Effect
623 | 
624 | - Write code that doesn't break when you change it
625 | - Write reusable code that you know won't surprise you
626 | - Write code that can be understood in isolation
627 | - Gain access to an ecosystem of compatible, efficient, and easy to learn libraries
628 | 
629 | ---
630 | # Links and resources
631 | 
632 | - [Cats-Effect Concepts](https://typelevel.org/cats-effect/docs/concepts)
633 | - Typelevel [Discord chat](https://discord.gg/fChyzB4w)
634 | - [Documentation](https://typelevel.org/cats-effect/)
635 | - [Functional and Reactive Domain Modeling](https://www.manning.com/books/functional-and-reactive-domain-modeling)
636 |   - Book that goes into application design, in a style that meshes very cleanly with cats-effect
637 | - [Referential Transparency in the Wild](https://impurepics.com/posts/2018-07-13-referential-transparency-wild.html)
638 | - [Shared State in Functional Programming](https://typelevel.org/blog/2018/06/07/shared-state-in-fp.html) - More examples around `Resource` usage and simpler data sharing examples
639 | - [@impurepics](https://impurepics.com) is the author+owner of the graphics
640 |     
641 | 
642 | 
643 | ---
644 | class: center, middle
645 | 
646 | # Thanks!
647 | Code and slides at `daenyth/intro-cats-effect` on GitHub
648 | 
649 | ## Questions?
650 | 
651 | 
652 | 
653 | 
654 | 
655 |  </textarea>
656 |   <script src="remark-latest.min.js">
657 |   </script>
658 |   <script>
659 |     var slideshow = remark.create();
660 |   </script>
661 | </body>
662 | 
663 | </html>


--------------------------------------------------------------------------------
/docs/index.html:
--------------------------------------------------------------------------------
  1 | <!DOCTYPE html>
  2 | <html>
  3 | 
  4 | <head>
  5 |   <title>Intro to Cats-Effect</title>
  6 |   <meta charset="utf-8">
  7 |   <style>
  8 |     @import url(https://fonts.googleapis.com/css?family=Yanone+Kaffeesatz);
  9 |     @import url(https://fonts.googleapis.com/css?family=Droid+Serif:400,700,400italic);
 10 |     @import url(https://fonts.googleapis.com/css?family=Ubuntu+Mono:400,700,400italic);
 11 | 
 12 |     body {
 13 |       font-family: 'Droid Serif', 'Helvetica';
 14 |       /*line-height: 1.25em;*/
 15 |     }
 16 | 
 17 |     li {
 18 |       margin: 10px 0;
 19 |     }
 20 | 
 21 |     h1,
 22 |     h2,
 23 |     h3 {
 24 |       font-family: 'Yanone Kaffeesatz', 'Gill Sans';
 25 |       font-weight: normal;
 26 |     }
 27 | 
 28 |     img {
 29 |       width: 100%;
 30 |       height: 100%;
 31 |       object-fit: contain;
 32 |     }
 33 | 
 34 |     .remark-code,
 35 |     .remark-inline-code {
 36 |       font-family: 'Ubuntu Mono', 'Consolas', 'Courier New';
 37 |     }
 38 |   </style>
 39 | </head>
 40 | 
 41 | <body>
 42 |   <textarea id="source">
 43 | 
 44 | class: center, middle
 45 | 
 46 | # Intro to Cats-Effect
 47 | Gavin Bisesi • `@Daenyth`
 48 | 
 49 | @47Degrees
 50 | 
 51 | ???
 52 | 
 53 | Questions at the end
 54 | 
 55 | ---
 56 | # What is a "Functional side effect" library?
 57 | 
 58 | --
 59 | 
 60 | Programming with "pure functions", aka programming with *Referential Transparency*
 61 | 
 62 | ---
 63 | # Referential Transparency
 64 | 
 65 | --
 66 | 
 67 | A property of *expressions* (not statements (`return`) or declarations (`def`, `class`))
 68 | 
 69 | --
 70 | 
 71 | > The result of any expression can be replaced by its definition without changing the meaning
 72 | 
 73 | ---
 74 | # Referential Transparency
 75 | > The result of any expression can be replaced by its definition without changing the meaning
 76 | 
 77 | ```scala
 78 | val two = 1 + 1
 79 | // two: Int = 2
 80 | 
 81 | two
 82 | // res0: Int = 2
 83 | 1 + 1
 84 | // res1: Int = 2
 85 | ```
 86 | 
 87 | 👍
 88 | 
 89 | ---
 90 | # Referential Transparency
 91 | > The result of any expression can be replaced by its definition without changing the meaning
 92 | 
 93 | ```scala
 94 | val hello = println("hello")
 95 | // hello
 96 | 
 97 | hello
 98 | println("hello")
 99 | // hello
100 | ```
101 | 
102 | 👎
103 | 
104 | ---
105 | # Who cares? Why use FP?
106 | 
107 | Why program with Referential Transparency?
108 | 
109 | RT means we can:
110 | - Read code and know what it means and what it does, without reading the rest of the codebase
111 | - Change existing code without breaking it  
112 | 
113 | ---
114 | # Who cares? Why use FP?
115 | 
116 | In other words:
117 | 
118 | We use FP because we want a codebase that
119 | - Developers can read and understand
120 | - Can be changed without breaking things
121 | 
122 | (among other reasons)
123 | 
124 | ---
125 | # Functional Programming - Combinators
126 | 
127 | *Combinators* are composable building block functions that modify some input in a reusable way
128 | - `map`
129 | - `filter`
130 | 
131 | ---
132 | # Some setup
133 | ```scala
134 | import cats._
135 | import cats.syntax.all._
136 | import cats.effect._
137 | import cats.effect.implicits._
138 | import scala.concurrent._
139 | import scala.concurrent.duration._
140 | 
141 | import ExecutionContext.Implicits.{global => futureEC}
142 | 
143 | import cats.effect.unsafe.implicits.{global => ioRuntime}
144 | 
145 | // Custom `unsafeRunSync` for mdoc reasons
146 | import daenyth.talk.ce.MdocConsoleWorkaround._
147 | def yolo[A](description: IO[A]) = description.unsafeRunSyncWithRedirect()
148 | 
149 | ```
150 | 
151 | 
152 | ---
153 | # cats-effect `IO`
154 | 
155 | A lot like scala `Future` at first glance
156 | - `apply` to wrap blocks of code
157 | - `map`, `flatMap`
158 | - Don't use `Await` with `Future`; don't use `unsafeRun*` with `IO`
159 | 
160 | ```scala
161 | val rndUUID: IO[UUID] = IO(UUID.randomUUID())
162 | // rndUUID: IO[UUID] = Delay(
163 | //   <function0>,
164 | //   cats.effect.tracing.TracingEvent$StackTrace
165 | // )
166 | val helloIO = rndUUID.flatMap(uuid => IO(println(s"Hello $uuid")))
167 | // helloIO: IO[Unit] = FlatMap(
168 | //   Delay(<function0>, cats.effect.tracing.TracingEvent$StackTrace),
169 | //   <function1>,
170 | //   cats.effect.tracing.TracingEvent$StackTrace
171 | // )
172 | 
173 | yolo(helloIO >> helloIO)
174 | // Hello a1fb5ebf-11dc-410b-8258-4872e36cf32e
175 | // Hello fa27fb78-11a5-4a21-acff-f0c3028cbea8
176 | ```
177 | 
178 | ---
179 | # `IO[A]` values
180 | 
181 | `IO[A]` describes a computation that will:
182 | - Eventually produce a value of `A`, or
183 | - Fail with a `Throwable`, or
184 | - Never complete
185 | 
186 | ```scala
187 | def game = for {
188 |   _ <- IO.println("Guess a number")
189 |   n <- IO.readLine
190 |   _ <- if (n == 10) IO.println("Yay!")
191 |        else IO.raiseError(new Exception("wrong"))
192 | } yield ()
193 | 
194 | def clock: IO[Unit] =
195 |   IO.sleep(1.minute) >>
196 |     Clock[IO].realTimeInstant.flatMap(IO.println) >>
197 |     clock
198 | ```
199 | 
200 | ---
201 | # Fibers
202 | 
203 | `IO` is based on the `Fiber` abstraction for low-level concurrency
204 | ```scala
205 | // Simplified
206 | trait IO[A] {
207 |   def start: Fiber[A]
208 | }
209 | trait Fiber[A] {
210 |   def cancel: F[Unit]
211 |   def join: F[Outcome[F, Throwable, A]]
212 | }
213 | ```
214 | 
215 | A low level building block - you usually don't need to interact with them directly
216 | 
217 | ---
218 | # `IO` Execution
219 | 
220 | - Can describe both concurrency and parallelism
221 | - Uses N:M green-threading
222 |   - Cheap: thousands of concurrent `Fiber`s are not a problem
223 | - Nonblocking asynchronous execution
224 |   - Run as as few as 1 thread (including Scala.JS)
225 | 
226 | ---
227 | # `IO` Concurrency
228 | 
229 | Both low-level `Fibers` and high-level combinators
230 | - Forking: `io.start`, `Fiber`
231 | - Cancellation (low level): `Fiber#cancel`
232 | - Cancellation (high level):
233 |   - `IO.race(first, second)` - concurrently execute, return the winner and cancel the loser,
234 |   - `io.timeout(duration)` - fails with `TimeoutException` if not complete within `duration`
235 |   - `io.timeoutTo(duration, fallbackIO)` - Execute `fallbackIO` if `io` is not complete within `duration`
236 | - Nonblocking asynchronous sleep: `IO.sleep(duration)`
237 | - Concurrent execution: `start`, `listOfIO.parSequence`, `(ioA, ioB).parTupled`
238 | 
239 | ---
240 | # Resource management
241 | 
242 | `Resource[IO, A]` describes the ability to initialize and release a resource
243 | - Similar to `try`/`finally`, but composable and referentially transparent
244 |   - `catch`/`finally` aren't transparent - they don't talk about *return values*.
245 | - Allows tracking resource lifetime at the type level
246 |   - Function accepting `Resource[IO, A]` parameter will acquire and release internally
247 |   - Function accepting `A` reuses the live value
248 | - Allows *guaranteed* finalization
249 |   - Whether the function given to `use` completes, fails, or is cancelled, the Resource is closed. Will not leak.
250 | 
251 | ---
252 | # cats-effect typeclasses
253 | 
254 | All the capabilities that `IO` exposes are described by typeclasses, allowing more generic code and multi-library compatibility.
255 | 
256 | This talk focus on `IO` and not the typeclasses
257 | 
258 | ---
259 | # cats-effect typeclasses
260 | 
261 | <img src="typeclasses-cheat-sheet.jpeg">
262 | 
263 | ---
264 | # `IO` vs `Future` - Overview
265 | 
266 | Actions:
267 | - `IO` is a value that describes an action (possibly asynchronous)
268 | - `Future` is a handle to the result of an already-running action (possibly asynchronous)
269 | 
270 | ---
271 | # `IO` vs `Future` - Speed
272 | 
273 | - `IO` is optimized for throughput
274 |   - Thread shift on demand
275 |   - Has utilities for introducing manual shifts for fairness
276 |   - Benchmarks faster for most workloads
277 |   - Work-stealing runtime implementation inspired by Rust's Tokio
278 | - `Future` is optimized for fairness
279 |   - Thread shift every single `map`/`flatMap` (hence implicit `ec`)
280 |   - Can only be configured using a specialized `ec` argument
281 | 
282 | ---
283 | # `IO` vs `Future` - Cancellation
284 | 
285 | - `Future[A]` can't be cancelled - once constructed, it can't be stopped
286 |   - Wasted resources
287 | - `IO[A]` can be concurrently forked, and then either `join`ed or `cancel`ed  
288 |   - There are high-level constructs around this in cats-effect
289 |   - More sophisticated abstractions built on top can be found in other libraries
290 | 
291 | ---
292 | # `IO` vs `Future` - Concurrency
293 | 
294 | - Future has concurrency depending where you invoke functions
295 | - IO has structured concurrency via explicit combinators
296 | 
297 | ---
298 | # `IO` vs `Future` - Concurrency with Future
299 | ```scala
300 | // Sequential execution
301 | def jobOne: Future[Int] = Future(???)
302 | def jobTwo: Future[String] = Future(???)
303 | 
304 | jobOne.flatMap(i => jobTwo.map(s => (i, s)))
305 | ```
306 | 
307 | ```scala
308 | // Concurrent execution
309 | val jobOne: Future[Int] = Future(???)
310 | val jobTwo: Future[String] = Future(???)
311 | 
312 | jobOne.flatMap(i => jobTwo.map(s => (i, s)))
313 | ```
314 | 
315 | ---
316 | # `IO` vs `Future` - Concurrency with Future
317 | 
318 | 
319 | Does this expression evaluate concurrently or sequentially?
320 | 
321 | ```scala
322 | jobOne.flatMap(i => jobTwo.map(s => (i, s)))
323 | ```
324 | 
325 | Impossible to tell - have to read the implementation details
326 | 
327 | ---
328 | # `IO` vs `Future` - Concurrency with `IO`
329 | 
330 | ```scala
331 | val jobOne: IO[Int] = IO(???)
332 | val jobTwo: IO[String] = IO(???)
333 | 
334 | // Sequential execution
335 | jobOne.flatMap(i => jobTwo.map(s => (i, s)))
336 | // Also Sequential
337 | val result1: IO[(Int, String)] = (jobOne, jobTwo).tupled
338 | 
339 | // Concurrent execution (manually)
340 | for {
341 |   j1Fiber <- jobOne.start
342 |   j2Fiber <- jobTwo.start
343 |   i <- j1Fiber.join
344 |   s <- j2Fiber.join
345 | } yield (i, s)
346 | 
347 | // Concurrent execution (higher level)
348 | val result2: IO[(Int, String)] = (jobOne, jobTwo).parTupled
349 | 
350 | ```
351 | 
352 | ---
353 | # A tour of cats-effect
354 | 
355 | - Utilities around Thread pools, controlling where and when things execute
356 |   - Temporal, Clock
357 | - Concurrency primitives
358 |   - Semaphore - Has `N` permits, can acquire or release permits as needed. Acquire blocks until permits are available
359 |   - Ref - Lock-free concurrency-safe mutable shared memory. A pure replacement for `var`
360 |   - Deferred - A pure promise. Can complete with a value or get the completed value. Get blocks until complete.
361 |   - And more!
362 | 
363 | 
364 | ---
365 | # A tour of cats-effect
366 | 
367 | - Dispatcher - Allows you to have controlled regions of `unsafeRun*` methods, for wrapping imperative libraries
368 | 
369 | - `IOApp` - Whole "pure" applications
370 |   - Handles all the initialization, cancellation hooks, jvm actions so you can write your main method in `IO`
371 | 
372 | - IORuntime
373 |   - An optimized work-stealing compute-based Execution context, bundled with an appropriate pool for thread-blocking work and a high-priority scheduler pool.
374 | 
375 | ---
376 | # Thread pool management
377 | 
378 | <img src="concurrency-thread-pools.png">
379 | 
380 | ---
381 | # Thread pool management - `ExecutionContext.global`
382 | 
383 | `global` isn't an ideal choice.
384 | - Designed for mixed cpu + blocking-io work in a single pool
385 | - Optimal for neither
386 | - CPU-bound work suffers in performance from cpu context shifting; `global` creates more threads than cpu cores
387 | - I/O-bound work can preempt cpu-bound work if `global` decides not to make a new Thread
388 | - This applies for all fork-join pools - even if you don't use cats-effect.
389 | 
390 | ---
391 | # Thread pool management - 3 Pool Model
392 | 
393 | - Computation: Fixed size pool for cpu work
394 |   - Normal `IO` values run here
395 | - Blocking IO: Cached thread pool for thread-blocking work
396 |   - Wrap side-effecting code with `IO.blocking` or `IO.interruptible` (if you can `Thread.interrupt()` it)
397 | - Event Dispatcher: High-priority pool for scheduling and timers
398 |  - Used to schedule asynchronous `sleep` calls
399 | 
400 | ---
401 | # Blocking threads
402 | 
403 | Blocking threads should be avoided
404 | - Your cpu core is doing no work, waiting for a result while it could be computing something else
405 | - It reduces your bandwidth for concurrent work
406 | 
407 | Instead of `IO.apply`, use:
408 | - `IO.blocking` to wrap thread-blocking code
409 | - `IO.interruptible` if that code will behave well under `Thread.interrupt()`
410 | 
411 | ---
412 | # Blocking threads - `IO.blocking`
413 | - `IO.blocking` to wrap thread-blocking code
414 | 
415 | ```scala
416 | def fos: java.io.FileOutputStream = ???
417 | def bytes: Array[Byte] = ???
418 | val writeFile: IO[Unit] = IO.blocking(fos.write(bytes))
419 | ```
420 | 
421 | ---
422 | # Blocking Threads - `IO.interruptible`
423 | - `IO.interruptible` if that code will behave well under `Thread.interrupt()`
424 | 
425 | ```scala
426 | val tenMinutes = 10 * 60 * 1000
427 | // tenMinutes: Int = 600000
428 | def blockingTask = IO.interruptible(many = false)(Thread.sleep(tenMinutes))
429 | def printTime = Clock[IO].realTimeInstant.flatMap(t => IO.println(s"It is now $t"))
430 | yolo(for {
431 |   _ <- printTime
432 |   task <- blockingTask.start
433 |   _ <- IO.sleep(2.seconds)
434 |   _ <- task.cancel
435 |   _ <- printTime
436 | } yield ())
437 | // It is now 2021-08-02T15:18:30.698Z
438 | // It is now 2021-08-02T15:18:32.714Z
439 | ```
440 | 
441 | ---
442 | # Time
443 | 
444 | `Temporal` and `Clock`
445 |  - Nonblocking async sleep: `IO.sleep(duration)` (or `Temporal[IO].sleep(duration)`)
446 |  - Get the time: `Clock[IO].realTime`, `.realTimeInstant`
447 | 
448 | ```scala
449 | // Time since epoch
450 | yolo(Clock[IO].realTime)
451 | // res12: FiniteDuration = 1627917512718 milliseconds
452 | 
453 | // Current Instant
454 | yolo(Clock[IO].realTimeInstant)
455 | // res13: java.time.Instant = 2021-08-02T15:18:32.720Z
456 | 
457 | // Monotonically incrementing clock
458 | yolo(Clock[IO].monotonic)
459 | // res14: FiniteDuration = 288656489830275 nanoseconds
460 | ```
461 | 
462 | ---
463 | # Applications
464 | 
465 | `IOApp` for your "main" classes
466 | 
467 | ```scala
468 | object MyMain extends IOApp {
469 |   def run(args: List[String]): IO[ExitCode] = {
470 |     val myAppResource = 
471 |       for {
472 |         _ <- Resource.eval(IO.println("hello cats"))
473 |         db <- getDatabase
474 |         result <- Resource.eval(myAppLogic(db))
475 |         _ <- Resource.eval(IO.println(s"got $result"))
476 |       } yield ()
477 |     
478 |       myAppResource.useForever.as(ExitCode.Success)
479 |     }
480 | 
481 | 
482 |   def getDatabase: Resource[IO, Database] = ???
483 |   def myAppLogic(db: Database): IO[Int] = ???
484 | }
485 | ```
486 | 
487 | ---
488 | # But I already have an application!
489 | 
490 | `IO` can be introduced to a codebase using `Future` or using its own "main" class.
491 | 
492 | ---
493 | # Calling `Future` from `IO`
494 | 
495 | Tip: Instantiating a `Future` value is a side effect, so it gets wrapped with `IO.apply`
496 | 
497 | ```scala
498 | def existingLogic(x: Int): Future[Int] = ???
499 | def moreLogic(y: Int): IO[Int] =
500 |   for {
501 |     xResult <- IO.fromFuture(IO(existingLogic(42))) 
502 |   } yield xResult + y
503 | ```
504 | 
505 | ---
506 | 
507 | # Calling `IO` from `Future`
508 | 
509 | ```scala
510 | import cats.effect.unsafe
511 | 
512 | trait MyTrait { def doWork: Future[Int] }
513 | 
514 | // NB: You can use `IORuntime.global`, but it's more flexible to take a parameter
515 | class MyTraitImpl(implicit ioRuntime: unsafe.IORuntime) extends MyTrait {
516 |   override def doWork: Future[Int] =
517 |     ioLogic.map(_.length).unsafeToFuture()
518 |   
519 |   def ioLogic: IO[String] = ???
520 | }
521 | ```
522 | 
523 | ---
524 | # Converting to IO - Sequential imperative
525 | 
526 | Sequential code:
527 | - Replace `;` with `flatMap`
528 | 
529 | ```scala
530 | 
531 | // Imperative
532 | def oneStep(): Unit = println("one")
533 | def anotherStep(): Unit = println("two")
534 | 
535 | oneStep()
536 | anotherStep()
537 | 
538 | // IO
539 | def oneStepIO(): IO[Unit] = IO(println("one"))
540 | def anotherStepIO(): IO[Unit] = IO(println("two"))
541 | 
542 | for {
543 |   _ <- oneStepIO()
544 |   _ <- anotherStepIO()
545 | } yield ()
546 | ```
547 | 
548 | ---
549 | # Converting to `IO` - `Future` code
550 | 
551 | - `Future.apply` -> `IO.apply`
552 | - `Future.successful` -> `IO.pure`
553 | - `Future.failed` -> `IO.raiseError`
554 | - Implicit `Future` concurrency -> Explicit concurrency combinators
555 | - Side effects in `map` -> explicit effects with `IO(sideEffect())` in `flatMap`
556 | 
557 | ---
558 | # Converting to `IO` - imperative code and mutation
559 | 
560 | - `new` on a stateful class is stateful; wrap it in `IO`
561 | - Reading or writing to stateful classes is stateful; wrap it in `IO`
562 | - Imperative setup/close methods -> `Resource.make`
563 | - Use `Random[IO]` for pure, performant, concurrecy-safe randomness. Avoid `IO(Random.xyz())`
564 | - Use `Clock[IO]` for pure access to time.
565 | - Two sequential imperative lines -> two `IO` expressions combined with `flatMap`
566 | - "I need a `Foo` value but I have `IO[Foo]`, how do I get it out?
567 |   - You never "get it out"; use `flatMap`; `getFooIO.flatMap(foo => useFooIO(foo))`
568 | 
569 | ---
570 | IO Examples
571 | 
572 | ```scala
573 | import cats.effect.std.Random
574 | 
575 | val ioExample = for {
576 |   _ <- IO.println("Hello cats!") // Uses the `Console[IO]` capability
577 | 
578 |   time <- Clock[IO].realTimeInstant
579 |   _ <- IO.println(s"It is now $time")
580 | 
581 |   rnd <- Random.scalaUtilRandom[IO]
582 |   _ <- rnd.nextInt.flatMap(n => IO.println(s"Your lucky number is: $n"))
583 | 
584 | } yield ()
585 | ```
586 | 
587 | ```scala
588 | yolo(ioExample)
589 | // Hello cats!
590 | // It is now 2021-08-02T15:18:32.737Z
591 | // Your lucky number is: -514751454
592 | ```
593 | 
594 | ---
595 | # Converting to `IO` - general tips
596 | - Sometimes you'll want to `import cats.syntax.all._` for generic combinators (eg `tupled`, `handleError`)
597 | - Sometimes you'll want `import cats.effect.implicits._` for effect methods (eg `parSequence`, `parTupled`, `parMapN`)
598 | - To imperative run an `IO`, you need either an `IORuntime` or create a `Dispatcher[IO]`.
599 |    - `IORuntime.global` is fine for production! It's not like `ExecutionContext.global`
600 |    - `Dispatcher[F]` is cheap and works with "capability trait" style (aka "tagless final")
601 | - Understand the risks when using `.unsafe*` methods on `IO`
602 | 
603 | ---
604 | # Converting to `IO` - Common errors
605 | - Discarding an `IO` without flatMap-ing it
606 | - Side effects not wrapped `IO`, eg in `map`
607 | - Implicit `Future` concurrency
608 | - Use `-Ywarn-value-discard`!
609 |   - Optionally but recommended, set a lot of "save me from myself" flags at once using `sbt-tpolecat`
610 | 
611 | ---
612 | # Common Errors - discarding your `IO`
613 | 
614 | ```scala
615 | def doStuff: IO[Unit] = ???
616 | def oops = {
617 |    // This IO never executes!
618 |    IO.println("About to do stuff")
619 |    doStuff
620 | }
621 | 
622 | def correct =
623 |   IO.println("About to do stuff")
624 |     .flatMap(_ => doStuff)
625 | ```
626 | 
627 | Tip: `fa.flatMap(_ => fb)` is so common it has an operator; `fa >> fb`
628 | 
629 | ---
630 | # Converting to `IO` - Application structure
631 | - Semantic interfaces, not mechanical ones
632 | - New code in `IO`
633 | - Interop where needed
634 | - Convert one class at a time
635 |   - You don't need to convert the whole project!
636 |   - Stop whenever you reach "good enough"
637 |   - Update code sections when you need to; if it's not broken and isn't being modified, leave it
638 | 
639 | ---
640 | # Cats-Effect
641 | 
642 | - Write code that doesn't break when you change it
643 | - Write reusable code that you know won't surprise you
644 | - Write code that can be understood in isolation
645 | - Gain access to an ecosystem of compatible, efficient, and easy to learn libraries
646 | 
647 | ---
648 | # Links and resources
649 | 
650 | - [Cats-Effect Concepts](https://typelevel.org/cats-effect/docs/concepts)
651 | - Typelevel [Discord chat](https://discord.gg/fChyzB4w)
652 | - [Documentation](https://typelevel.org/cats-effect/)
653 | - [Functional and Reactive Domain Modeling](https://www.manning.com/books/functional-and-reactive-domain-modeling)
654 |   - Book that goes into application design, in a style that meshes very cleanly with cats-effect
655 | - [Referential Transparency in the Wild](https://impurepics.com/posts/2018-07-13-referential-transparency-wild.html)
656 | - [Shared State in Functional Programming](https://typelevel.org/blog/2018/06/07/shared-state-in-fp.html) - More examples around `Resource` usage and simpler data sharing examples
657 | - [@impurepics](https://impurepics.com) is the author+owner of the graphics
658 |     
659 | 
660 | 
661 | ---
662 | class: center, middle
663 | 
664 | # Thanks!
665 | Code and slides at `daenyth/intro-cats-effect` on GitHub
666 | 
667 | ## Questions?
668 | 
669 | 
670 | 
671 | 
672 | 
673 |  </textarea>
674 |   <script src="remark-latest.min.js">
675 |   </script>
676 |   <script>
677 |     var slideshow = remark.create();
678 |   </script>
679 | </body>
680 | 
681 | </html>


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