akka/akka-core

Add notes about shutdown patterns for Streams to docs

Open

#22,183 opened on Jan 23, 2017

View on GitHub
 (2 comments) (0 reactions) (0 assignees)Scala (3,547 forks)batch import
1 - triagedhelp wantedt:docs

Repository metrics

Stars
 (13,277 stars)
PR merge metrics
 (Avg merge 8d 19h) (10 merged PRs in 30d)

Description

As a newbie, I ran into a case where I couldn't understand how to terminate the ActorSystem, used to materialize the Stream, after the latter has finished it work. I scanned through the titles in the doc and couldn't find a word about shutdown patterns. The onComplete() callback (which was an obvious choice) unexpectedly fired right after my pipeline was run. Thanks to akka gitter chat and @ktoso, I was pointed towards "Custom materialized values" section, because it turned out I didn't use one in my custom Sink, and that's why onComplete() fired too early. But it was very unobvious to me as a beginner.

So it'd be great if there will be some small section in the beginning of the Streams doc, that has a keyword "shutdown" or similar and explains basic necessity of Mat values for signaling completition of a stream with an example of a proper shutdown pattern.

Contributor guide

Research direction
Explore the existing Akka Streams documentation to identify where to add a section on shutdown patterns. Focus on the section about materialized values and provide a clear example of how to properly shut down a stream using the ActorSystem.
Tech stack
scala
Domain
backend
Issue type
Documentation
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
2
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-3 hours
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
Stale
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
Clear
Prerequisites
ScalaGit
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
75