Manages buffered read/write using callbacks or memory buffer. More...

#include <BufferedStream.h>

Inheritance diagram for grk::BufferedStream:

Public Member Functions
	BufferedStream (uint8_t *buffer, size_t initial_buffer_size, size_t buffer_size, bool is_input)
	Constructs a BufferedStream.
	~BufferedStream () override
	Destroys a BufferedStream.
IStream *	bifurcate (void) override
void	setFetcher (IFetcher *fetcher)
	Sets the IFetcher.
IFetcher *	getFetcher (void) override
	Gets the IFetcher.
void	setMemAdvisor (MemAdvisor *advisor)
void	memAdvise (size_t virtual_offset, size_t length, GrkAccessPattern pattern) override
void	setChunkBuffer (std::shared_ptr< ChunkBuffer<> > chunkBuffer) override
void	setUserData (void *data, grk_stream_free_user_data_fn freeUserDataFun, uint64_t len) override
	Sets user data.
void	setCallbacks (StreamCallbacks &callbacks) override
	Sets callbacks.
size_t	read (uint8_t buffer, uint8_t *zero_copy_buffer, size_t len) override
	Read bytes.
bool	write24u (uint32_t value) override
	Writes 3 bytes from uint32_t as big endian.
bool	write8u (uint8_t value) override
	Writes byte.
size_t	writeBytes (const uint8_t *buffer, size_t len) override
	Writes bytes to stream (no correction for endian!).
bool	flush () override
	Flushes stream to disk.
bool	skip (int64_t len) override
	Skips bytes in stream.
uint64_t	tell (void) override
	query byte offset of stream (similar to ftell).
uint64_t	numBytesLeft (void) override
	Gets the number of bytes left before end of stream.
bool	seek (uint64_t offset) override
	Seek bytes from the stream (absolute).
bool	hasSeek () override
	Checks if stream is seekable.
bool	supportsZeroCopy () override
	Checks is stream supports zero copy.
void	setFormat (GRK_CODEC_FORMAT format) override
	Stores codec format J2K/JP2/MJ2.
GRK_CODEC_FORMAT	getFormat (void) override
	Gets codec format (J2K/JP2/MJ2).
uint8_t *	currPtr (void) override
	Gets current pointer (used for zero copy).
bool	isMemStream () override
	Checks if stream is memory stream i.e.
Public Member Functions inherited from grk::IStream
virtual	~IStream ()=default
Public Member Functions inherited from grk::t1_t2::IStreamWriter
virtual	~IStreamWriter ()=default
template<typename TYPE>
bool	write (TYPE value)
	Writes to stream.

Private Member Functions
size_t	read (uint8_t *buffer, size_t len)
	Reads bytes from stream.
size_t	readDirect (uint8_t *buffer, size_t len)
	Reads directly from callback.
bool	writeSkip (int64_t len)
	Skips bytes in write stream.
bool	readSkip (int64_t len)
	Skip bytes in read stream.
bool	readSeek (uint64_t offset)
	Performs absolute seek in read stream.
bool	writeSeek (uint64_t offset)
	Performs absolute seek in write stream.
void	writeIncrement (size_t len)
bool	write_non_template (const uint8_t *value, uint8_t sizeOfType, uint8_t numBytes) override
void	invalidateBuffer ()

Private Attributes
void *	userData_ = nullptr
	user data
grk_stream_free_user_data_fn	freeUserDataCallback_
	Pointer to function to free user_data_ (nullptr at initialization) when destroying the stream.
uint64_t	userDataLength_ = 0
	User data length.
StreamCallbacks	callbacks_
uint32_t	status_ = 0
	Stream status flags.
std::unique_ptr< BufferAligned8 >	buf_
	Backing buffer.
std::shared_ptr< ChunkBuffer<> >	chunk_buf_
size_t	bufferedBytes_ = 0
size_t	readBytesSeekable_ = 0
uint64_t	streamOffset_ = 0
GRK_CODEC_FORMAT	format_ = GRK_CODEC_UNK
bool	firstCache_ = true
size_t	originalBufferLength_ = 0
IFetcher *	fetcher_ = nullptr
MemAdvisor *	memAdvisor_ = nullptr

