implement and document Pipelines, see #3174

- heavily inspired by spray.io.Pipeline
- fully functional style: a stage returns the resulting commands and
  events, which makes it impossible to mess with the pipeline from the
  inside
- object allocations are optimized away for emtpy and 1-elem results
- added type-safety, verifying that stages match up
- management commands “from the side” for configuration or async events
- full Java API and docs

akka-actor/src/main/scala/akka/util/ByteIterator.scala

@@ -522,6 +522,22 @@ abstract class ByteIterator extends BufferedIterator[Byte] {
     else throw new IllegalArgumentException("Unknown byte order " + byteOrder)
   }
 
+  /**
+   * Get a Long from this iterator where only the least significant `n`
+   * bytes were encoded.
+   */
+  def getLongPart(n: Int)(implicit byteOrder: ByteOrder): Long = {
+    if (byteOrder == ByteOrder.BIG_ENDIAN) {
+      var x = 0L
+      (1 to n) foreach (_ ⇒ x = (x << 8) | next())
+      x
+    } else if (byteOrder == ByteOrder.LITTLE_ENDIAN) {
+      var x = 0L
+      (0 until n) foreach (i ⇒ x |= next() << 8 * i)
+      x
+    } else throw new IllegalArgumentException("Unknown byte order " + byteOrder)
+  }
+
   def getFloat(implicit byteOrder: ByteOrder): Float =
     java.lang.Float.intBitsToFloat(getInt(byteOrder))