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 com.twitter.util.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 com.twitter.util.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 com.twitter.util.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 leveragecom.twitter.util.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
Writertype is an undefined behaviour but could be changed in a refinement.
- Alphabetic
- By Inheritance
- Writer
- Closable
- AnyRef
- Any
- Hide All
- Show All
- Public
- Protected
Abstract Value Members
- 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
- 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 com.twitter.util.Future failed withcause.- Note
Failing an already closed stream does not have an effect.
- abstract def onClose: Future[StreamTermination]
A com.twitter.util.Future that resolves once this writer is closed and flushed.
A com.twitter.util.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.
- abstract def write(element: A): Future[Unit]
Write an
elementinto this stream.Write an
elementinto this stream. Although undefined by this contract, a trustworthy implementation (such as Pipe) would do its best to resolve the returned com.twitter.util.Future only when a consumer observes a writtenelement.The write can also resolve into a failure (failed com.twitter.util.Future).
Concrete Value Members
- final def !=(arg0: Any): Boolean
- Definition Classes
- AnyRef → Any
- final def ##: Int
- Definition Classes
- AnyRef → Any
- final def ==(arg0: Any): Boolean
- Definition Classes
- AnyRef → Any
- final def asInstanceOf[T0]: T0
- Definition Classes
- Any
- def clone(): AnyRef
- Attributes
- protected[lang]
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.CloneNotSupportedException]) @native()
- 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
- 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
- final def contramap[B](f: (B) => A): Writer[B]
Given f, a function from B into A, creates an Writer[B] whose
failandclosefunctions are equivalent to Writer[A]'s.Given f, a function from B into A, creates an Writer[B] whose
failandclosefunctions are equivalent to Writer[A]'s. Writer[B]'swritefunction is equivalent to:def write(element: B) = Writer[A].write(f(element)) - final def eq(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef
- def equals(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef → Any
- def finalize(): Unit
- Attributes
- protected[lang]
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.Throwable])
- final def getClass(): Class[_ <: AnyRef]
- Definition Classes
- AnyRef → Any
- Annotations
- @native()
- def hashCode(): Int
- Definition Classes
- AnyRef → Any
- Annotations
- @native()
- final def isInstanceOf[T0]: Boolean
- Definition Classes
- Any
- final def ne(arg0: AnyRef): Boolean
- Definition Classes
- AnyRef
- final def notify(): Unit
- Definition Classes
- AnyRef
- Annotations
- @native()
- final def notifyAll(): Unit
- Definition Classes
- AnyRef
- Annotations
- @native()
- final def synchronized[T0](arg0: => T0): T0
- Definition Classes
- AnyRef
- def toString(): String
- Definition Classes
- AnyRef → Any
- final def wait(): Unit
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.InterruptedException])
- final def wait(arg0: Long, arg1: Int): Unit
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.InterruptedException])
- final def wait(arg0: Long): Unit
- Definition Classes
- AnyRef
- Annotations
- @throws(classOf[java.lang.InterruptedException]) @native()