Detailed Description

Manages buffered read/write using callbacks or memory buffer.

For memory buffers, it is possible to perform zero-copy reads where a suitable pointer into the buffer is returned instead of copying into a second buffer.

Note: a memory-mapped file is treated as a memory buffer.

Constructor & Destructor Documentation

◆ BufferedStream()

grk::BufferedStream::BufferedStream	(	uint8_t *	buffer,
		size_t	initial_buffer_size,
		size_t	buffer_size,
		bool	is_input )

inline

Constructs a BufferedStream.

Parameters

buffer	underlying buffer. If null and buffer_size is non-zero, then a new double buffer will be created
initial_buffer_size	initial size of double buffer
buffer_size	size of buffer
is_input	true if this is an input stream

References buf_, grk::grk_aligned_malloc(), GROK_STREAM_STATUS_INPUT, GROK_STREAM_STATUS_OUTPUT, originalBufferLength_, and status_.

Referenced by bifurcate().

◆ ~BufferedStream()

grk::BufferedStream::~BufferedStream ( )

inlineoverride

Destroys a BufferedStream.

References freeUserDataCallback_, memAdvisor_, and userData_.

Member Function Documentation

◆ bifurcate()

IStream * grk::BufferedStream::bifurcate ( void )

inlineoverridevirtual

Implements grk::IStream.

References buf_, bufferedBytes_, BufferedStream(), format_, isMemStream(), grk::memStreamSetup(), streamOffset_, and userData_.

◆ currPtr()

uint8_t * grk::BufferedStream::currPtr ( void )

inlineoverridevirtual

Gets current pointer (used for zero copy).

Returns: current pointer

Implements grk::IStream.

References buf_.

◆ flush()

bool grk::BufferedStream::flush ( )

inlineoverridevirtual

Flushes stream to disk.

Returns: true if the data could be flushed

Implements grk::IStream.

References buf_, bufferedBytes_, callbacks_, grk::grklog, GROK_STREAM_STATUS_ERROR, isMemStream(), status_, and userData_.

Referenced by write_non_template(), writeBytes(), and writeSeek().

◆ getFetcher()

IFetcher * grk::BufferedStream::getFetcher ( void )

inlineoverridevirtual

Gets the IFetcher.

Returns: IFetcher*

Implements grk::IStream.

References fetcher_.

◆ getFormat()

GRK_CODEC_FORMAT grk::BufferedStream::getFormat ( void )

inlineoverridevirtual

Gets codec format (J2K/JP2/MJ2).

Returns: GRK_CODEC_FORMAT

Implements grk::IStream.

References format_.

◆ hasSeek()

bool grk::BufferedStream::hasSeek ( )

inlineoverridevirtual

Checks if stream is seekable.

Returns: true if seekable

Implements grk::IStream.

References callbacks_.

◆ invalidateBuffer()

void grk::BufferedStream::invalidateBuffer ( )

inlineprivate

References buf_, bufferedBytes_, GROK_STREAM_STATUS_INPUT, readBytesSeekable_, and status_.

Referenced by read(), readSeek(), and writeSeek().

◆ isMemStream()

bool grk::BufferedStream::isMemStream ( )

inlineoverridevirtual

Checks if stream is memory stream i.e.

from mapped file or buffer

Returns: true; false

Implements grk::IStream.

References buf_.

Referenced by bifurcate(), flush(), supportsZeroCopy(), write_non_template(), writeBytes(), writeIncrement(), and writeSeek().

◆ memAdvise()

void grk::BufferedStream::memAdvise	(	size_t	virtual_offset,
		size_t	length,
		GrkAccessPattern	pattern )

inlineoverridevirtual

Implements grk::IStream.

References memAdvisor_.

◆ numBytesLeft()

uint64_t grk::BufferedStream::numBytesLeft ( void )

inlineoverridevirtual

Gets the number of bytes left before end of stream.

Returns: number of bytes left before the end of the stream.

Implements grk::IStream.

References streamOffset_, and userDataLength_.

◆ read() [1/2]

size_t grk::BufferedStream::read	(	uint8_t *	buffer,
		size_t	len )

inlineprivate

Reads bytes from stream.

passing in nullptr for buffer will execute a zero-copy read

