swave.io

swave is a lightweight Reactive-Streams infrastructure toolkit for Scala. It attempts to provide all the general-purpose stream construction, stream consumption and stream transformation logic that is typically required in applications that work with Reactive-Streams.

The latest swave artifacts on Maven Central

Gitter chat for swave https://gitter.im/sirthias/swave

Contents of this Document

Getting Started
- Installation
- Basic Usage
Resources
Participating
License

Getting Started

Installation

The library artifacts for swave live on Maven Central and can be tied into your SBT-based Scala project like this:

libraryDependencies += "io.swave" %% "swave-core" % "0.5-M3"

The latest released version is 0.5-M3. Currently it is available only for Scala 2.11.

swave-core has the following dependencies that it will transitively pull into your classpath:

org.reactivestreams % reactive-streams (non-scala)
org.jctools % jctools-core (non-scala)
com.typesafe % config (non-scala)
com.chuusai %% shapeless
com.typesafe.scala-logging %% scala-logging

Once swave is on your classpath you can use this single import to bring everything you need into scope:

import swave.core._

Basic Usage

Providing users and contributors with proper, in-depth documentation for all features is our next number one priority (also see sirthias#2 ).

Up until this goal is reached here are the most important entry points to the swave API:

The three core types you'll work with most are
- Spout[T]: An outlet of stream elements, similar to akka-stream's Source
- Pipe[A, B]: A piece of stream pipeline with two open ends, similar to akka-stream's Flow
- Drain[T, R]: An inlet for stream elements, similar to akka-stream's Sink
You create instances of the core types mostly via the methods on their companion objects.
Most stream operations are defined by the swave.core.StreamOps trait.
Spout, Pipe, Drain instances are not reusable. After creation they can only be started once. If you'd like to run a stream again you need to need to recreate it.
In order to be able to start a stream you need an implicit swave.core.StreamEnv instance in scope. A StreamEnv instance encapsulates everything required to manage a larger streaming setup (like configuration, dispatchers, etc.).

Resources

Talk: "swave - Reactive Streams in Scala" presented at ScalaDays 2016 @ Berlin (Jun 2016): Slides: http://swave.io/scaladays/2016/

Video: https://youtu.be/htwmROeki0c
Talk: "swave - A Preview" presented at SCALAR (Apr 2016): Slides: http://swave.io/scalar/

Video: https://youtu.be/0jq0-Ph2gpM

Participating

swave follows the Collective Code Construction Contract (C4), which is an evolution of the github.com Fork + Pull Model, aimed at providing an optimal collaboration model for free software projects.

This process was originally designed by @hintjens for the ZeroMQ community where it has worked exceptionally well for many years. It has these goals (quote from C4 specification):

To maximize the scale and diversity of the community around a project, by reducing the friction for new Contributors and creating a scaled participation model with strong positive feedbacks;

To relieve dependencies on key individuals by separating different skill sets so that there is a larger pool of competence in any required domain;

To allow the project to develop faster and more accurately, by increasing the diversity of the decision making process;

To support the natural life cycle of project versions from experimental through to stable, by allowing safe experimentation, rapid failure, and isolation of stable code;

To reduce the internal complexity of project repositories, thus making it easier for Contributors to participate and reducing the scope for error;

To enforce collective ownership of the project, which increases economic incentive to Contributors and reduces the risk of hijack by hostile entities.

If you'd like to participate in the development of swave you are very much invited to check out the C4 specification as well as the background information available here. We are looking forward to receiving your first pull request!

License

swave is released under the MPL 2.0, which is a simple and modern weak copyleft license.

Here is the gist of the terms that are likely most important to you (disclaimer: the following points are not legally binding, only the license text itself is):

If you'd like to use swave as a library in your own applications:

swave is safe for use in closed-source applications. The MPL share-alike terms do not apply to applications built on top of or with the help of swave.
You do not need a commercial license. The MPL applies to swave's own source code, not your applications.

If you'd like to contribute to swave:

You do not have to transfer any copyright.
You do not have to sign a CLA.
You can be sure that your contribution will always remain available in open-source form and will not become a closed-source commercial product (even though it might be used by such products!)

For more background info on the license please also see the official MPL 2.0 FAQ.

danielwegener / swave