implement stop-on-end stream (#25)

Author: bicycle1885

docs/src/assets/modes.dot

@@ -1,14 +1,28 @@
 digraph modes {
+    "start" -> "idle";
+
     "idle" -> "read";
     "idle" -> "write";
     "idle" -> "close";
     "idle" -> "panic";
 
     "read" -> "read";
+    "read" -> "stop";
     "read" -> "close";
     "read" -> "panic";
 
     "write" -> "write";
+    "write" -> "stop";
     "write" -> "close";
     "write" -> "panic";
+
+    "stop" -> "close";
+
+    "start" [ shape = point ];
+    "idle"  [ shape = circle ];
+    "read"  [ shape = circle ];
+    "write" [ shape = circle ];
+    "stop"  [ shape = circle; style=bold; ];
+    "close" [ shape = circle; style=bold; ];
+    "panic" [ shape = circle; style=bold; ];
 }

docs/src/assets/modes.svg

@@ -44,24 +44,32 @@ default buffer size is 16KiB for each.
 
 The `mode` field may be one of the following value:
 - `:idle` : initial and intermediate mode, no buffered data
-- `:read` : ready to read data, data may be buffered
-- `:write`: ready to write data, data may be buffered
+- `:read` : being ready to read data, data may be buffered
+- `:write`: being ready to write data, data may be buffered
+- `:stop` : transcoding is stopped, data may be buffered
 - `:close`: closed, no buffered data
 - `:panic`: an exception has been thrown in codec, data may be buffered but we
             cannot do anything
 
+Note that `mode=:stop` does not mean there is no data available in the stream.
+This is because transcoded data may be left in the buffer.
+
 The initial mode is `:idle` and mode transition happens as shown in the
 following diagram:
 ![Mode transition](./assets/modes.svg)
 
-The mode transition should happen in the `changemode!(stream, newmode)` function
-in src/stream.jl. Trying an undefined transition will thrown an exception.
-
-A transition happens based on actions (or function calls) of the user or return
-code of the codec. For example, calling `read(stream)` will change the mode from
-`:init` to `:read` and then calling `close(stream)` will change the mode from
-`:read` to `:close`. When data processing fails in the codec, a codec will
-return `:error` and the stream will result in `:panic`.
+Modes surrounded by a bold circle are a state in which the transcoding stream
+has released resources by calling `finalize(codec)`.  The mode transition should
+happen in the `changemode!(stream, newmode)` function in src/stream.jl. Trying
+an undefined transition will thrown an exception.
+
+A transition happens according to internal or external events of the transcoding
+stream. The status code and the error object returned by codec methods are
+internal events, and user's method calls are external events.  For example,
+calling `read(stream)` will change the mode from `:init` to `:read` and then
+calling `close(stream)` will change the mode from `:read` to `:close`. When data
+processing fails in the codec, a codec will return `:error` and the stream will
+result in `:panic`.
 
 
 Shared buffers

docs/src/devnotes.md

@@ -132,6 +132,34 @@ Effectively, this is equivalent to the following pipeline:
 
     cat data.txt.gz | gzip -d | zstd >data.txt.zst
 
+Stop decoding on the end of a block
+-----------------------------------
+
+Most codecs support decoding concatenated data blocks. For example, if you
+concatenate two gzip files into a file and read it using
+`GzipDecompressionStream`, you will see the byte stream of concatenation of two
+files. If you need the first part of the file, you can set `stop_on_end` to
+`true` to stop transcoding at the end of the first block:
+```julia
+using CodecZlib
+# cat foo.txt.gz bar.txt.gz > foobar.txt.gz
+stream = GzipDecompressionStream(open("foobar.txt.gz"), stop_on_end=true)
+read(stream)  #> the content of foo.txt
+eof(stream)   #> true
+```
+
+In the case where you need to reuse the wrapped stream, the code above must be
+slightly modified because the transcoding stream may read more bytes than
+necessary from the wrapped stream. By wrapping a stream with `NoopStream`, the
+problem of overreading is resolved:
+```julia
+using CodecZlib
+using TranscodingStreams
+stream = NoopStream(open("foobar.txt.gz"))
+read(GzipDecompressionStream(stream, stop_on_end=true))  #> the content of foo.txt
+read(GzipDecompressionStream(stream, stop_on_end=true))  #> the content of bar.txt
+```
+
 Transcode data in one shot
 --------------------------
 

docs/src/examples.md

@@ -139,7 +139,7 @@ function reset!(buf::Buffer)
     return buf.bufferpos
 end
 
-# Make margin with ≥`minsize`.
+# Make margin with ≥`minsize` and return the size of it.
 function makemargin!(buf::Buffer, minsize::Integer)
     @assert minsize ≥ 0
     if buffersize(buf) == 0 && buf.markpos == 0

src/buffer.jl

@@ -155,7 +155,7 @@ function flushbufferall(stream::NoopStream)
     return bufsize
 end
 
-function processall(stream::NoopStream)
-    flushbufferall(stream)
-    @assert buffersize(stream.state.buffer1) == 0
+function flushuntilend(stream::NoopStream)
+    writedata!(stream.stream, stream.state.buffer1)
+    return
 end

src/noop.jl

@@ -4,10 +4,13 @@
 # See docs/src/devnotes.md.
 mutable struct State
     # current stream mode
-    mode::Symbol
+    mode::Symbol  # {:idle, :read, :write, :stop, :close, :panic}
 
-    # return code of the last method call (:ok or :end)
-    code::Symbol
+    # return code of the last method call
+    code::Symbol  # {:ok, :end, :error}
+
+    # flag to go :stop on :end
+    stop_on_end::Bool
 
     # exception thrown while data processing
     error::Error
@@ -16,11 +19,11 @@ mutable struct State
     buffer1::Buffer
     buffer2::Buffer
 
-    function State(size::Integer)
-        return new(:idle, :ok, Error(), Buffer(size), Buffer(size))
-    end
-
     function State(buffer1::Buffer, buffer2::Buffer)
-        return new(:idle, :ok, Error(), buffer1, buffer2)
+        return new(:idle, :ok, false, Error(), buffer1, buffer2)
     end
 end
+
+function State(size::Integer)
+    return State(Buffer(size), Buffer(size))
+end