Parameters

buffer	pointer to the data buffer that will receive the data.
len	number of bytes to read.

Returns: the number of bytes read

References buf_, bufferedBytes_, callbacks_, chunk_buf_, firstCache_, grk::grklog, GROK_STREAM_STATUS_END, GROK_STREAM_STATUS_ERROR, invalidateBuffer(), originalBufferLength_, readBytesSeekable_, readDirect(), status_, streamOffset_, supportsZeroCopy(), userData_, and userDataLength_.

◆ read() [2/2]

size_t grk::BufferedStream::read	(	uint8_t *	buffer,
		uint8_t **	zero_copy_buffer,
		size_t	len )

inlineoverridevirtual

Read bytes.

Do zero copy read if buffer is null

Parameters

buffer	buffer for non-zero-copy read
zero_copy_buffer	buffer for zero-copy read
len	number of bytes

Returns: size_t number of bytes read

Implements grk::IStream.

References buf_, chunk_buf_, and read().

Referenced by read().

◆ readDirect()

size_t grk::BufferedStream::readDirect	(	uint8_t *	buffer,
		size_t	len )

inlineprivate

Reads directly from callback.

Parameters

buffer	buffer
len	number of bytes to read

Returns: size_t number of bytes read

References callbacks_, grk::grklog, GROK_STREAM_STATUS_END, status_, streamOffset_, userData_, and userDataLength_.

Referenced by read().

◆ readSeek()

bool grk::BufferedStream::readSeek ( uint64_t offset )

inlineprivate

Performs absolute seek in read stream.

Parameters

offset absolute offset

Returns: true if successful

References buf_, bufferedBytes_, callbacks_, chunk_buf_, GROK_STREAM_STATUS_END, GROK_STREAM_STATUS_ERROR, invalidateBuffer(), readBytesSeekable_, status_, streamOffset_, userData_, and userDataLength_.

Referenced by readSkip(), and seek().

◆ readSkip()

bool grk::BufferedStream::readSkip ( int64_t len )

inlineprivate

Skip bytes in read stream.

Parameters

len	the number of bytes to skip.

Returns: true if successful

References readSeek(), and streamOffset_.

Referenced by skip().

◆ seek()

bool grk::BufferedStream::seek ( uint64_t offset )

inlineoverridevirtual

Seek bytes from the stream (absolute).

Parameters

offset the number of bytes to skip.

Returns: true if successful, otherwise false

Implements grk::IStream.

References GROK_STREAM_STATUS_INPUT, readSeek(), status_, and writeSeek().

◆ setCallbacks()

void grk::BufferedStream::setCallbacks ( StreamCallbacks & callbacks )

inlineoverridevirtual

Sets callbacks.

Parameters

callbacks StreamCallbacks

Implements grk::IStream.

References callbacks_.

◆ setChunkBuffer()

void grk::BufferedStream::setChunkBuffer ( std::shared_ptr< ChunkBuffer<> > chunkBuffer )

inlineoverridevirtual

Implements grk::IStream.

References bufferedBytes_, chunk_buf_, readBytesSeekable_, and streamOffset_.

◆ setFetcher()

void grk::BufferedStream::setFetcher ( IFetcher * fetcher )

inline

Sets the IFetcher.

Parameters

fetcher IFetcher

References fetcher_.

◆ setFormat()

void grk::BufferedStream::setFormat ( GRK_CODEC_FORMAT format )

inlineoverridevirtual

Stores codec format J2K/JP2/MJ2.

This is needed when deciding what type of code stream object to create based on stream

Parameters

format GRK_CODEC_FORMAT

Implements grk::IStream.

References format_.

◆ setMemAdvisor()

void grk::BufferedStream::setMemAdvisor ( MemAdvisor * advisor )

inline

References memAdvisor_.

◆ setUserData()

void grk::BufferedStream::setUserData	(	void *	data,
		grk_stream_free_user_data_fn	freeUserDataFun,
		uint64_t	len )

inlineoverridevirtual

Sets user data.

Parameters

data	user data
freeUserDataFun	grk_stream_free_user_data_fn used to free data when stream is closed
len	data length (for read stream)

Implements grk::IStream.

