Edit on GitHub

Buffer

Buffer is a primitive to buffer the data. Data can be read from and written into a buffer. The mode of the buffer determines the way to read from and write into the buffers.

Buffer Modes

Buffer mode determines the way the data is read from and written into a Buffer. Basically, there are four buffer modes: Normal, Cyclic, Fifo and Lifo. Normal, Fifo and Lifo are subtypes of LinearMode and Cyclic is subtype of CyclicMode.

There are four different buffer modes.

Jusdl.Utilities.Normal — Type
Normal <: LinearMode

LinearMode buffer mode. The data is written to buffer until the buffer is full. When it is full, no more data is written to the buffer. When read, the data written last is returned and the returned data is not deleted from the internal container of the buffer.

source
Jusdl.Utilities.Cyclic — Type
Cyclic <: CyclicMode

Cyclic buffer mode. The data is written to buffer until the buffer is full. When the buffer is full, new data is written by overwriting the data available in the buffer starting from the beginning of the buffer. When the buffer is read, the element written last is returned and the returned element is not deleted from the buffer.

source
Jusdl.Utilities.Lifo — Type
Lifo <: LinearMode

Lifo (Last-in-first-out) buffer mode. This type of buffer is a last-in-first-out buffer. Data is written to the buffer until the buffer is full. When the buffer is full, no more element can be written into the buffer. When read, the last element written into buffer is returned. The returned element is deleted from the buffer.

source
Jusdl.Utilities.Fifo — Type
Fifo <: LinearMode

Fifo (First-in-last-out) buffer mode. This type of buffer is a first-in-first-out buffer. The data is written to the buffer until the buffer is full. When the buffer is full, no more element can be written into the buffer. When read, the first element written into the buffer is returned. The returned element is deleted from the buffer.

source

Buffer Constructors

The Buffer construction is very similar to the construction of arrays in Julia. Just specify the mode, element type and length of the buffer. Here are the main Buffer constructors:

Jusdl.Utilities.Buffer — Type
Buffer{M}(dtype::Type{T}, sz::Int...) where {M, T}

Constructs a Buffer of size sz with element type of T. M is the mode of the Buffer that determines how data is to read from and written into the Buffer. There exists for different buffer modes:

The default mode for Buffer is Cyclic and default element type is Float64.

Buffer{M}(sz::Int...) where {M, T}

Constructs a Buffer of size sz and with element type of T and mode M.

Buffer(dtype::Type{T}, sz::Int...) where T

Constructs a Buffer of size sz and element type T. The mode of buffer is Cyclic.

Buffer(sz::Int...)

Constructs a Buffer of size sz with mode Cyclic and element type of Float64.

Buffer{M}(data::AbstractVecOrMat{T}) where {M, T<:Real}

Constructs a Buffer with data.

Example

julia> buf = Buffer(5)
Buffer(mode:Cyclic, eltype:Float64, size:(5,), index:1, state:empty)

julia> buf = Buffer{Cyclic}(2, 5)
Buffer(mode:Cyclic, eltype:Float64, size:(2, 5), index:1, state:empty)

julia> buf = Buffer{Cyclic}(collect(reshape(1:8, 2, 4)))
Buffer(mode:Cyclic, eltype:Int64, size:(2, 4), index:1, state:empty)
source

Writing Data into Buffers

Writing data into a Buffer is done with write! function.

Jusdl.Utilities.write! — Method
write!(buf::Buffer{M, <:Real, 1}, val::Real) where {M}

Writes val into buf.

write!(buf::Buffer{M, <:Real, 2}, val::AbstractVector{<:Real}) where {M}

Writes val into buf.

write!(buf::Buffer{M, <:Real, 1}, vals::AbstractVector{<:Real}) where {M}

Writes each element of vals into buf.

write!(buf::Buffer{M, <:Real, 2}, vals::AbstractMatrix{<:Real}) where {M}

Writes each column of vals into buf.

Warning

Buffer mode determines how data is written into buffers. See also: Normal, Cyclic, Lifo, Fifo for buffer modes.

Example

julia> buf = Buffer(5)
Buffer(mode:Cyclic, eltype:Float64, size:(5,), index:1, state:empty)

julia> write!(buf, 1.)
1.0

julia> write!(buf, [2, 3])

julia> buf.data
5-element Array{Float64,1}:
 1.0
 2.0
 3.0
 0.0
 0.0

julia> buf = Buffer(2,5)
Buffer(mode:Cyclic, eltype:Float64, size:(2, 5), index:1, state:empty)

julia> write!(buf, [1, 1])
2-element Array{Int64,1}:
 1
 1

