trait Writer[-A] extends Closable

A writer represents a sink for a stream of arbitrary elements. While Reader provides an API to consume streams, Writer provides an API to produce streams.

Similar to Readers, a very typical way to work with Writers is to model a stream producer as a write-loop:

def produce[A](w: Writer[A])(generate: () => Option[A]): Future[Unit] =
  generate match {
    case Some(a) => w.write(a).before(produce(w)(generate))
    case None => w.close() // signal EOF and quit producing
  }

Closures and Failures

Writers are Closable and the producer MUST close the stream when it finishes or fail the stream when it encounters a failure and can no longer continue. Streams backed by network connections are particularly prone to resource leaks when they aren't cleaned up properly.

Observing stream failures in the producer could be done via a Future returned form a write-loop:

produce(writer)(generator).respond {
  case Return(()) => println("Produced a stream successfully.")
  case Throw(e) => println(s"Could not produce a stream because of a failure: $e")
}
Self Type
Writer[A]
Note

Encountering a stream failure would terminate the write-loop given the Future recursion semantics.

,

Once failed or closed, a stream can not be restarted such that all future writes will resolve into a failure.

,

Closing an already failed stream does not have an effect.

Back Pressure

By analogy with read-loops (see Reader API), write-loops leverage Future recursion to exert back-pressure: the next write isn't issued until the previous write finishes. This will always ensure a finer grained back-pressure in network systems allowing the producers to adjust the flow rate based on consumer's speed and not on IO buffering.

,

Whether or not multiple pending writes are allowed on a Writer type is an undefined behaviour but could be changed in a refinement.

Linear Supertypes
Known Subclasses
Ordering
  1. Alphabetic
  2. By Inheritance
Inherited
  1. Writer
  2. Closable
  3. AnyRef
  4. Any
  1. Hide All
  2. Show All
Visibility
  1. Public
  2. All

Abstract Value Members

  1. abstract def close(deadline: Time): Future[Unit]

    Close the resource with the given deadline.

    Close the resource with the given deadline. This deadline is advisory, giving the callee some leeway, for example to drain clients or finish up other tasks.

    Definition Classes
    Closable
  2. abstract def fail(cause: Throwable): Unit

    Fail this stream with a given cause.

    Fail this stream with a given cause. No further writes are allowed, but if happen, will resolve into a Future failed with cause.

    Note

    Failing an already closed stream does not have an effect.

  3. abstract def onClose: Future[StreamTermination]

    A Future that resolves once this writer is closed and flushed.

    A Future that resolves once this writer is closed and flushed.

    It may contain an error if the writer is failed.

    This is useful for any extra resource cleanup that you must do once the stream is no longer being used.

  4. abstract def write(element: A): Future[Unit]

    Write an element into this stream.

    Write an element into this stream. Although undefined by this contract, a trustworthy implementation (such as Pipe) would do its best to resolve the returned Future only when a consumer observes a written element.

    The write can also resolve into a failure (failed Future).

Concrete Value Members

  1. final def !=(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  2. final def ##(): Int
    Definition Classes
    AnyRef → Any
  3. final def ==(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  4. final def asInstanceOf[T0]: T0
    Definition Classes
    Any
  5. def clone(): AnyRef
    Attributes
    protected[java.lang]
    Definition Classes
    AnyRef
    Annotations
    @native() @throws( ... )
  6. def close(after: Duration): Future[Unit]

    Close the resource with the given timeout.

    Close the resource with the given timeout. This timeout is advisory, giving the callee some leeway, for example to drain clients or finish up other tasks.

    Definition Classes
    Closable
  7. final def close(): Future[Unit]

    Close the resource.

    Close the resource. The returned Future is completed when the resource has been fully relinquished.

    Definition Classes
    Closable
  8. final def contramap[B](f: (B) ⇒ A): Writer[B]

    Given f, a function from B into A, creates an Writer[B] whose fail and close functions are equivalent to Writer[A]'s.

    Given f, a function from B into A, creates an Writer[B] whose fail and close functions are equivalent to Writer[A]'s. Writer[B]'s write function is equivalent to:

    def write(element: B) = Writer[A].write(f(element))
  9. final def eq(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  10. def equals(arg0: Any): Boolean
    Definition Classes
    AnyRef → Any
  11. def finalize(): Unit
    Attributes
    protected[java.lang]
    Definition Classes
    AnyRef
    Annotations
    @throws( classOf[java.lang.Throwable] )
  12. final def getClass(): Class[_]
    Definition Classes
    AnyRef → Any
    Annotations
    @native()
  13. def hashCode(): Int
    Definition Classes
    AnyRef → Any
    Annotations
    @native()
  14. final def isInstanceOf[T0]: Boolean
    Definition Classes
    Any
  15. final def ne(arg0: AnyRef): Boolean
    Definition Classes
    AnyRef
  16. final def notify(): Unit
    Definition Classes
    AnyRef
    Annotations
    @native()
  17. final def notifyAll(): Unit
    Definition Classes
    AnyRef
    Annotations
    @native()
  18. final def synchronized[T0](arg0: ⇒ T0): T0
    Definition Classes
    AnyRef
  19. def toString(): String
    Definition Classes
    AnyRef → Any
  20. final def wait(): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  21. final def wait(arg0: Long, arg1: Int): Unit
    Definition Classes
    AnyRef
    Annotations
    @throws( ... )
  22. final def wait(arg0: Long): Unit
    Definition Classes
    AnyRef
    Annotations
    @native() @throws( ... )

Inherited from Closable

Inherited from AnyRef

Inherited from Any

Ungrouped