References freeUserDataCallback_, userData_, and userDataLength_.

◆ skip()

bool grk::BufferedStream::skip ( int64_t len )

inlineoverridevirtual

Skips bytes in stream.

Parameters

len	number of bytes to skip.

Returns: true if successful

Implements grk::IStream.

References GROK_STREAM_STATUS_INPUT, readSkip(), status_, and writeSkip().

◆ supportsZeroCopy()

bool grk::BufferedStream::supportsZeroCopy ( )

inlineoverridevirtual

Checks is stream supports zero copy.

Returns: true if zero copy supported

Implements grk::IStream.

References GROK_STREAM_STATUS_INPUT, isMemStream(), and status_.

Referenced by read().

◆ tell()

uint64_t grk::BufferedStream::tell ( void )

inlineoverridevirtual

query byte offset of stream (similar to ftell).

Returns: the current position of the stream.

Implements grk::IStream.

References streamOffset_.

◆ write24u()

bool grk::BufferedStream::write24u ( uint32_t value )

inlineoverridevirtual

Writes 3 bytes from uint32_t as big endian.

Parameters

value uint32_t to write

Returns: true if successful

Implements grk::IStream.

References write_non_template().

◆ write8u()

bool grk::BufferedStream::write8u ( uint8_t value )

inlineoverridevirtual

Writes byte.

Endian is NOT taken into account

Parameters

value byte to write

Returns: true if successful

Implements grk::t1_t2::IStreamWriter.

References writeBytes().

◆ write_non_template()

bool grk::BufferedStream::write_non_template	(	const uint8_t *	value,
		uint8_t	sizeOfType,
		uint8_t	numBytes )

inlineoverrideprivatevirtual

Implements grk::t1_t2::IStreamWriter.

References buf_, bufferedBytes_, callbacks_, flush(), grk::grk_write(), GROK_STREAM_STATUS_ERROR, isMemStream(), status_, streamOffset_, userData_, and writeIncrement().

Referenced by write24u().

◆ writeBytes()

size_t grk::BufferedStream::writeBytes	(	const uint8_t *	buffer,
		size_t	len )

inlineoverridevirtual

Writes bytes to stream (no correction for endian!).

Parameters

buffer	pointer to the data buffer holds the data to be written.
len	number of bytes to write.

Returns: number of bytes written

Implements grk::IStream.

References buf_, bufferedBytes_, callbacks_, flush(), GROK_STREAM_STATUS_ERROR, isMemStream(), status_, streamOffset_, userData_, and writeIncrement().

Referenced by write8u().

◆ writeIncrement()

void grk::BufferedStream::writeIncrement ( size_t len )

inlineprivate

References buf_, bufferedBytes_, isMemStream(), and streamOffset_.

Referenced by write_non_template(), and writeBytes().

◆ writeSeek()

bool grk::BufferedStream::writeSeek ( uint64_t offset )

inlineprivate

Performs absolute seek in write stream.

Parameters

offset absolute offset

Returns: true if successful

References buf_, callbacks_, flush(), GROK_STREAM_STATUS_ERROR, invalidateBuffer(), isMemStream(), status_, streamOffset_, and userData_.

Referenced by seek(), and writeSkip().

◆ writeSkip()

bool grk::BufferedStream::writeSkip ( int64_t len )

inlineprivate

Skips bytes in write stream.

Parameters

len	number of bytes to skip.

Returns: true if successful

References streamOffset_, and writeSeek().

Referenced by skip().

Member Data Documentation

◆ buf_

std::unique_ptr<BufferAligned8> grk::BufferedStream::buf_

private

Backing buffer.

Referenced by bifurcate(), BufferedStream(), currPtr(), flush(), invalidateBuffer(), isMemStream(), read(), read(), readSeek(), write_non_template(), writeBytes(), writeIncrement(), and writeSeek().

◆ bufferedBytes_

size_t grk::BufferedStream::bufferedBytes_ = 0

private

Referenced by bifurcate(), flush(), invalidateBuffer(), read(), readSeek(), setChunkBuffer(), write_non_template(), writeBytes(), and writeIncrement().

◆ callbacks_

StreamCallbacks grk::BufferedStream::callbacks_