julia> write!(buf, [2 3; 2 3])

julia> buf.data
2×5 Array{Float64,2}:
 1.0  2.0  3.0  0.0  0.0
 1.0  2.0  3.0  0.0  0.0
source

Recall that when the buffer is full, no more data can be written into the buffer if the buffer mode is of type LinearMode. 


julia> normalbuf = Buffer{Normal}(3)
3-element Buffer{Normal,Float64,1}

julia> fill!(normalbuf, 1.)
3-element Buffer{Normal,Float64,1}:
 1.0
 1.0
 1.0

julia> normalbuf.data
3-element Array{Float64,1}:
 1.0
 1.0
 1.0

julia> write!(normalbuf, 1.)
ERROR: Buffer is full

This situation is the same for Lifo and Fifo buffers, but not the case for Cyclic buffer. 


julia> normalbuf = Buffer{Cyclic}(3)
3-element Buffer{Cyclic,Float64,1}

julia> fill!(normalbuf, 1.)
3-element Buffer{Cyclic,Float64,1}:
 1.0
 1.0
 1.0

julia> normalbuf.data
3-element Array{Float64,1}:
 1.0
 1.0
 1.0

julia> write!(normalbuf, 3.)
3.0

julia> write!(normalbuf, 4.)
4.0

Reading Data from Buffers

Reading data from a Buffer is done with read function.

Base.read — Method
read(buf::Buffer)

Reads an element from buf. Reading is performed according to the mode of buf. See also: Normal, Cyclic, Lifo, Fifo for buffer modes.

Example

julia> buf = Buffer(3)
Buffer(mode:Cyclic, eltype:Float64, size:(3,), index:1, state:empty)

julia> write!(buf, [2, 4, 6])

julia> for i = 1 : 3 
       @show (read(buf), buf.data)
       end
(read(buf), buf.data) = (6.0, [2.0, 4.0, 6.0])
(read(buf), buf.data) = (6.0, [2.0, 4.0, 6.0])
(read(buf), buf.data) = (6.0, [2.0, 4.0, 6.0])

julia> buf = Buffer{Fifo}(5)
Buffer(mode:Fifo, eltype:Float64, size:(5,), index:1, state:empty)

julia> write!(buf, [2, 4, 6])

julia> for i = 1 : 3 
       @show (read(buf), buf.data)
       end
(read(buf), buf.data) = (2.0, [4.0, 6.0, 0.0, 0.0, 0.0])
(read(buf), buf.data) = (4.0, [6.0, 0.0, 0.0, 0.0, 0.0])
(read(buf), buf.data) = (6.0, [0.0, 0.0, 0.0, 0.0, 0.0])
source

AbstractArray Interface of Buffers

A Buffer can be indexed using the similar syntax of arrays in Julia. That is, getindex and setindex! methods can be used with known Julia syntax. i.e. getindex(buf, idx) is equal to buf[idx] and setindex(buf, val, idx) is equal to buf[idx] = val.


julia> buf = Buffer(5)
5-element Buffer{Cyclic,Float64,1}

julia> size(buf)
(5,)

julia> length(buf)
5

julia> for val in 1 : 5
           write!(buf, 2val)
       end

julia> buf[1]
2.0

julia> buf[3:4]
2-element Array{Float64,1}:
 6.0
 8.0

julia> buf[[3, 5]]
2-element Array{Float64,1}:
  6.0
 10.0

julia> buf[end]
10.0

julia> buf[1] = 5
5

julia> buf[3:5] = [7, 8, 9]
3-element Array{Int64,1}:
 7
 8
 9

Full API

Base.fill! — Function
fill!(buf::Buffer, val)

Writes val to buf until bus is full.

Example

julia> buf = Buffer(3);

julia> fill!(buf, 1.)
Buffer(mode:Cyclic, eltype:Float64, size:(3,), index:1, state:full)

julia> buf.data
3-element Array{Float64,1}:
 1.0
 1.0
 1.0
source
Jusdl.Utilities.content — Function
content(buf, [flip=true])

Returns the current data of buf. If flip is true, the data to be returned is flipped. See also snapshot

Example

julia> buf = Buffer(5);

julia> write!(buf, 1:3)

julia> content(buf, flip=false)
3-element Array{Float64,1}:
 1.0
 2.0
 3.0

julia> buf = Buffer(2, 5);

julia> write!(buf, reshape(1:10, 2, 5))

julia> content(buf)
2×5 Array{Float64,2}:
  9.0  7.0  5.0  3.0  1.0
 10.0  8.0  6.0  4.0  2.0
source