- user ---> |state.buffer1| ---> <stream.codec> ---> |state.buffer2| ---> stream</code></pre><p>In the read mode, a user pull out data from <code>state.buffer1</code> and pre-transcoded data are filled in <code>state.buffer2</code>. In the write mode, a user will push data into <code>state.buffer1</code> and transcoded data are filled in <code>state.buffer2</code>. The default buffer size is 16KiB for each.</p><p><code>State</code> (defined in src/state.jl) has five fields:</p><ul><li><code>mode</code>: current stream mode (<code><:Symbol</code>)</li><li><code>code</code>: return code of the last codec's method call (<code><:Symbol</code>)</li><li><code>error</code>: exception returned by the codec (<code><:Error</code>)</li><li><code>buffer1</code>: data buffer that is closer to the user (<code><:Buffer</code>)</li><li><code>buffer2</code>: data buffer that is farther to the user (<code><:Buffer</code>)</li><li><code>bytes_written_out</code>: number of bytes written to the underlying stream (<code><:Int64</code>)</li></ul><p>The <code>mode</code> field may be one of the following value:</p><ul><li><code>:idle</code> : initial and intermediate mode, no buffered data</li><li><code>:read</code> : being ready to read data, data may be buffered</li><li><code>:write</code>: being ready to write data, data may be buffered</li><li><code>:stop</code> : transcoding is stopped after read, data may be buffered</li><li><code>:close</code>: closed, no buffered data</li><li><code>:panic</code>: an exception has been thrown in codec, data may be buffered but we cannot do anything</li></ul><p>Note that <code>mode=:stop</code> does not mean there is no data available in the stream. This is because transcoded data may be left in the buffer.</p><p>The initial mode is <code>:idle</code> and mode transition happens as shown in the following diagram: <img src="../assets/modes.svg" alt="Mode transition"/></p><p>Modes surrounded by a bold circle are a state in which the transcoding stream has released resources by calling <code>finalize(codec)</code>. The mode transition should happen in the <code>changemode!(stream, newmode)</code> function in src/stream.jl. Trying an undefined transition will thrown an exception.</p><p>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 <code>read(stream)</code> will change the mode from <code>:init</code> to <code>:read</code> and then calling <code>close(stream)</code> will change the mode from <code>:read</code> to <code>:close</code>. When data processing fails in the codec, a codec will return <code>:error</code> and the stream will result in <code>:panic</code>.</p><h2 id="Shared-buffers"><a class="docs-heading-anchor" href="#Shared-buffers">Shared buffers</a><a id="Shared-buffers-1"></a><a class="docs-heading-anchor-permalink" href="#Shared-buffers" title="Permalink"></a></h2><p>Adjacent transcoding streams may share their buffers. This will reduce memory allocation and eliminate data copy between buffers.</p><p>If <code>buffer2</code> is shared it is considered to be owned by the underlying stream by the <code>stats</code> and <code>position</code> functions.</p><p><code>readdata!(input::IO, output::Buffer)</code> and <code>flush_buffer2(stream::TranscodingStream)</code> do the actual work of read/write data from/to the underlying stream. These methods have a special pass for shared buffers.</p><h2 id="Noop-codec"><a class="docs-heading-anchor" href="#Noop-codec"><code>Noop</code> codec</a><a id="Noop-codec-1"></a><a class="docs-heading-anchor-permalink" href="#Noop-codec" title="Permalink"></a></h2><p><code>Noop</code> (<code>NoopStream</code>) is a codec that does <em>nothing</em>. It works as a buffering layer on top of the underlying stream. Since <code>NoopStream</code> does not need to have two distinct buffers, <code>buffer1</code> and <code>buffer2</code> in the <code>State</code> object are shared and some specialized methods are defined for the type. All of these are defined in src/noop.jl.</p></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../migrating/">« Migration</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="auto">Automatic (OS)</option><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option><option value="catppuccin-latte">catppuccin-latte</option><option value="catppuccin-frappe">catppuccin-frappe</option><option value="catppuccin-macchiato">catppuccin-macchiato</option><option value="catppuccin-mocha">catppuccin-mocha</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> version 1.14.1 on <span class="colophon-date" title="Friday 29 August 2025 03:10">Friday 29 August 2025</span>. Using Julia version 1.11.6.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
0 commit comments