private

Referenced by flush(), hasSeek(), read(), readDirect(), readSeek(), setCallbacks(), write_non_template(), writeBytes(), and writeSeek().

◆ chunk_buf_

std::shared_ptr<ChunkBuffer<> > grk::BufferedStream::chunk_buf_

private

Referenced by read(), read(), readSeek(), and setChunkBuffer().

◆ fetcher_

IFetcher* grk::BufferedStream::fetcher_ = nullptr

private

Referenced by getFetcher(), and setFetcher().

◆ firstCache_

bool grk::BufferedStream::firstCache_ = true

private

Referenced by read().

◆ format_

GRK_CODEC_FORMAT grk::BufferedStream::format_ = GRK_CODEC_UNK

private

Referenced by bifurcate(), getFormat(), and setFormat().

◆ freeUserDataCallback_

grk_stream_free_user_data_fn grk::BufferedStream::freeUserDataCallback_

private

Pointer to function to free user_data_ (nullptr at initialization) when destroying the stream.

If pointer is nullptr the function is not called and the user_data_ is not freed (even if it isn't nullptr).

Referenced by setUserData(), and ~BufferedStream().

◆ memAdvisor_

MemAdvisor* grk::BufferedStream::memAdvisor_ = nullptr

private

Referenced by memAdvise(), setMemAdvisor(), and ~BufferedStream().

◆ originalBufferLength_

size_t grk::BufferedStream::originalBufferLength_ = 0

private

Referenced by BufferedStream(), and read().

◆ readBytesSeekable_

size_t grk::BufferedStream::readBytesSeekable_ = 0

private

Referenced by invalidateBuffer(), read(), readSeek(), and setChunkBuffer().

◆ status_

uint32_t grk::BufferedStream::status_ = 0

private

Stream status flags.

Referenced by BufferedStream(), flush(), invalidateBuffer(), read(), readDirect(), readSeek(), seek(), skip(), supportsZeroCopy(), write_non_template(), writeBytes(), and writeSeek().

◆ streamOffset_

uint64_t grk::BufferedStream::streamOffset_ = 0

private

Referenced by bifurcate(), numBytesLeft(), read(), readDirect(), readSeek(), readSkip(), setChunkBuffer(), tell(), write_non_template(), writeBytes(), writeIncrement(), writeSeek(), and writeSkip().

◆ userData_

void* grk::BufferedStream::userData_ = nullptr

private

user data

Referenced by bifurcate(), flush(), read(), readDirect(), readSeek(), setUserData(), write_non_template(), writeBytes(), writeSeek(), and ~BufferedStream().

◆ userDataLength_

uint64_t grk::BufferedStream::userDataLength_ = 0

private

User data length.

Currently set to size of file for file read stream, and size of buffer for buffer read/write stream

Referenced by numBytesLeft(), read(), readDirect(), readSeek(), and setUserData().

The documentation for this struct was generated from the following file:

BufferedStream.h

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ BufferedStream()

◆ ~BufferedStream()

Member Function Documentation

◆ bifurcate()

◆ currPtr()

◆ flush()

◆ getFetcher()

◆ getFormat()

◆ hasSeek()

◆ invalidateBuffer()

◆ isMemStream()

◆ memAdvise()

◆ numBytesLeft()

◆ read() [1/2]

◆ read() [2/2]

◆ readDirect()

◆ readSeek()

◆ readSkip()

◆ seek()

◆ setCallbacks()

◆ setChunkBuffer()

◆ setFetcher()

◆ setFormat()

◆ setMemAdvisor()

◆ setUserData()

◆ skip()

◆ supportsZeroCopy()

◆ tell()

◆ write24u()

◆ write8u()

◆ write_non_template()

◆ writeBytes()

◆ writeIncrement()

◆ writeSeek()

◆ writeSkip()

Member Data Documentation

◆ buf_

◆ bufferedBytes_

◆ callbacks_

◆ chunk_buf_

◆ fetcher_

◆ firstCache_

◆ format_

◆ freeUserDataCallback_

◆ memAdvisor_

◆ originalBufferLength_

◆ readBytesSeekable_

◆ status_

◆ streamOffset_

◆ userData_

◆ userDataLength_